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 platforms, to the syslog daemon process.
You can specify the type of information gathered by the Logger as well as
the type of information the Logger writes to each of the output channels.
For example, you can specify that you want metrics information written out
to a log file.

This section describes the configuration and use of the Logger for monitoring
broker activity. It includes the following topics:

Logger Properties

The imq.log.file.dirpath and imq.log.file.filename broker properties identify the log file to use and the imq.log.console.stream property specifies whether console output is directed to stdout or stderr.

The imq.log.level property controls the categories
of metric information that the Logger gathers: ERROR, WARNING, or INFO. Each level includes those above
it, so if you specify, for example, WARNING as the logging
level, error messages will be logged as well.

There is also an imq.destination.logDeadMsgs property
that specifies whether to log entries when dead messages are discarded or
moved to the dead message queue.

The imq.log.console.output and imq.log.file.output properties control which of the specified categories the Logger
writes to the console and the log file, respectively. In this case, however,
the categories do not include those above them; so if
you want, for instance, both errors and warnings written to the log file and
informational messages to the console, you must explicitly set imq.log.file.output to ERROR|WARNING and imq.log.console.output to INFO.

On Solaris platforms another property, imq.log.syslog.output,
specifies the categories of metric information to be written to the syslog daemon.

In the case of a log file, you can specify the point at which the file
is closed and output is rolled over to a new file. Once the log file reaches
a specified size (imq.log.file.rolloverbytes) or age (imq.log.file.rolloversecs), it is saved and a new log file created.

See Monitoring Properties for additional
broker properties related to logging and subsequent sections for details about
how to configure the Logger and how to use it to obtain performance information.

Log Message Format

A logged message consists of a time stamp, a message code, and
the message itself. The volume of information included varies with the logging level you have set. The broker supports three logging
levels: ERROR, WARNING , and INFO (see Table 13–2). Each level includes those
above it (for example, WARNING includes ERROR).

Table 13–2 Logging Levels

Logging Level

Description

ERROR

Serious problems that could cause system failure

WARNING

Conditions that should be heeded but will not cause system failure

INFO

Metrics and other informational messages

The default logging level is INFO, so messages at
all three levels are logged by default. 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

You can change the time zone used in the time stamp by setting the broker
configuration property imq.log.timezone (see Table 17–11).

Changing the Logging Configuration

To Change the Logger Configuration for a Broker

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

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:

To have all log categories (for a given
level) output displayed on the screen, use the -tty option
to the imqbrokerd command.

To prevent log output from being displayed on the screen,
use the -silent option to the imqbrokerd command.

Use the imq.log.file.output property to
specify which categories of logging information should be written to the log
file. For example,

imq.log.file.output=ERROR

Use the imq.log.console.output property
to specify which categories of logging information should be written to the
console. For example,

imq.log.console.output=INFO

On Solaris, use the imq.log.syslog.output property
to specify which categories of logging information should be written to Solaris syslog. For example,

imq.log.syslog.output=NONE

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 logging 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.

To change the time interval, you need to change the property imq.log.file.rolloversecs. For example, the following property definition
changes the time interval to ten days:

imq.log.file.rolloversecs=864000

To change the rollover criteria to depend on file size, you
need to set the imq.log.file.rolloverbytes property. For
example, the following definition directs the broker to rollover files after
they reach a limit of 500,000 bytes

imq.log.file.rolloverbytes=500000

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.

To Use Log Files to Report Metrics Information

Configure the broker’s metrics generation capability:

Confirm imq.metrics.enabled=true

Generation
of metrics for logging is turned on by default.

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 -metricsinterval command
line option when starting up the broker.

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 -loglevellevel command
line option when starting up the broker.

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.