Chapter 18. Logging

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

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


Table 18.1. Loggers



Logs any calls not handled by the Brokers loggers


Logs the Broker core


Logs utility calls


Logs Journal calls


Logs JMS calls


Logs bootstrap calls

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


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.


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

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



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.


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.


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.


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.


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.


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 refers to the name given in the logger.handlers key.

Table 18.3. Available Console Configuration



The handler’s name.


The character encoding used by this Handler.


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


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


Automatically flush after each write.


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 refers to the name given in the logger.handlers key.

Table 18.4. Available Console Configuration



The handler’s name.


The character encoding used by this Handler.


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


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


Automatically flush after each write.


Specify whether to append to the target 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.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:


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:


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


The following is a typical file for a client:

# Root logger option

# Root logger level
# ActiveMQ Artemis logger levels

# Root logger handlers

# Console handler configuration

# File handler configuration

# Formatter pattern configuration
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-plugin class-name="some.plugin.UserPlugin">
      <property key="property1" value="val_1" />
      <property key="property2" value="val_2" />

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.



Logs information when a connection is created or destroyed.


Logs information when a session is created or closed.


Logs information when a consumer is created or closed.


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


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


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


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-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"/>

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.