Skip Navigation Links | |
Exit Print View | |
Oracle GlassFish Server Message Queue 4.5 Administration Guide |
Part I Introduction to Message Queue Administration
1. Administrative Tasks and Tools
3. Starting Brokers and Clients
6. Configuring and Managing Connection Services
8. Configuring Persistence Services
9. Configuring and Managing Security Services
10. Configuring and Managing Broker Clusters
11. Managing Administered Objects
12. Configuring and Managing Bridge Services
13. Monitoring Broker Operations
Introduction to Monitoring Tools
Configuring and Using Broker Logging
Changing the Logging Configuration
To Change the Logger Configuration for a Broker
Changing Log File Rollover Criteria
Using the Command Utility to Display Metrics Interactively
Metrics Outputs: imqcmd metrics
Using the JMX Administration API
Using the Java ES Monitoring Console
Using the Message-Based Monitoring API
Setting Up Message-Based Monitoring
To Set Up Message-based Monitoring
Security and Access Considerations
Metrics Outputs: Metrics Messages
14. Analyzing and Tuning a Message Service
17. Broker Properties Reference
18. Physical Destination Property Reference
19. Administered Object Attribute Reference
20. JMS Resource Adapter Property Reference
21. Metrics Information Reference
22. JES Monitoring Framework Reference
A. Distribution-Specific Locations of Message Queue Data
B. Stability of Message Queue Interfaces
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:
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.
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
|
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 500You can change the time zone used in the time stamp by setting the broker configuration property imq.log.timezone (see Table 17-13).
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:
IMQ_VARHOME/instances/instanceName/logNote - For a broker whose life cycle is controlled by GlassFish Server, the log files are located in a subdirectory of the domain directory for the domain for which the broker was started:
domain-root-dir/domainName/imq/instances/imqbroker/logThe log files are simple text files. The system maintains nine backup files named as follows, from earliest to latest:
log.txt log_1.txt log_2.txt … log_9.txtBy default, the log files are rolled over once a week. You can change this rollover interval, or the location or names of the log files, by setting appropriate configuration properties:
To change the directory in which the log files are kept, set the property imq.log.file.dirpath to the desired path.
To change the root name of the log files from log to something else, set the imq.log.file.filename property.
To change the frequency with which the log files are rolled over, set the property imq.log.file.rolloversecs.
See Table 17-13 for further information on these properties.
Log-related properties are described in Table 17-13.
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:
Logging interval for broker metrics, in seconds
Logging level (ERROR, WARNING, INFO, or NONE)
Silent mode (no logging to console)
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
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.
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.
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.
Generation of metrics for logging is turned on by default.
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.
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.
imq.log.file.output=INFO
This is the default value. It can be set in the config.properties file.
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 21, Metrics Information Reference
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:
A physical destination exceeded its maximum size.
The broker removed a message from a physical destination, for a reason such as the following:
The destination size limit has been reached.
The message time to live expired.
The message is too large.
An error occurred when the broker attempted to process the message.
If a dead message queue is in use, logging also includes the following types of events:
The broker moved a message to the dead message queue.
The broker removed a message from the dead message queue and discarded it.
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.