Chapter 19 Configuring Logging

This chapter briefly describes how to configure logging and view the server log. It contains the following sections:

• About Logging

• Configuring Logging

About Logging

• Log Records

• Module Log Levels

Log Records

The Communications Server uses the Java EE platform Logging API specified in JSR 047. Communications Server logging messages are recorded in the server log, normally found at domain-dir/logs/server.log. When a log is rotated, Communications Server creates a new, empty file named server.log and renames the old file server.log_date, where date is the date and time when the file was rotated.

The components of the Communications Server generate logging output. Application components can also generate logging output.

Application components may use the Apache Commons Logging Library to log messages. The platform standard JSR 047 API, however, is recommended for better log configuration.

Log records follow a uniform format:

[#|yyyy-mm-ddThh:mm:ss.SSS-Z|Log Level|ProductName-Version|LoggerName|Key Value Pairs|Message|#]

For example:

[#|2006-10-21T13:25:53.852-0400|INFO|sun-appserver9.1|javax.enterprise.
system.core|_ThreadID=13;|CORE5004: Resource Deployed: 
[cr:jms/DurableConnectionFactory].|#]

In this example,

• [# and #] mark the beginning and end of the record.

• The vertical bar (|) separates the record fields.

• 2006-10-21T13:25:53.852-0400 specifies the date and time.

• The Log Level is INFO. This level may have any of the following values: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST.

• The ProductName-Version is sun-glassfish-comms-server2.0.

• The LoggerName is a hierarchical logger namespace that identifies the source of the log module, in this case javax.enterprise.system.core.

• The Key Value Pairs are key names and values, typically a thread ID such as _ThreadID=14;.

• The Message is the text of the log message. For all Communications Server SEVERE and WARNING messages and many INFO messages, it begins with a message ID that consists of a module code and a numerical value (in this case, CORE5004).

The log record format might be changed or enhanced in future releases.

Module Log Levels

The Communications Server provides a logger for each of its modules.

asadmin> get server-config.log-service.module-log-levels.*
server-config.log-service.module-log-levels.admin = INFO
server-config.log-service.module-log-levels.classloader = INFO
server-config.log-service.module-log-levels.cmp = INFO
server-config.log-service.module-log-levels.cmp-container = INFO
server-config.log-service.module-log-levels.configuration = INFO
server-config.log-service.module-log-levels.connector = INFO
server-config.log-service.module-log-levels.corba = INFO
server-config.log-service.module-log-levels.deployment = INFO
server-config.log-service.module-log-levels.ejb-container = INFO
server-config.log-service.module-log-levels.group-management-service = INFO
server-config.log-service.module-log-levels.javamail = INFO
server-config.log-service.module-log-levels.jaxr = INFO
server-config.log-service.module-log-levels.jaxrpc = INFO
server-config.log-service.module-log-levels.jdo = INFO
server-config.log-service.module-log-levels.jms = INFO
server-config.log-service.module-log-levels.jta = INFO
server-config.log-service.module-log-levels.jts = INFO
server-config.log-service.module-log-levels.management-event = INFO
server-config.log-service.module-log-levels.mdb-container = INFO
server-config.log-service.module-log-levels.naming = INFO
server-config.log-service.module-log-levels.node-agent = INFO
server-config.log-service.module-log-levels.property.ar = INFO
server-config.log-service.module-log-levels.property.clb = INFO
server-config.log-service.module-log-levels.property.sip = INFO
server-config.log-service.module-log-levels.property.smi = INFO
server-config.log-service.module-log-levels.property.ssr = INFO
server-config.log-service.module-log-levels.resource-adapter = INFO
server-config.log-service.module-log-levels.root = INFO
server-config.log-service.module-log-levels.saaj = INFO
server-config.log-service.module-log-levels.security = INFO
server-config.log-service.module-log-levels.self-management = INFO
server-config.log-service.module-log-levels.server = INFO
server-config.log-service.module-log-levels.synchronization = INFO
server-config.log-service.module-log-levels.util = INFO
server-config.log-service.module-log-levels.verifier = INFO
server-config.log-service.module-log-levels.web-container = INFO

Configuring Logging

This section contains the following topics:

• Configuring General Logging Settings

• Configuring Log Levels

• SIP Message Inspection

• Viewing Server Logs

Configuring General Logging Settings

To configure the general logging settings using the Admin Console:

• For the developer profile, go to Application Server -> Logging -> General

• For the cluster profile, go to Configurations -> Configuration -> Logging Settings -> General

On the General page, enter appropriate values to customize logging to your requirements. Stop and restart the Communications Server.

For details on setting the various configuration parameters, click Help in the Admin Console.

To configure these log settings in asadmin, use the get and set commands.

Configuring Log Levels

To configure log levels using the Admin Console:

• For the developer profile, go to Application Server -> Logging -> Log Levels

• For the cluster and enterprise profiles, go to Configurations -> Configuration -> Logging -> Logging Settings -> Log Levels

Set the log level for the modules listed on this page. Use the Additional Properties area to configure log levels for any application loggers. For a list of the module loggers, see Module Log Levels.

For details on setting the various configuration parameters, click Help in the Admin Console.

To configure these log settings in asadmin, use the get and set commands.

For example, to set the logging level of the SIP container to FINE, use the following set command:

asadmin set server-config.log-service.module-log-levels.property.sip=FINE

SIP Message Inspection

SIP Message Inspection feature helps troubleshoot SIP traffic through Communications Server. It is activated by setting the SMI log domain to level FINE.

To Activate SIP Message Inspection Using the Admin Console

1. Open the Admin Console in a browser.

2. For the developer profile, go to Application Server -> Logging -> Log Levels. For the cluster profile, go to Configurations -> Configuration -> Logging -> Logging Settings -> Log Levels.

3. In the Log Levels page, in the Additional Properties section, set the smi proerty to FINE.

To Activate SIP Message Inspection Using the Admin CLI

1. Open the asadmin utility in a terminal window.

2. Use the following command:

   asadmin set server-config.log-service.module-log-levels.property.smi=FINE

Viewing Server Logs

To view the log files:

• In the developer profile, go to Applications Server -> Logging -> View Log Files.

• In the cluster and enterprise profiles, go to Configurations -> Configuration -> Logger Settings -> General, and click View Log Files.

Use the options provided in the Search Criteria area to display log results based on your preferences.

• Instance Name — Choose an instance name from the drop-down list to view the log for that server instance. The default is the current server instance.

• Log File — Choose a log file name from the drop-down list to view the contents of that log. The default is server.log.

• Timestamp — To view the most recent messages, select Most Recent (the default). To view messages only from a certain period of time, select Specific Range and type a date and time value in the From and To fields that appear. For the Time value, the syntax must take the following form (SSS stands for milliseconds):

  hh:mm:ss.SSS

  For example:

  17:10:00.000

  If the From value is later than the To value, an error message appears.

• Log Level — To filter messages by log level, choose a log level from the drop-down list. By default, the display includes all messages that appear in the server log at the chosen log level and more severe levels. Select the checkbox labeled “Do not include more severe messages” to display messages at only the chosen level.

  To ensure that the messages you want to view appear in the server log, first set the appropriate log levels on the Log Levels page. See Configuring Log Levels.

  If you choose to filter log messages based on log level, only messages matching the specified filter criteria are shown. However, this filtering does not affect which messages are logged to the server log.

  The most recent 40 entries in the server log appear, with the settings specified on the Logging Settings and Log Levels pages.

  Click the arrow next to the Timestamp header to sort the messages so that the most recent one appears last.

  To view a formatted version of any message, click the link marked

  (details)

  A window labeled Log Entry Detail appears, with a formatted version of the message.

  At the end of the list of entries, click the buttons to view earlier or later entries in the log file.

  Click Advanced Search in the Search Criteria area to make additional refinements to the log viewer. Use the Advanced Options fields as follows:

• Logger — To filter by module, choose one or more namespaces from the drop-down list. Use shift-click or control-click to choose multiple namespaces.

  Selecting a namespace at a higher level selects all the namespaces below it. For example, selecting javax.enterprise.system also selects the loggers for all the modules under that namespace: javax.enterprise.system.core, javax.enterprise.system.tools.admin, and so on.

• Custom Logger — To view messages from loggers specific to a particular application, type the logger names in the text field, one per line. If the application has several modules, you can view any or all of them. For example, suppose the application has loggers with the following names:

  com.mycompany.myapp.module1 com.mycompany.myapp.module2 com.mycompany.myapp.module3

  To view messages from all modules in the application, type com.mycompany.myapp. To view messages from module2 only, type com.mycompany.myapp.module2.

  When you specify one or more custom loggers, messages from Communications Server modules appear only if you specify them explicitly in the Logger area.

• Name-Value Pairs — To view output from a specific thread, type the key name and value for that thread in the text field. The key name is _ThreadID. For example:

  _ThreadID=13

  Suppose that com.mycompany.myapp.module2 runs in several threads. To refine the log viewer to show only the output from a single thread, specify that module’s logger in the Custom Logger field, and then specify the thread ID in this field.

• Display — To view more than 40 messages at a time (the default), choose another of the available values from the drop-down list (100, 250, or 1000).

  To view stack traces, deselect the “Limit excessively long messages” checkbox. By default, stack traces do not appear in the viewer; to view them, click the (details) link for a message.

  Click Basic Search to hide the Advanced Options area.