Java log4j logging


log4j is “a popular logging package written in Java. One of its distinctive features is the notion of inheritance in loggers. Using a logger hierarchy it is possible to control which log statements are output at arbitrary granularity.”

Before implementing log4j on a new app, seriously consider using:

Papertrail supports aggregating messages from a native log4j 1.x or log4j 2 appender, providing a live searchable console for your Java (JRE/JVM) app logs. Here’s how, using log4j 1.x or log4j 2

log4j 1.x

Install log4j 1.x

Install log4j in your app or J2EE servlet container. This is basically adding the log4j jar to your classpath, creating a config file, and loading and invoking the classes to output messages.

Here’s more specifics for using log4j in:

log4j includes SyslogAppender in the standard distribution. log4j 1.2.14 and newer support user-specified destination ports, which make Papertrail configuration easier. The steps below assume 1.2.14 or newer. log4j’s SyslogAppender uses UDP syslog.

Setup SyslogAppender for Papertrail

Edit log4j.xml and add this within the <log4j:configuration> block.

Important: In the sample below, replace <host> and XXXXX with the details from Papertrail’s Add Systems page.

<appender name="SYSLOG" class="">
  <param name="Facility" value="LOCAL7"/>
  <param name="FacilityPrinting" value="false"/>
  <param name="Header" value="true"/>
  <param name="SyslogHost" value="<host>"/>
  <param name="ConversionPattern" value="%p: %c{2} %x %m %n"/>

Important: where the config snippet above has <errorHandler/>, you may need to provide a class attribute that is your app server’s ErrorHandler implementation. For example, for Tomcat:

<errorHandler class="org.apache.log4j.helpers.OnlyOnceErrorHandler" />

or for JBoss:

<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler" />

Alternatively, to use, add the following (replacing <host> and XXXXX as explained above):

log4j.rootLogger=INFO, syslog
log4j.appender.syslog.layout.ConversionPattern=%p: (%F:%L) %x %m %n

Enable appender

Outside of the appenders section (in the <root> block), add this to enable the syslog appender you just created:

<appender-ref ref="SYSLOG" />

Change sender identifier (optional)

With the configuration option Header above, SyslogAppender automatically prepends the timestamp (in MMM dd HH:mm:ss format) and the system hostname, which Papertrail uses as the sender identifier. In most cases, this is the best sender identifier.

To use a different sender identifier (such as the name of the app or an arbitrary string), disable the Header option and include those within the ConversionPattern. This configuration:

  <param name="Header" value="true"/>
  <param name="ConversionPattern" value="%p: %c{2} %x %m %n"/>

Is functionally equivalent to this one, except that this configuration is manually outputting the date and sender ID my-app instead of relying on log4j’s Header option:

  <param name="Header" value="false"/>
  <param name="ConversionPattern" value="%d{MMM dd HH:mm:ss} my-app %p: %c{2} %x %m %n"/>

When editing the ConversionPattern, retain the %d{MMM dd HH:mm:ss} my-app at the start.

Edit Format (optional)

Finally, you can optionally edit the message format using standard log4j output formatting parameters. To do so, include a <layout> block within <appender>. Here’s an extremely verbose example:

  <param name="ConversionPattern" value="%t %5r %-5p %c{2} [%x] %m %n"/>

For more details about the ConversionPattern you can refer to the documentation for PatternLayout.


Papertrail is just another log4j target, so no code changes should be needed.

If you aren’t yet using log4j, generate messages with a snippet like this. From the log4j manual:

// get a logger instance named
Logger barlogger = Logger.getLogger("");
barlogger.warn("Low fuel level.");
barlogger.debug("Starting search for nearest gas station.");

log4j 2

Install log4j 2

See installation. Ensure that the API and core .jar files are present in the application’s classpath.

Setup SYSLOG-TCP appender for Papertrail

Important: In the sample below, replace <host> and XXXXX with the details from Papertrail’s Add Systems page. Also, Papertrail does not enable plaintext TCP by default. To enable it, visit Log Destinations, click “Edit Settings,” and enable plaintext TCP logging.

This does not capture stack traces.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
    <Syslog name="SYSLOG-TCP" host="<host>" port="XXXXX"
            protocol="TCP" appName="MyApp" mdcId="mdc"
            facility="LOCAL0" enterpriseNumber="18060" newLine="true"
            format="RFC5424" ignoreExceptions="false" exceptionPattern="%throwable{full}">
    <Root level="debug">
      <AppenderRef ref="SYSLOG-TCP"/>