Chapter 18. Logging

download PDF

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.

You specify loggers in your broker configuration by including them in the loggers key of the configuration file, as shown below.


The loggers available in AMQ Broker are shown in the following table.



The root logger. Logs any calls not handled by the other broker loggers.


Logs the broker core


Logs utility calls


Logs Journal calls


Logs JMS calls


Logs bootstrap calls


Logs access to all JMX object methods


Logs message operations such as production, consumption, and browsing of messages


Logs authentication events, creation or deletion of broker resources from JMX or the AMQ Broker management console, and browsing of messages in the management console

There are also two default logging handlers configured in the logger.handlers key, as shown below.

The logger outputs log entries to a file.
The logger outputs log entries to the AMQ Broker management console.

18.1. Changing the logging level

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


You can configure the logging level for all other loggers individually, as shown below.

The available logging levels are described in the following table. The logging levels are listed in ascending order, from the least detailed to the most.



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


Use the ERROR logging level 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 this level of error.


Use the WARN logging level for events that might indicate a non-critical service error. Resumable errors, or minor breaches in request expectations meet this description. The distinction between WARN and ERROR is one for an application developer to make. A simple criterion for making this distinction is whether the error would require a user to seek technical support. If an error would require technical support, set the logging level to ERROR. Otherwise, set the level to WARN.


Use the INFO logging level for service lifecycle events and other crucial related information. INFO-level messages for a given service category should clearly indicate what state the service is in.


Use the DEBUG logging level for log messages that convey extra information for lifecycle events. Use this logging level for developer-oriented information or in-depth information required for technical support. When the DEBUG logging level is enabled, the JBoss server log should not grow proportionally with the number of server requests. DEBUG- and INFO-level messages for a given service category should clearly indicate what state the service is in, as well as what broker resources it is using; ports, interfaces, log files, and so on.


Use the TRACE logging level for log messages that are directly associated with request activity. 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 whether the category priority threshold is enabled. TRACE-level logging enables deep probing of the broker behavior when necessary. When TRACE logging level is enabled, the number of messages in the JBoss sever log grows to at least a * N, where N is the number of requests received by the broker, and a is some constant. The server log might grow to some power of N, depending on the request-handling layer being traced.

  • INFO is the only available logging level for the,, and audit loggers.
  • The logging level specified for the root logger determines the most detailed logging level for all loggers, even if other loggers have more detailed logging levels specified in their configurations. For example, suppose org.apache.activemq.artemis.utils has a specified logging of DEBUG, while the root logger, org.jboss.logging, has a specified logging level of WARN. In this case, both loggers use a logging level of WARN.

18.2. Enabling audit logging

Three audit loggers are available for you to enable; a base audit logger, a message audit logger, and a resource audit logger.

Base audit logger (org.apache.activemq.audit.base)
Logs access to all JMX object methods, such as creation and deletion of addresses and queues. The log does not indicate whether these operations succeeded or failed.
Message audit logger (org.apache.activemq.audit.message)
Logs message-related broker operations, such as production, consumption, or browsing of messages.
Resource audit logger (org.apache.activemq.audit.resource)
Logs authentication success or failure from clients, routes, and the AMQ Broker management console. Also logs creation, update, or deletion of queues from either JMX or the management console, and browsing of messages in the management console.

You can enable each audit logger independently of the others. By default, each audit logger is disabled (that is, the logging level is set to ERROR, which is a not a valid logging level for the audit loggers). To enable one of the audit loggers, set the logging level to INFO. For example:

The message audit logger runs on a performance-intensive path on the broker. Enabling the logger might negatively affect the performance of the broker, particularly if the broker is running under a high messaging load. Use of the message audit logger is not recommended on messaging systems where high throughput is required.

18.3. Configuring console logging

You can configure console logging using the following keys.


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

The console logging configuration options are described in the following table.



Handler name


Character encoding used by the handler


Logging level, specifying the message levels logged. Message levels lower than this value are discarded.


Defines a formatter. See Section 18.5, “Configuring the logging format”.


Species whether to automatically flush the log after each write


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

18.4. Configuring file logging

You can configure file logging using the following keys.


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

The file logging configuration options are described in the following table.



Handler name


Character encoding used by the handler


Logging level, specifying the message levels logged. Message levels lower than this value are discarded.


Defines a formatter. See Section 18.5, “Configuring the logging format”.


Species whether to automatically flush the log after each write


Specifies whether to append to the target file


File description, consisting of the path and optional relative to path.

18.5. Configuring the logging format

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

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

In the preceding configuration, %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.6. Client or embedded server logging

If you want to enable logging on a client, 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 that 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.7. AMQ Broker plugin support

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

You can create custom plugins and implement them using the ActiveMQServerPlugin interface. This interface ensures that the plugin 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.7.1. Adding plugins to the class path

Add the custom created broker plugins to the broker runtime by adding the relevant .jar files to the BROKER_INSTANCE_DIR/lib directory.

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

18.7.2. Registering a plugin

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

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

18.7.3. Registering a plugin programmatically

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

Configuration config = new ConfigurationImpl();

config.registerBrokerPlugin(new UserPlugin());

18.7.4. Logging specific events

By default, AMQ broker provides the LoggingActiveMQServerPlugin plugin to log specific broker events. The LoggingActiveMQServerplugin plugin is commented-out by default and does not log any information.

The following table describes each plugin property. Set a 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 configuration 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"/>

When you have changed the configuration parameters inside the <broker-plugins> section, you must restart the broker to reload the configuration updates. These configuration changes are not reloaded based on 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, for example, beforeCreateConsumer() and afterCreateConsumer(). If the log Level is set to DEBUG, the logger logs more information for a notification, when available.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.