Documentation forPapertrail

Java log4j

Introduction

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:

  • logback, intended as a successor to log4j
  • SLF4J, a logging abstraction layer which supports multiple pluggable backends (including log4j, logback, and java.util.Logging)

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.

log4j 1.x

Installation

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 are 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 makes 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 the sample below within the <log4j:configuration> block. Replace logsN and XXXXX with the details from Papertrail’s Add Systems page.

Copy
<appender name="SYSLOG" class="org.apache.log4j.net.SyslogAppender">
  <errorHandler/>
  <param name="Facility" value="LOCAL7"/>
  <param name="FacilityPrinting" value="false"/>
  <param name="Header" value="true"/>
  <param name="SyslogHost" value="logsN.papertrailapp.com:XXXXX"/>
  <param name="ConversionPattern" value="%p: %c{2} %x %m %n"/>
</appender>

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:

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

or for JBoss:

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

Alternatively, to use log4j.properties, add the following (replacing logsN and XXXXX as explained above):

Copy
log4j.rootLogger=INFO, syslog
log4j.appender.syslog=org.apache.log4j.net.SyslogAppender
log4j.appender.syslog.Facility=LOCAL7
log4j.appender.syslog.FacilityPrinting=false
log4j.appender.syslog.Header=true
log4j.appender.syslog.SyslogHost=logsN.papertrailapp.com:XXXXX
log4j.appender.syslog.layout=org.apache.log4j.PatternLayout
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:

Copy
<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:

Copy
<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:

Copy
<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:

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

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

Use

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:

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

log4j 2

Installation

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

Setup SYSLOG-TCP appender for Papertrail

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.

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

In the sample above, replace logsN and XXXXX with the details from Papertrail’s Add Systems page.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.