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. You specify loggers in your broker configuration by including them in the loggers key of the logging.properties configuration file, as shown below. loggers=org.eclipse.jetty,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,org.apache.activemq.audit.base,org.apache.activemq.audit.message,org.apache.activemq.audit.resource The loggers available in AMQ Broker are shown in the following table. Logger Description org.jboss.logging The root logger. Logs any calls not handled by the other broker 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 org.apache.activemq.audit.base Logs access to all JMX object methods org.apache.activemq.audit.message Logs message operations such as production, consumption, and browsing of messages org.apache.activemq.audit.resource 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. logger.handlers=FILE,CONSOLE logger.handlers=FILE The logger outputs log entries to a file. logger.handlers=CONSOLE 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. logger.level=INFO You can configure the logging level for all other loggers individually, as shown below. 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 logger.org.apache.activemq.audit.base.level=INFO logger.org.apache.activemq.audit.message.level=INFO logger.org.apache.activemq.audit.resource.level=INFO 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. Level Description FATAL 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. ERROR 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. WARN 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. INFO 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. DEBUG 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. TRACE 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. Note INFO is the only available logging level for the logger.org.apache.activemq.audit.base , logger.org.apache.activemq.audit.message , and logger.org.apache.activemq.audit.resource 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: logger.org.apache.activemq.audit.base.level=INFO Important 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=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. The console logging configuration options are described in the following table. Property Description name Handler name encoding Character encoding used by the handler level Logging level, specifying the message levels logged. Message levels lower than this value are discarded. formatter Defines a formatter. See Section 18.5, "Configuring the logging format" . autoflush Species whether to automatically flush the log after each write target 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=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=USD{artemis.instance}/log/artemis.log handler.FILE.formatter=PATTERN Note handler.FILE refers to the name given in the logger.handlers key. The file logging configuration options are described in the following table. Property Description name Handler name encoding Character encoding used by the handler level Logging level, specifying the message levels logged. Message levels lower than this value are discarded. formatter Defines a formatter. See Section 18.5, "Configuring the logging format" . autoflush Species whether to automatically flush the log after each write append Specifies whether to append to the target file 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=org.jboss.logmanager.formatters.PatternFormatter formatter.PATTERN.properties=pattern 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: <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 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 logging.properties file to use. This is done by setting the -Dlogging.configuration property with a valid URL. For example: 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.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. 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: 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. Property Description 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 configuration file. The value of all the events is set to true in the commented default example. 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.

Commands:
loggers=org.eclipse.jetty,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,org.apache.activemq.audit.base,org.apache.activemq.audit.message,org.apache.activemq.audit.resource
logger.handlers=FILE,CONSOLE
logger.level=INFO
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 logger.org.apache.activemq.audit.base.level=INFO logger.org.apache.activemq.audit.message.level=INFO logger.org.apache.activemq.audit.resource.level=INFO
logger.org.apache.activemq.audit.base.level=INFO
handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler handler.CONSOLE.properties=autoFlush handler.CONSOLE.level=DEBUG handler.CONSOLE.autoFlush=true handler.CONSOLE.formatter=PATTERN
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=USD{artemis.instance}/log/artemis.log handler.FILE.formatter=PATTERN
formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter formatter.PATTERN.properties=pattern formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n
<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>
-Djava.util.logging.manager=org.jboss.logmanager.LogManager
-Dlogging.configuration=file:///home/user/projects/myProject/logging.properties
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
<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>
Configuration config = new ConfigurationImpl(); config.registerBrokerPlugin(new UserPlugin ());
<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>