Chapter 7 Administering the Logging Service

This chapter provides instructions on how to configure logging and how to view log information in the Sun GlassFish^TM Enterprise Server v3 environment.

The following topics are addressed here:

• About Logging

• Setting Log Levels

• Rotating the Server Log

• Viewing Log Information

Instructions for accomplishing these tasks and also for editing properties by using the Administration Console are contained in the Administration Console online help.

About Logging

Logging is the process by which Enterprise Server captures information about events that occur during server operation, such as configuration errors, security failures, or server malfunction. This data is recorded in a log file, and is usually the first source of information when problems occur. Analyzing the log files can help you to determine the health of the server.

Although application components can use the Apache Commons Logging Library to record messages, the platform standard JSR 047 API is recommended for better log configuration.

The following topics are addressed here:

• Log File

• Logger Namespaces

Log File

Enterprise Server log records are captured in the server log. The server log is named server.log by default and is typically located in domain-dir/logs. You can change the default name or location of the server log by using the Administration Console.

In addition to the server log, the domain-dir/logs directory contains the following additional logs:

• HTTP service access logs, located in the /access subdirectory

• Transaction service logs, located in the /tx subdirectory

When the server log reaches the specified size in bytes, the log is rotated and renamed with a timestamp name to server.log_date, where date is the date and time that the file was rotated. You can also rotate this log manually by following instructions in Rotating the Server Log.

Enterprise Server log records follow a uniform format:

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

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

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

• yyyy-mm-ddThh:mm:ss.SSSS-Z specifies the date and time that the record was created. For example: 2006-10-21T13:25:53.852-0400

• Log Level specifies the desired log level. You can select any of the following values: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. The default is INFO.

• ProductName-Version refers to the current version of the Enterprise Server. For example: glassfish

• LoggerName is a hierarchical logger namespace that identifies the source of the log module. For example: javax.enterprise.system.core

• Key Value Pairs refers to pairs of key names and values, typically a thread ID. For example: _ThreadID=14;

• Message is the text of the log message. For all Enterprise Server SEVERE and WARNING messages and for many INFO messages, the message begins with a message ID that consists of a module code and a numerical value. For example: CORE5004

An example log record might look like this:

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

The Administration Console presents log records in a more readable display.

Logger Namespaces

You can use the list-logger-levels(1) subcommand to list the existing loggers for the modules. Example loggers:

javax.enterprise.system.container.cmp: INFO
javax.enterprise.system.tools.admin: INFO
javax.enterprise.system.container.web: INFO
javax.enterprise.system.util: INFO
javax.enterprise.resource.webcontainer.jsf.timing: INFO
javax: INFO
javax.enterprise.resource.corba: INFO
javax.enterprise.system.core.naming: INFO
javax.enterprise.system.core.selfmanagement: INFO
javax.enterprise.system.container.ejb: INFO
javax.enterprise.resource.webcontainer.jsf.config: INFO
javax.enterprise.resource.javamail: INFO
org.apache.catalina: INFO
javax.enterprise.system.core.config: INFO
javax.enterprise.system.webservices.rpc: INFO
javax.enterprise.system.webservices.registry: INFO
javax.enterprise.system.tools.deployment: INFO
javax.enterprise.resource.jms: INFO
javax.enterprise.system: INFO
javax.enterprise.system.webservices.saaj: INFO
org.apache.jasper: INFO
javax.enterprise.resource.webcontainer.jsf.lifecycle: INFO
javax.enterprise.resource.jta: INFO
javax.enterprise.resource.jdo: INFO
javax.enterprise.resource.resourceadapter: INFO
javax.enterprise.system.core.transaction: INFO
javax.enterprise.resource.webcontainer.jsf.resource: INFO
javax.enterprise.system.core.security: INFO
javax.enterprise.resource.webcontainer.jsf.application: INFO
javax.enterprise.system.core.classloading: INFO
org.apache.coyote: INFO
javax.enterprise.resource.webcontainer.jsf.managedbean: INFO
javax.enterprise.system.container.ejb.mdb: INFO
javax.enterprise.resource.webcontainer.jsf.context: INFO
javax.enterprise.resource.webcontainer.jsf.renderkit: INFO
javax.enterprise.resource.webcontainer.jsf.facelets: INFO
javax.enterprise.resource.webcontainer.jsf.taglib: INFO

Setting Log Levels

The log level determines the granularity of the message that is logged, from error only (SEVERE) to detailed debug (FINEST). The following values apply: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. These log levels are hierarchically inclusive, which means that if you set a particular log level, such as INFO, the messages that have log levels above that level (SEVERE and WARNING) are also included. If you set the log level to the lowest level, FINEST, your output will include all the messages in the file. The default setting is INFO.

There are two levels of log settings available: global and logger-specific. If you have chosen a logger-specific setting that is different from the global setting, the logger-specific setting takes precedence.

Setting the global log level is done by editing the logging.properties file. Logging levels for the individual modules are set by using the asadmin subcommands as explained in this section

Setting Log Levels

Because setting log levels is a dynamic operation, you do not need to restart Enterprise Server for changes to take effect.

The following topics are addressed here:

• To List the Logger Levels

• To Set the Global Log Level

• To Set Module Logger Levels

To List the Logger Levels

Use the list-logger-levels subcommand in remote mode to list the modules and their current log levels.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List the existing module loggers by using the list-logger-levels(1) subcommand.

Example 7–1 Listing Logger Levels for Modules

This example shows a partial list of the existing loggers and indicates how their log levels are set.

asadmin> list-logger-levels
javax.enterprise.system.container.cmp: INFO
javax.enterprise.system.tools.admin: INFO
java.util.logging.ConsoleHandler: FINEST
javax.enterprise.system.container.web: INFO
javax.enterprise.system.util: INFO
javax.enterprise.resource.webcontainer.jsf.timing: INFO
javax: INFO
javax.enterprise.resource.corba: INFO
...
Command list-logger-levels executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-logger-levels at the command line.

To Set the Global Log Level

The global log level specifies which kinds of events are logged across all loggers. The default level for message output to the console is INFO (which also includes SEVERE and WARNING messages).

You configure global logging by editing the logging.properties file. The default logging.properties file is located in the same directory as the domain.xml file, typically domain-dir/config. You can choose a different file name by using the java.util.logging.config.file system property to specify a file name. For example:

java -Djava.util.logging.config.file=myfile

The ConsoleHandler has a separate log level setting that limits the messages that are displayed. For example:

java.util.logging.ConsoleHandler.level = INFO 
java.util.logging.ConsoleHandler.formatter = 
com.sun.enterprise.server.logging.UniformLogFormatter

1. In a text editor, find the ConsoleHandler log level line and make your changes.

2. Save the file.

Example 7–2 Changing the Global Log Level for All Loggers

If you set the log level at the root level, you are setting the level of all loggers. This example sets the log level for all loggers to INFO:

.level= INFO

To Set Module Logger Levels

A module log level specifies which kinds of events are logged for a particular logger. The default level for message output to the console is INFO (which also includes SEVERE and WARNING messages). The global log level is overridden by a module-specific log level.

By default, the module log level is set to FINE. The lines for the loggers might look like this (the modules are indicated in bold):

#javax.enterprise.system.tools.level=FINE
#javax.enterprise.system.container.ejb.level=FINE
#javax.enterprise.system.core.security.level=FINE
#javax.enterprise.system.tools.admin.level=FINE
#javax.enterprise.level=FINE
#javax.enterprise.system.container.web.level=FINE

Because setting log levels is a dynamic operation, you do not need to restart Enterprise Server for changes to take effect.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List the existing module loggers by using the list-logger-levels(1) subcommand.

3. Set the log level for a module by using the set-log-level(1) subcommand.

   Your choices are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST.

Example 7–3 Setting the Log Level for a Module Logger

This example sets the log level for the web container logger to FINE.

asadmin> set-log-level javax.enterprise.system.container.web.level=FINE
Command set-log-level executed successfully.

Example 7–4 Setting Log Levels for Multiple Loggers

This example sets the log level for security and web container loggers.

asadmin> set-log-level javax.enterprise.system.core.security.level=FINE
javax.enterprise.system.container.web=WARNING 
Command set-log-level executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help set-log-level at the command line.

Rotating the Server Log

Logs are rotated automatically based on settings in the logging.properties file. You can change these settings by using the Administration Console.

To Rotate a Log File Manually

You can rotate the server log file manually by using the rotate-log subcommand in remote mode. The server log in the default location is immediately moved to a time-stamped file and a new server log is created.

Because log rotation is a dynamic operation, you do not need to restart Enterprise Server for changes to take effect.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Rotate a log by using the rotate-log(1) subcommand.

Example 7–5 Rotating a Log File Manually

This example moves the server.log file to yyyy-mm-dd_server.log and creates a new server.log file in the default location.

asadmin> rotate-log
Command rotate-log executed successfuly.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help rotate-log at the command line.

Viewing Log Information

By default, all logging information is captured in the server.log file, typically located in domain-dir/logs. You can view logging information by using the Log Viewer in the Administration Console. Instructions for using the Administration Console logging functions are contained in the Administration Console online help.

To view information that has been collected for a module, you can open the server.log file in a text editor and search for the module that you are interested in.