Java: Configure with Logback

New Relic offers a Logback extension for New Relic Logs, allowing you link to your log data with related data across the rest of the New Relic platform. This document explains how to configure logs in context and start getting log data.

The code and an example application are available on GitHub.

Compatibility and requirements

Access to logs in context requires a New Relic APM Pro or Pro trial subscription and enabling of distributed tracing. Before enabling distributed tracing, read the transition guide to learn about the effects on existing APM features and set-up recommendations.

To use New Relic logs in context with Logback, ensure your configuration meets the following requirements:

  • Java agent 5.6.0 or higher: Install or update
  • Logback 1.2.0 or higher installed and working on the application.

Configure logs in context with New Relic Logs

To configure New Relic logs in context with Logback:

  1. Enable New Relic Logs with a compatible log forwarding plugin.
  2. Install or update the Java agent.
  3. Configure the Logback extension.
  4. Check for logging data.

Enable New Relic Logs

Confirm that you have New Relic Logs enabled, with a compatible log forwarding plugin installed to send your application logs to New Relic.

Install or update the Java agent

Install or update to the most recent Java agent version, and enable Distributed tracing.

Configure the Logback extension

To configure logs in context with the Logback extension, complete the following steps:

  1. Update your project's dependencies to include the Logback extension as applicable:

    • To update with Gradle, add the following to your build.gradle file:

      dependencies {
        compile("com.newrelic.logging:logback:1.1")
      }
      
    • To update with Maven, add the following to your pom.xml file:

      <dependencies>
          <dependency>
              <groupId>com.newrelic.logging</groupId>
              <artifactId>logback</artifactId>
              <version>1.1</version>
          </dependency>
      </dependencies>
  2. Update your logging configuration xml to replace any existing <encoder> element as shown below.

    If you are logging to the console (stdout/stderr), look for ConsoleAppender and replace :

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
    </appender>

    If you are logging to a file, look for FileAppender and replace <encoder>:

    <appender name="LOG_FILE" class="ch.qos.logback.core.FileAppender">
        <file>logs/app-log-file.log</file>
        <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
    </appender>
  3. Update your logging configuration xml with the NewRelicAsyncAppender. To ensure that NewRelicAsyncAppender wraps any appenders that will target New Relic's log forwarder, add the following section. Change "LOG_FILE" to the name of the appender you updated in the previous step.

    <appender name="ASYNC" class="com.newrelic.logging.logback.NewRelicAsyncAppender">
        <appender-ref ref="LOG_FILE" />
    </appender>
  4. Make sure NewRelicAsyncAppender is the appender used in your logger. Replace your root logger’s appenders with the ASYNC appender created in the previous step.

    <root>
        <appender-ref ref="ASYNC" />
    </root>

    It's important that the NewRelicAsyncAppender be the first appender to see the log message. List any other appenders after the NewRelicAsyncAppender in the <root> list.

Example configuration files

You can find a working example in GitHub.

Here are examples of an updated logging .xml file for the Logback extension.​

Single console appender example

Example configuration file after adding in the logging extension information.

<configuration>
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">

    <!-- changed the encoder -->
    <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>

  </appender>

  <!-- added the ASYNC appender -->
  <appender name="ASYNC" class="com.newrelic.logging.logback.NewRelicAsyncAppender">
    <appender-ref ref="STDOUT" />
  </appender>

  <root level="debug">

    <!-- changed the root logger -->
    <appender-ref ref="ASYNC" /> 

  </root>
</configuration>

Two-appender example

This example sends New Relic logging to a file, but still sends standard logging to the console.

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>myApp.log</file>
    <!-- encoder changed -->
    <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
  </appender>

  <!-- this appender does normal console logging -->
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%msg%n</pattern>
    </encoder>
  </appender>

  <!-- The required New Relic ASYNC appender wraps the FILE appender -->
  <appender name="ASYNC" class="com.newrelic.logging.logback.NewRelicAsyncAppender">
    <appender-ref ref="FILE" /> 
  </appender>

  <root level="debug">
    <!-- ASYNC is one of the main appenders -->
    <appender-ref ref="ASYNC" /> 

    <!-- Send every message to normal console logging, as well. -->
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

Check for logging data

To verify that you have configured the extension correctly, run your application and verify that the logging you have configured contains the following:

  1. Includes trace.id and span.id fields
  2. Is properly-formatted JSON lines

If everything is configured correctly and your data is being reported, you should see data logs in the New Relic Logs UI using the query operator has: span.id/trace.id.

What's next?

Now that you've set up APM logs in context, here are some potential next steps:

For more help

Recommendations for learning more: