Chapter 18. Logging

AMQ Broker uses the JBoss Logging framework to do its logging and is configurable via the BROKER_INSTANCE_DIR/etc/logging.properties configuration file. This configuration file is a list of key value pairs.

There are six loggers available, which are configured by the loggers key.

loggers=org.jboss.logging,org.apache.activemq.artemis.core.server,org.apache.activemq.artemis.utils,org.apache.activemq.artemis.journal,org.apache.activemq.artemis.jms.server,org.apache.activemq.artemis.integration.bootstrap

Table 18.1. Loggers

LoggerDescription

org.jboss.logging

Logs any calls not handled by the Brokers loggers

org.apache.activemq.artemis.core.server

Logs the Broker core

org.apache.activemq.artemis.utils

Logs utility calls

org.apache.activemq.artemis.journal

Logs Journal calls

org.apache.activemq.artemis.jms

Logs JMS calls

org.apache.activemq.artemis.integration.bootstrap

Logs bootstrap calls

By default there are two loggers configured by default by the logger.handlers key.

logger.handlers=FILE,CONSOLE

As the names suggest these log to the console and to a file.

18.1. Changing the Logging Level

The default logging level for all loggers is INFO and is configured on the root logger.

logger.level=INFO

All other loggers specified can be configured individually via the logger name.

logger.org.apache.activemq.artemis.core.server.level=INFO
logger.org.apache.activemq.artemis.journal.level=INFO
logger.org.apache.activemq.artemis.utils.level=INFO
logger.org.apache.activemq.artemis.jms.level=INFO
logger.org.apache.activemq.artemis.integration.bootstrap.level=INFO
Note

The root logger configuration will always be the finest logging logged even if the other logs have a finer logging configuration.

Table 18.2. Available Logging Levels

LevelDescription

FATAL

Use the FATAL level priority for events that indicate a critical service failure. If a service issues a FATAL error it is completely unable to service requests of any kind.

ERROR

Use the ERROR level priority for events that indicate a disruption in a request or the ability to service a request. A service should have some capacity to continue to service requests in the presence of ERRORs.

WARN

Use the WARN level priority for events that may indicate a non-critical service error. Resumable errors, or minor breaches in request expectations fall into this category. The distinction between WARN and ERROR may be hard to discern and so it is up to the developer to judge. The simplest criterion is would this failure result in a user support call. If it would use ERROR. If it would not use WARN.

INFO

Use the INFO level priority for service life-cycle events and other crucial related information. Looking at the INFO messages for a given service category should tell you exactly what state the service is in.

DEBUG

Use the DEBUG level priority for log messages that convey extra information regarding life-cycle events. Developer or in depth information required for support is the basis for this priority. The important point is that when the DEBUG level priority is enabled, the JBoss server log should not grow proportionally with the number of server requests. Looking at the DEBUG and INFO messages for a given service category should tell you exactly what state the service is in, as well as what server resources it is using: ports, interfaces, log files, and so on.

TRACE

Use TRACE the level priority for log messages that are directly associated with activity that corresponds requests. Further, such messages should not be submitted to a Logger unless the Logger category priority threshold indicates that the message will be rendered. Use the Logger.isTraceEnabled() method to determine if the category priority threshold is enabled. The point of the TRACE priority is to allow for deep probing of the JBoss server behavior when necessary. When the TRACE level priority is enabled, you can expect the number of messages in the JBoss server log to grow at least a x N, where N is the number of requests received by the server, a some constant. The server log may well grow as power of N depending on the request-handling layer being traced.

18.2. Configuring Console Logging

Console Logging can be configured via the following keys.

handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler
handler.CONSOLE.properties=autoFlush
handler.CONSOLE.level=DEBUG
handler.CONSOLE.autoFlush=true
handler.CONSOLE.formatter=PATTERN
Note

handler.CONSOLE refers to the name given in the logger.handlers key.

Table 18.3. Available Console Configuration

PropertyDescription

name

The handler’s name.

encoding

The character encoding used by this Handler.

level

The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded.

formatter

Defines a formatter. See Section 18.4, “Configuring the Logging Format”.

autoflush

Automatically flush after each write.

target

Defines the target of the console handler. The value can either be SYSTEM_OUT or SYSTEM_ERR.

18.3. Configuring File Logging

File Logging can be configured via the following keys.

handler.FILE=org.jboss.logmanager.handlers.PeriodicRotatingFileHandler
handler.FILE.level=DEBUG
handler.FILE.properties=suffix,append,autoFlush,fileName
handler.FILE.suffix=.yyyy-MM-dd
handler.FILE.append=true
handler.FILE.autoFlush=true
handler.FILE.fileName=${artemis.instance}/log/artemis.log
handler.FILE.formatter=PATTERN
Note

handler.FILE refers to the name given in the logger.handlers key.

Table 18.4. Available Console Configuration

PropertyDescription

name

The handler’s name.

encoding

The character encoding used by this Handler.

level

The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded.

formatter

Defines a formatter. See Section 18.4, “Configuring the Logging Format”.

autoflush

Automatically flush after each write.

append

Specify whether to append to the target file.

file

The file description consisting of the path and optional relative to path.

18.4. Configuring the Logging Format

The formatter describes how log messages should be shown. The following is the default configuration.

formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
formatter.PATTERN.properties=pattern
formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n

Where %s is the message and %E is the exception if one exists.

The format is the same as the Log4J format. A full description can be found here.

18.5. Client or Embedded Server Logging

Firstly, if you want to enable logging on the client side you need to include the JBoss logging JARs in your client’s class path. If you are using Maven, add the following dependencies:

<dependency>
   <groupId>org.jboss.logmanager</groupId>
   <artifactId>jboss-logmanager</artifactId>
   <version>1.5.3.Final</version>
</dependency>
<dependency>
   <groupId>org.apache.activemq</groupId>
   <artifactId>artemis-core-client</artifactId>
   <version>1.0.0.Final</version>
</dependency>

There are two properties you need to set when starting your Java program. The first is to set the Log Manager to use the JBoss Log Manager. This is done by setting the -Djava.util.logging.manager property. For example:

-Djava.util.logging.manager=org.jboss.logmanager.LogManager

The second is to set the location of the logging.properties file to use. This is done by setting the -Dlogging.configuration property with a valid URL. For example:

-Dlogging.configuration=file:///home/user/projects/myProject/logging.properties

The following is a typical logging.properties file for a client:

# Root logger option
loggers=org.jboss.logging,org.apache.activemq.artemis.core.server,org.apache.activemq.artemis.utils,org.apache.activemq.artemis.journal,org.apache.activemq.artemis.jms,org.apache.activemq.artemis.ra

# Root logger level
logger.level=INFO
# ActiveMQ Artemis logger levels
logger.org.apache.activemq.artemis.core.server.level=INFO
logger.org.apache.activemq.artemis.utils.level=INFO
logger.org.apache.activemq.artemis.jms.level=DEBUG

# Root logger handlers
logger.handlers=FILE,CONSOLE

# Console handler configuration
handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler
handler.CONSOLE.properties=autoFlush
handler.CONSOLE.level=FINE
handler.CONSOLE.autoFlush=true
handler.CONSOLE.formatter=PATTERN

# File handler configuration
handler.FILE=org.jboss.logmanager.handlers.FileHandler
handler.FILE.level=FINE
handler.FILE.properties=autoFlush,fileName
handler.FILE.autoFlush=true
handler.FILE.fileName=activemq.log
handler.FILE.formatter=PATTERN

# Formatter pattern configuration
formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
formatter.PATTERN.properties=pattern
formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n

18.6. AMQ Broker Plug-ins Support

AMQ supports custom plug-ins. You can use plug-ins to log information about many different types of events that would otherwise only be available through debug logs. Multiple plug-ins can be registered, tied, and executed together. The plug-ins will be executed based on the order of the registration, that is, the first plug-in registered is always executed first.

You can create custom plug-ins and implement them using the ActiveMQServerPlugin interface. This interface ensures that the plug-in is on the classpath, and is registered with the broker. As all the interface methods are implemented by default, you have to add only the required behavior that needs to be implemented.

18.6.1. Adding Plug-ins to the Classpath

Add the custom created broker plug-ins to the broker runtime by adding the relevant jars to the BROKER_INSTANCE_DIR/lib directory.

If you are using an embedded system then place the jar under the regular classpath of your embedded application.

18.6.2. Registering a Plug-in

You must register a plug-in by adding the broker-plugins element in the broker.xml file. You can specify the plug-in configuration value using the property child elements. These properties will be read and passed into the plug-in’s init (Map<String, String>) operation after the plug-in has been instantiated.

<broker-plugins>
   <broker-plugin class-name="some.plugin.UserPlugin">
      <property key="property1" value="val_1" />
      <property key="property2" value="val_2" />
   </broker-plugin>
 </broker-plugins>

18.6.3. Registering a Plug-in Programmatically

To register a plug-in programmatically, use the registerBrokerPlugin() method and pass in a new instance of your plug-in. The example below shows the registration of the UserPlugin plugin:

Configuration config = new ConfigurationImpl();

config.registerBrokerPlugin(new UserPlugin());

18.6.4. Logging Specific Events

By default, AMQ broker provides the LoggingActiveMQServerPlugin plug-in to log specific broker events. The LoggingActiveMQServerPlug-in plug-in is commented out by default and does not log any information. The following table provides information about the plug-in properties and its description. Set the configuration property value to true to log events.

PropertyDescription

LOG_CONNECTION_EVENTS

Logs information when a connection is created or destroyed.

LOG_SESSION_EVENTS

Logs information when a session is created or closed.

LOG_CONSUMER_EVENTS

Logs information when a consumer is created or closed.

LOG_DELIVERING_EVENTS

Logs information when message is delivered to a consumer and when a message is acknowledged by a consumer.

LOG_SENDING_EVENTS

Logs information when a message has been sent to an address and when a message has been routed within the broker.

LOG_INTERNAL_EVENTS

Logs information when a queue created or destroyed, when a message is expired, when a bridge is deployed, and when a critical failure occurs.

LOG_ALL_EVENTS

Logs information for all the above events.

To configure the LoggingActiveMQServerPlugin plugin to log connection events, uncomment the <broker-plugins> section in the broker.xml file. The value of all the events is set to true in the commented default example.

<configuration ...>
...
<!-- Uncomment the following if you want to use the Standard LoggingActiveMQServerPlugin plugin to log in events -->
           <broker-plugins>
         <broker-plugin class-name="org.apache.activemq.artemis.core.server.plugin.impl.LoggingActiveMQServerPlugin">
            <property key="LOG_ALL_EVENTS" value="true"/>
            <property key="LOG_CONNECTION_EVENTS" value="true"/>
            <property key="LOG_SESSION_EVENTS" value="true"/>
            <property key="LOG_CONSUMER_EVENTS" value="true"/>
            <property key="LOG_DELIVERING_EVENTS" value="true"/>
            <property key="LOG_SENDING_EVENTS" value="true"/>
            <property key="LOG_INTERNAL_EVENTS" value="true"/>
         </broker-plugin>
      </broker-plugins>
...
</configuration>

After changing the configuration parameters inside the <broker-plugins> section of the broker.xml file, you must restart the broker to reload the configuration updates. These configuration changes will not be reloaded by the configuration-file-refresh-period setting.

When the log level is set to INFO, an entry is logged after the event has occurred. If the log level is set to DEBUG, log entries are generated for both before and after the event has occurred. For example, it logs beforeCreateConsumer() and afterCreateConsumer(). If the log Level is set to DEBUG, it logs more information for a notification when available.