Log4j Jakarta JMS Appender

The JMS Appender sends the formatted log event to a JMS Destination.

Dependency

You need to have the org.apache.logging.log4j:log4j-jakarta-jms dependency in your classpath:

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-jakarta-jms</artifactId>
  <version>3.0.0-SNAPSHOT</version>
</dependency>

JMS Appender requires a jakarta.jms:jakarta.jms-api implementation (e.g., the one provided by Eclipse GlassFish or Apache ActiveMQ) at runtime.

Configuration

The JMS Appender requires JNDI support so as of release 2.15.1 and will not function unless log4j2.enableJndi=true is configured as a system property or environment variable.

Note that in Log4j 2.0, this Appender was split into a JMSQueueAppender and a JMSTopicAppender. Starting in Log4j 2.1, these Appenders were combined into the JMS Appender, which makes no distinction between queues and topics. However, configurations written for 2.0 which use the <JMSQueue/> or <JMSTopic/> elements will continue to work with the new <JMS/> configuration element.

Table 1. JMS Appender parameters
Parameter	Type	Default	Description
`factoryBindingName`	`String`		The name to locate in the `Context` that provides the `ConnectionFactory`. This can be any sub-interface of `ConnectionFactory` as well. This parameter is required.
`factoryName`	`String`		The fully qualified class name that should be used to define the initial `ContextFactory` as defined in `INITIAL_CONTEXT_FACTORY`. If a `factoryName` is specified without a `providerURL`, a warning message will be logged as this is likely to cause problems. This parameter is required.
`filter`	`Filter`		A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a `CompositeFilter`.
`layout`	`Layout`		The Layout to use to format the LogEvent. This parameter is required since `2.9`. In previous versions `SerializedLayout` was default.
`name`	`String`		The name of the Appender. This parameter is required.
`password`	`String`		The password to use to create the JMS connection
`providerURL`	`String`		The URL of the provider to use as defined by `PROVIDER_URL`. This parameter is required.
`destinationBindingName`	`String`		The name to use to locate the `Destination`. This can be a `Queue` or `Topic`, and as such, the attribute names `queueBindingName` and `topicBindingName` are aliases to maintain compatibility with the Log4j 2.0 JMS Appenders. This parameter is required.
`securityPrincipalName`	`String`		The name of the identity of the Principal as specified by `SECURITY_PRINCIPAL`. If a `securityPrincipalName` is specified without `securityCredentials`, a warning message will be logged as this is likely to cause problems.
`securityCredentials`	`String`		The security credentials for the principal as specified by `SECURITY_CREDENTIALS`.
`ignoreExceptions`	`boolean`	`true`	Indicates if exceptions encountered while appending events to be internally logged and then ignored. When set to `false` exceptions will be propagated to the caller, instead. You must set this to `false` when wrapping this Appender in a `FailoverAppender`.
`immediateFail`	`boolean`	`false`	When set to `true`, log events will not wait to try to reconnect and will fail immediately if the JMS resources are not available. This parameter is introduced in `2.9`.
`reconnectIntervalMillis`	`long`	`5000`	If set to a value greater than `0`, after an error, the `JMSManager` will attempt to reconnect to the broker after waiting the specified number of milliseconds. If the reconnect fails then an exception will be thrown, which can be caught by the application if `ignoreExceptions` is set to `false`. This parameter is introduced in `2.9`.
`urlPkgPrefixes`	`String`	`null`	A colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory as defined by `URL_PKG_PREFIXES`
`userName`	`String`	`null`	The user ID used to create the JMS connection

Example log4j.xml demonstrating JMS Appender usage

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">

  <Appenders>
    <JMS name="jmsQueue"
         destinationBindingName="MyQueue"
         factoryBindingName="MyQueueConnectionFactory">
      <JsonTemplateLayout/>
    </JMS>
  </Appenders>

  <Loggers>
    <Root level="error">
      <AppenderRef ref="jmsQueue"/>
    </Root>
  </Loggers>

</Configuration>

Starting from version 2.9, you can map your Log4j MapMessages to JMS javax.jms.MapMessages, set the Layout of the Appender to MessageLayout with <MessageLayout/>:

Example log4j.xml demonstrating JMS Appender usage with MessageLayout to translate MapMessages

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">

  <Appenders>
    <JMS name="jmsQueue"
         destinationBindingName="MyQueue"
         factoryBindingName="MyQueueConnectionFactory">
      <MessageLayout />
    </JMS>
  </Appenders>

  <Loggers>
    <Root level="error">
      <AppenderRef ref="jmsQueue"/>
    </Root>
  </Loggers>

</Configuration>