Chapter 13 Managing Logging for Instant Messaging

Instant Messaging creates log files that record events, related status of various software components, system errors, and other aspects of the server, multiplexor, Calendar agent, watchdog, and Instant Messenger. By examining the log files, you can monitor many aspects of the server’s operation. This section provides information about logging in the following topics:

• Instant Messaging Logging Overview

• Instant Messaging Log File Location

• Instant Messaging Component Logging Levels

• Managing Instant Messaging Logging Using Log4j

• Configuring Logging for Instant Messaging Components Using iim.conf Parameters

• Administering Logging for Instant Messenger

For information on logging for the XMPP/HTTP Gateway, see Managing Logging for the XMPP/HTTP Gateway. In addition, you can collect logging data for Instant Messenger on demand. See Administering Logging for Instant Messenger for more information.

Instant Messaging Logging Overview

Instant Messaging provides two ways to generate log files; using log4j, or without log4j by specifying parameters in iim.conf. Log4j style logging is available for all server instances including redirect servers, Calendar agent, watchdog, and the XMPP/HTTP Gateway, but not the multiplexor.

For information on logging for the XMPP/HTTP Gateway, see Managing Logging for the XMPP/HTTP Gateway. For information on setting up logging for Instant Messenger see Administering Logging for Instant Messenger.

The iim.conf parameter-based logging mechanism may be deprecated in a future release. Use log4j wherever possible.

You can configure the level of logging for the Instant Messaging server, multiplexor, Calendar agent, watchdog, and XMPP/HTTP Gateway. In addition, using log4j, you can configure Instant Messaging to generate a separate log file for XMPP traffic only.

If you are not using log4j style logging, as part of regular system maintenance, you need to periodically review and trim the log files from occupying more disk space. The server does not perform this action.

For more information about log4j, see the Apache Logging Services website.

Instant Messaging Log File Location

You specify the location of the log files when you run the configure utility after installing Instant Messaging. Typically, log files are stored in im-runtime-base/log. See Instant Messaging Server Directory Structure for information on locating im-runtime-base.

If you are using log4j for log file generation in your deploymentthe logger will also use the directory you specify during configuration as the base directory in which to store log4j logs.

Instant Messaging Component Logging Levels

The level or priority of maintaining the error log defines how detailed, or verbose, the log should be. A higher priority level implies less details as only events of high priority (high severity) are recorded in the log file. In contrast a lower priority level implies greater details as more events are recorded in the log file.

Regardless of whether you are using log4j or parameter-based logging, you can set the logging level separately for each component.

Table 13–1 describes the logging levels for the components. These logging levels are a subset of the levels defined by the UNIX syslog facility.

When you select a particular logging level, events corresponding to that level and to all higher and less verbose levels are logged.

INFO is the default level for the server. ERROR is the default level for the multiplexor, Calendar agent, and watchdog log files.

If you are not using log4j, and you specify DEBUG as the logging level, your log files will occupy more disk space. Monitor and trim your log files to prevent them from occupying more disk space.

Managing Instant Messaging Logging Using Log4j

When you install Instant Messaging, a template file (log4j.conf.template) for the log4j configuration file is installed into the im-svr-base/lib directory. When you run the configure utility after installation, the template is used to create the log4j configuration file (log4j.conf) in the im-cfg-base directory. This configuration file is used to determine where to store log files generated by log4j, the logging level to use for various components, the output syntax, and to determine what log files to generate.

This section describes using the log4j logger to generate log files for Instant Messaging in the following sections:

• Instant Messaging Log4j Configuration File (log4j.conf) Location

• Instant Messaging Log4j Log File Syntax

• Log4j Log Levels for Instant Messaging Components

• To Specify the Location of the Log4j Configuration File (Log4j.conf)

• To Enable or Disable Log4j Logging for an Instant Messaging Component

• To Set Log4j Log Levels for Instant Messaging

• To Specify the Maximum Log4j Log File Size for Instant Messaging Components

The logging levels described in Instant Messaging Component Logging Levels are used by the log4j logger.

For more information about log4j, and instructions on configuring aspects of log files, such as size, number of backups, etc., see the Apache Logging Services website.

Instant Messaging Log4j Configuration File (log4j.conf) Location

You can change the location of the log4j configuration file, log4j.conf, by modifying the iim.log4j.config parameter in iim.conf. If you do not specify a value for this parameter, the logger will look in im-cfg-base. If the logger does not find the log4j configuration file in that directory, it uses the logging parameters in iim.conf to generate non-log4j style logs.

See Instant Messaging Server Directory Structure for information on locating im-cfg-base.

Instant Messaging Log4j Log File Syntax

The configure utility generates the log4j configuration file (log4j.conf) based on the content of the log4j configuration file template (log4j.conf.template). Example 13–1 shows the log4j template. In this template:

• ${logdir} corresponds to the directory you specified during configuration in which you want to store log files. See Instant Messaging Log File Location.

• Each component's log configuration section starts with the following text:

  log4j.logger.

  Where:

  xmppd

  Generates xmppd.log which contains logging information for the server.

  iim_wd

  Generates wd.log which contains information for the watchdog

  xmppd.xfer

  Generates xfer.log which contains only for XMPP traffic.

  agent-calendar

  Generates logging information for the Calendar agent.

  net.outer_planes.jso.BasicStream

  Generates jso.log which contains information for Jabber stream objects. See the Jabber Stream Objects website for more information.

  genredirect

  Generates genredirect.log which contains information for the redirect database creation tool.

• A#, for example A1, are appender IDs.

Example 13–1 Log4j Template File

log4j.logger.xmppd=INFO, A1
# DEFAULT TO RollingFileAppender
log4j.appender.A1=org.apache.log4j.RollingFileAppender
log4j.appender.A1.file=${logdir}/xmppd.log
log4j.appender.A1.append=true
log4j.appender.A1.maxBackupIndex=7
log4j.appender.A1.maxFileSize=5mb
# More example appenders..
# Straight to console..
# log4j.appender.A1=org.apache.log4j.ConsoleAppender
# log4j.appender.A1.ImmediateFlush=true
# Rollover at midnight..
# log4j.appender.A1=org.apache.log4j.DailyRollingFileAppender
# log4j.appender.A1.DatePattern='.'yyyy-MM-dd
# log4j.appender.A1.file=${logdir}/xmppd.log
# log4j.appender.A1.ImmediateFlush=true
# log4j.appender.A1.append=true
# Send to SMTP..
# log4j.appender.A1=org.apache.log4j.SMTPAppender

# PATTERN LAYOUT AND OPTIONS
# DEFAULT TO PatternLayout
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
# For full dates..
log4j.appender.A1.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n
# IM traditional output format..
#log4j.appender.A1.layout.ConversionPattern=%d{HH:mm:ss,SSS} %-5p %c [%t] %m%n
# More example layouts
# XMLLayout for chainsaw consumption
# log4j.appender.A1.layout=org.apache.log4j.xml.XMLLayout
# TTCCLayout for NDC information

# log4j.appender.A1.layout=org.apache.log4j.xml.TTCCLayout
# log4j.appender.A1.layout.DateFormat=ISO8601
# log4j.appender.A1.layout.TimeZoneID=GMT-8:00
# log4j.appender.A1.layout.CategoryPrefixing=false
# log4j.appender.A1.layout.ThreadPrinting=false
# log4j.appender.A1.layout.ContextPrinting=false

# Now we list logger/appender/layout for the other default loggers, but
# only the defaults..
log4j.logger.iim_wd=ERROR, A2
log4j.appender.A2=org.apache.log4j.RollingFileAppender
log4j.appender.A2.file=${logdir}/iim_wd.log
log4j.appender.A2.append=true
log4j.appender.A2.maxBackupIndex=7
log4j.appender.A2.maxFileSize=5mb
log4j.appender.A2.layout=org.apache.log4j.PatternLayout
log4j.appender.A2.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n

# For separate xmpp traffic log, disabled by default.
log4j.logger.xmppd.xfer=DEBUG, A3
log4j.appender.A3=org.apache.log4j.varia.NullAppender
# Select next block instead of previous line to enable separate transfer log
# log4j.appender.A3=org.apache.log4j.RollingFileAppender
# log4j.appender.A3.file=${logdir}/xfer.log
# log4j.appender.A3.append=true
# log4j.appender.A3.maxBackupIndex=7
# log4j.appender.A3.maxFileSize=5mb
# log4j.appender.A3.layout=org.apache.log4j.PatternLayout
# # Note, simpler default output than above 3 loggers:
# log4j.appender.A3.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n

log4j.logger.agent-calendar=ERROR, A4
log4j.appender.A4=org.apache.log4j.RollingFileAppender
log4j.appender.A4.file=${logdir}/agent-calendar.log
log4j.appender.A4.append=true
log4j.appender.A4.maxBackupIndex=7
log4j.appender.A4.maxFileSize=5mb
log4j.appender.A4.layout=org.apache.log4j.PatternLayout
log4j.appender.A4.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n

log4j.logger.net.outer_planes.jso.BasicStream=OFF, A5
log4j.appender.A5=org.apache.log4j.RollingFileAppender
log4j.appender.A5.file=${logdir}/jso.log
log4j.appender.A5.append=true
log4j.appender.A5.maxBackupIndex=7
log4j.appender.A5.maxFileSize=5mb
log4j.appender.A5.layout=org.apache.log4j.PatternLayout
log4j.appender.A5.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n

log4j.logger.genredirect=INFO, A6
log4j.appender.A6=org.apache.log4j.RollingFileAppender
log4j.appender.A6.file=${logdir}/genredirect.log
log4j.appender.A6.append=true
log4j.appender.A6.maxBackupIndex=7
log4j.appender.A6.maxFileSize=5mb
log4j.appender.A6.layout=org.apache.log4j.PatternLayout
log4j.appender.A6.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n

Log4j Log Levels for Instant Messaging Components

The log4j logger uses the same logging levels described for the iim.conf parameter-based logging mechanism in Instant Messaging Component Logging Levels.

To Specify the Location of the Log4j Configuration File (Log4j.conf)

1. Open iim.conf.

   See iim.conf File Location for information on locating this file.

2. Set the iim.log4j.config parameter to the path in which you want the logger to look for log4j.conf.

   For example, on Solaris:

   iim.log4j.config=/etc/opt/SUNWiim/default/config/log4j.conf

   On Linux:

   iim.log4j.config=/etc/opt/sun/im/default/config/log4j.conf

3. Save and close iim.conf.

4. Refresh the server.

   imadmin refresh

To Enable or Disable Log4j Logging for an Instant Messaging Component

By default, log4j logging is used for all components for which logging information is generated.

1. To disable log4j logging, set the logging level for the component to OFF in both log4j.conf and log4j.conf.template.

   See To Set Log4j Log Levels for Instant Messaging for more information.

2. To enable log4j logging, set the logging level for the component to any logging level other than OFF in both log4j.conf and log4j.conf.template.

To Set Log4j Log Levels for Instant Messaging

You can set log levels by modifying either the template or the log configuration file. However, if you only modify the configuration file, any changes you make will be overwritten the next time you run configure. To prevent this, you should make your changes to both the configuration file and the template.

1. Open log4j.conf.template.

   By default, this file is stored in the following location:

   im-svr-base/lib

2. For each component, specify the logging level you want to use.

   For example, to set the log level for the server:

   log4j.logger.xmppd=log-level

   Where log-level is one of FATAL, ERROR, WARNING, INFO, or DEBUG.

   See Table 13–1 for detailed information on each of these logging levels.

3. Save and close log4j.conf.template.

4. Repeat the procedure for the configuration file log4j.conf.

To Specify the Maximum Log4j Log File Size for Instant Messaging Components

You can set log levels by modifying either the template or the log configuration file. However, if you only modify the configuration file, any changes you make will be overwritten the next time you run configure. To prevent this, you should make your changes to both the configuration file and the template.

1. Open log4j.conf.template.

   By default, this file is stored in the following location:

   im-svr-base/lib

2. For each component, specify the maximum size for the component's log file.

   For example, to set the size for the server log file:

   log4j.appender.A1.maxFileSize=max-logfile-size

   Where A1 is the default appender ID for the server, max-logfile-size is in MB, for example 5MB.

3. Repeat the procedure for the configuration file log4j.conf.

Configuring Logging for Instant Messaging Components Using iim.conf Parameters

If you are not using log4j to generate log files, you need to set a configuration parameter specific to each component for which you want Instant Messaging to generate logging information. This method is referred to as parameter-based logging for Instant Messaging. You can use parameter-based logging for all server instances including redirect servers, multiplexor, calendar-agent, and watchdog.

This iim.conf parameter-based logging mechanism may be deprecated in a future release. Use log4j when possible.

Table 13–2 provides the name of the log files and the configuration parameter in iim.conf used to set the logging level for each Instant Messaging component log file.

The configuration parameters can have the following values:

• fatal

• error

• warning

• info

• debug

See Instant Messaging Component Logging Levels for information on the details logged for each logging level.

In addition, logging configuration in deployments with Sun Java^TM System Access Manager is determined by the com.iplanet.services.debug.level property. You set this property in the AMConfig.properties file on the Sun Java System Access Manager host. By default, this file is installed in the following location:

AM-svr-base/lib/AMConfig.properties

Where AM-svr-base is the directory in which you installed Access Manager.

This property can contain the following values:

• message

• warning

• error

• off

By default, the Sun Java System Portal Server desktop log file (desktop.debug) and archive log files (IMArchiveSearch.log and IMArchiveSubmit.log) are stored in the following locations:

• Solaris: /var/opt/SUNWam/debug

• Linux: /var/opt/sun/am/debug

To Set Log Levels for Instant Messaging Components Using iim.conf Parameters

1. Modify logging parameters in iim.conf.

   See Table 13–2 for a list of the log files and the associated parameter you need to set for each component.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf. For more information on the watchdog, see Managing the Watchdog Process. For more information on the Calendar agent, see Chapter 16, Using Calendar Pop-up Reminders.

Administering Logging for Instant Messenger

By default, Instant Messenger data is not logged. You may be asked to collect client data during a support call. In this situation, you will need to enable logging before you can view client log data.

Instant Messenger logs are created on demand and stored in the user's home directory (usr_home/.sunmsgr/messenger.log).

Setting Up Logging for Instant Messenger

To set up logging for Instant Messenger you will need to:

1. Determine the type of data you want to collect.

2. Modify im.jnlp to include the logconfig parameter.

3. Specify a type for the logconfig parameter based on the type of data you want to collect.

4. Redeploy the resource files.

To Enable Logging for Instant Messenger

1. Make a backup copy of im.jnlp.

2. Open the im.jnlp Instant Messenger resource file in a text editor.

3. Search for the line:

   <application-desc main-class="com.iplanet.im.client.iIM">

4. Add the following argument to the end of the section:

   <argument>logconfig=type</argument>

   Where type is one of ALL, API, XMPPTRAFFIC, or CLIENT. See Instant Messenger Log File Content Options for details.

5. Save and close the im.jnlp file.

6. If you are using Sun Java System Application Server or Sun Java System Web Server, redeploy the resource files as described in Redeploying Resource Files.

7. Relaunch Instant Messenger.

8. Locate the log file.

   By default the log file is stored as usr_home/.sunmsgr/messenger.log.

Next Steps

You should revert back to the backup copy of im.jnlp when you have finished troubleshooting Instant Messenger. Then, redeploy the resource files as described in Redeploying Resource Files.

Locating the Instant Messenger Log File (messenger.log)

By default, the Instant Messenger log file is stored as messenger.log under the user's home directory as follows:

/usr_home/.sunmsgr/messenger.log

Instant Messenger Log File Content Options

You can determine what activity you want logged in messenger.log by specifying a value for the logconfig parameter in im.jnlp. Table 13–3 describes the configuration parameters for logconfig. See To Enable Logging for Instant Messenger for instructions on setting the logconfig parameter and generating Instant Messenger logs.