Sun Java System Message Queue 4.3 Developer's Guide for Java Clients

Client Runtime Logging

This section describes Message Queue 4.0 support for client runtime logging of connection and session-related events.

JDK 1.4 (and above) includes the java.util.logging library. This library implements a standard logger interface that can be used for application-specific logging.

The Message Queue client runtime uses the Java Logging API to implement its logging functions. You can use all the J2SE 1.4 logging facilities to configure logging activities. For example, an application can use the following Java logging facilities to configure how the Message Queue client runtime outputs its logging information:

Logging Handlers
Logging Filters
Logging Formatters
Logging Level

For more information about the Java Logging API, please see the Java Logging Overview at http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

Logging Name Spaces, Levels, and Activities

The Message Queue provider defines a set of logging name spaces associated with logging levels and logging activities that allow Message Queue clients to log connection and session events when a logging configuration is appropriately set.

The root logging name space for the Message Queue client runtime is defined as javax.jms. All loggers in the Message Queue client runtime use this name as the parent name space.

The logging levels used for the Message Queue client runtime are the same as those defined in the java.util.logging.Level class. This class defines seven standard log levels and two additional settings that you can use to turn logging on and off.

OFF: Turns off logging.
SEVERE: Highest priority, highest value. Application-defined.
WARNING: Application-defined.
INFO: Application-defined.
CONFIG: Application-defined
FINE: Application-defined.
FINER: Application-defined.
FINEST: Lowest priority, lowest value. Application-defined.
ALL: Enables logging of all messages.

In general, exceptions and errors that occur in the Message Queue client runtime are logged by the logger with the javax.jms name space.

Exceptions thrown from the JVM and caught by the client runtime, such as IOException, are logged by the logger with the logging name space javax.jms at level WARNING.
JMS exceptions thrown from the client runtime, such as IllegalStateException, are logged by the logger with the logging name space javax.jms at level FINER.
Errors thrown from the JVM and caught by the client runtime, such as OutOfMemoryError, are logged by the logger with the logging name space javax.jms at level SEVERE.

The following tables list the events that can be logged and the log level that must be set to log events for JMS connections and for sessions.

The following table describes log levels and events for connections.

Table 3–6 Log Levels and Events for javax.jms.connection Name Space


Log Level	Events
`FINE`	Connection created
`FINE`	Connection started
`FINE`	Connection closed
`FINE`	Connection broken
`FINE`	Connection reconnected
`FINER`	Miscellaneous connection activities such as `setClientID`
`FINEST`	Messages, acknowledgments, Message Queue action and control messages (like committing a transaction)

For sessions, the following information is recorded in the log record.

Each log record for a message delivered to a consumer includes ConnectionID, SessionID, and ConsumerID.
Each log record for a message sent by a producer includes ConnectionID, SessionID, ProducerID, and destination name.

The table below describes log levels and events for sessions.

Table 3–7 Log Levels and Events for javax.jms.session Name Space


Log Level	Event
`FINE`	Session created
`FINE`	Session closed
`FINE`	Producer created
`FINE`	Consumer created
`FINE`	Destination created
`FINER`	Miscellaneous session activities such as committing a session.
`FINEST`	Messages produced and consumed. (Message properties and bodies are not logged in the log records.)

By default, the output log level is inherited from the JRE in which the application is running. Check the JRE_DIRECTORY/lib/logging.properties file to determine what that level is.

You can configure logging programmatically or by using configuration files, and you can control the scope within which logging takes place. The following sections describe these possibilities.

Using the JRE Logging Configuration File

The following example shows how you set logging name spaces and levels in the JRE_DIRECTORY/lib/logging.properties file, which is used to set the log level for the Java runtime environment. All applications using this JRE will have the same logging configuration. The sample configuration below sets the logging level to INFO for the javax.jms.connection name space and specifies that output be written to java.util.logging.ConsoleHandler.

#logging.properties file.
# "handlers" specifies a comma separated list of log Handler 
# classes. These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.

	handlers= java.util.logging.ConsoleHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers. For any given facility this global level
# can be overriden by a facility-specific level.
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.

    .level= INFO

# Limit the messages that are printed on the console to INFO and above.

    java.util.logging.ConsoleHandler.level = INFO
    java.util.logging.ConsoleHandler.formatter = 
                                    java.util.logging.SimpleFormatter

# The logger with javax.jms.connection name space will write
# Level.INFO messages to its output handler(s). In this configuration 
# the ouput handler is set to java.util.logging.ConsoleHandler.

    javax.jms.connection.level = INFO

Using a Logging Configuration File for a Specific Application

You can also define a logging configuration file from the java command line that you use to run an application. The application will use the configuration defined in the specified logging file. In the following example, configFile uses the same format as defined in the JRE_DIRECTORY/lib/logging.properties file.

java -Djava.util.logging.config.file=configFile MQApplication

Setting the Logging Configuration Programmatically

The following code uses the java.util.logging API to log connection events by changing the javax.jms.connection name space log level to FINE. You can include such code in your application to set logging configuration programmatically.

import java.util.logging.*;
//construct a file handler and output to the mq.log file 
//in the system's temp directory.

    Handler fh = new FileHandler("%t/mq.log");
    fh.setLevel (Level.FINE);

//Get Logger for "javax.jms.connection" domain.

    Logger logger = Logger.getLogger("javax.jms.connection");
    logger.addHandler (fh);

//javax.jms.connection logger would log activities   
//with level FINE and above.

    logger.setLevel (Level.FINE);