Sun Java System Message Queue 3.7 UR1 Administration Guide

Configuring and Using Broker Logging

The Message Queue logger takes information generated by broker code, a debugger, and a metrics generator and writes that information to a number of output channels: to standard output (the console), to a log file, and, on Solaris™ operating systems, to the syslog daemon process.

You can specify the type of information gathered by the logger as well as the type written to each of the output channels. In particular, you can specify that you want metrics information written out to a log file.

This section describes the default logging configuration for the broker and explains how to redirect log information to alternative output channels, how to change log file rollover criteria, and how to send metrics data to a log file.

Default Logging Configuration

A broker is automatically configured to save log output to a set of rolling log files. The log files are located in a directory identified by the instance name of the associated broker (see Appendix A, Platform-Specific Locations of Message QueueTM Data):

…/instances/instanceName/log

Note –

For a broker whose life cycle is controlled by the Application Server, the log files are located in a subdirectory of the domain directory for the domain for which the broker was started:

…/appServer_domainName_dir/imq/instances/imqbroker/log

The log files are simple text files. They are named as follows, from earliest to latest:

log.txt
log_1.txt
log_2.txt
…log_9.txt

By default, log files are rolled over once a week; the system maintains nine backup files.

The broker supports three log levels: ERROR, WARNING , INFO. Table 10–2 explains each level.

Table 10–2 Logging Levels

Level 

Description 

ERROR

Messages indicating problems that could cause system failure. 

WARNING

Alerts that should be heeded but will not cause system failure. 

INFO

Reporting of metrics and other informational messages. 

Setting a logging level gathers messages for that level and all higher levels. The default log level is INFO, so ERROR, WARNING, and INFO messages are all logged by default.

Log Message Format

A logged message consists of a time stamp, message code, and the message itself. The volume of information varies with the log level you have set. The following is an example of an INFO message.


[13/Sep/2000:16:13:36 PDT] [B1004]: Starting the broker service using tcp 
[25374,100] with min threads 50 and max threads of 500

To change the time stamp time zone, see information about the imq.log.timezone property, which is described in Table 14–8.

Changing the Logger Configuration

Log-related properties are described in Table 14–8.

ProcedureTo Change the Logger Configuration for a Broker

  1. Set the log level.

  2. Set the output channel (file, console, or both) for one or more logging categories.

  3. If you log output to a file, configure the rollover criteria for the file.

    You complete these steps by setting logger properties. You can do this in one of two ways:

    • Change or add logger properties in the config.properties file for a broker before you start the broker.

    • Specify logger command line options in the imqbrokerd command that starts the broker. You can also use the broker option -D to change logger properties (or any broker property).

    Options passed on the command line override properties specified in the broker instance configuration files. The following imqbrokerd options affect logging:

    -metrics interval

    Logging interval for broker metrics, in seconds

    -loglevel level

    Logging level (ERROR, WARNING, INFO, or NONE)

    -silent

    Silent mode (no logging to console)

    -tty

    Log all messages to console

    The following sections describe how you can change the default configuration in order to do the following:

    • Change the output channel (the destination of log messages)

    • Change rollover criteria

Changing the Output Channel

By default, error and warning messages are displayed on the terminal as well as being logged to a log file. (On Solaris, error messages are also written to the system’s syslog daemon.)

You can change the output channel for log messages in the following ways:


Note –

Before changing logger output channels, you must make sure that logging is set at a level that supports the information you are mapping to the output channel. For example, if you set the log level to ERROR and then set the imq.log.console.output property to WARNING, no messages will be logged because you have not enabled the logging of WARNING messages.


Changing Log File Rollover Criteria

There are two criteria for rolling over log files: time and size. The default is to use a time criteria and roll over files every seven days.

If you set both the time-related and the size-related rollover properties, the first limit reached will trigger the rollover. As noted before, the broker maintains up to nine rollover files.

You can set or change the log file rollover properties when a broker is running. To set these properties, use the imqcmd update bkr command.

Sending Metrics Data to Log Files

This section describes the procedure for using broker log files to report metrics information. For general information on configuring the logger, see Configuring and Using Broker Logging.

ProcedureTo Use Log Files to Report Metrics Information

  1. Configure the broker’s metrics generation capability:

    1. Confirm imq.metrics.enabled=true

      Generation of metrics for logging is turned on by default.

    2. Set the metrics generation interval to a convenient number of seconds.

      imq.metrics.interval=interval

      This value can be set in the config.properties file or using the -metrics interval command line option when starting up the broker.

  2. Confirm that the logger gathers metrics information:


    imq.log.level=INFO

    This is the default value. This value can be set in the config.properties file or using the -loglevel level command line option when starting up the broker.

  3. Confirm that the logger is set to write metrics information to the log file:


    imq.log.file.output=INFO

    This is the default value. It can be set in the config.properties file.

  4. Start up the broker.

    The following shows sample broker metrics output to the log file:


    [21/Jul/2004:11:21:18 PDT]
    Connections: 0    JVM Heap: 8323072 bytes (7226576 free) Threads: 0 (14-1010)
          In: 0 msgs (0bytes) 0 pkts (0 bytes)
         Out: 0 msgs (0bytes) 0 pkts (0 bytes)
     Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)
    Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)

    For reference information about metrics data, see Chapter 18, Metrics Reference

Logging Dead Messages

You can monitor physical destinations by enabling dead message logging for a broker. You can log dead messages whether or not you are using a dead message queue.

If you enable dead message logging, the broker logs the following types of events:

If a dead message queue is in use, logging also includes the following types of events:

The following is an example of the log format for dead messages:


[29/Mar/2006:15:35:39 PST] [B1147]: Message 8-129.145.180.87(e7:6b:dd:5d:98:aa)-
35251-1143675279400 from destination Q:q0 has been placed on the DMQ because 
[B0053]: Message on destination Q:q0 Expired: expiration time 1143675279402, 
arrival time 1143675279401, JMSTimestamp 1143675279400

Dead message logging is disabled by default. To enable it, set the broker attribute imq.destination.logDeadMsgs.