Java agent logs in context

This is the simplest approach, and it's a great choice for developers who may not have the access or interest in setting up a log forwarder, or for accounts that want to see the power of logs and other linking metadata in context of their apps, without a lot of overhead.

Using this option, the agent adds span.id, trace.id, hostname, entity.guid, and entity.name. Learn about log forwarding limitations.

This functionality is enabled by default.

All you need to do is install an agent version with log forwarding capabilities (Java agent 7.6.0 or higher). If forwarding is disabled, you can use this configuration:

Configuration file (newrelic.yml), indented 2 spaces under the common section:

application_logging:
  enabled: true
  forwarding:
    enabled: true
    max_samples_stored: 10000
  local_decorating:
    enabled: false

Environment variable:

NEW_RELIC_APPLICATION_LOGGING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED=10000
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=false

System property:

-Dnewrelic.config.application_logging.enabled=true
-Dnewrelic.config.application_logging.forwarding.enabled=true
-Dnewrelic.config.application_logging.forwarding.max_samples_stored=10000
-Dnewrelic.config.application_logging.local_decorating.enabled=false

Optional adjustments (max_samples_stored):

Once this feature is enabled, you also have control over the maximum number of log lines sent to New Relic every minute. The default value is 10,000. If more than 10,000 log lines are seen by the agent in a 60-second window, your logs will begin to be sampled.

Set it to a higher number to receive more logs. Set it to a lower number to receive fewer logs. Any non-negative integer is valid.

Configuration file (newrelic.yml):

application_logging:
  enabled: true
  forwarding:
    enabled: true
    max_samples_stored: 10000
  local_decorating:
    enabled: false

Environment variable:

NEW_RELIC_APPLICATION_LOGGING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED=10000
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=false

System property:

-Dnewrelic.config.application_logging.enabled=true
-Dnewrelic.config.application_logging.forwarding.enabled=true
-Dnewrelic.config.application_logging.forwarding.max_samples_stored=10000
-Dnewrelic.config.application_logging.local_decorating.enabled=false

Already have a log forwarder you like? We've got you covered! The Java agent can decorate your logs with the linking metadata needed to provide access to automatic logs-in-context features, and you can send them to New Relic using your manual log forwarder.

Update your agent's configuration to disable log forwarding and enable local decoration, then restart the agent to start decorating your logs.

Configuration file (newrelic.yml), indented 2 spaces under the common section:

application_logging:
  enabled: true
  local_decorating:
    enabled: true
  forwarding:
    enabled: false

Environment variable:

NEW_RELIC_APPLICATION_LOGGING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=false

System property:

-Dnewrelic.config.application_logging.enabled=true
-Dnewrelic.config.application_logging.local_decorating.enabled=true
-Dnewrelic.config.application_logging.forwarding.enabled=false

Our decorator adds five attributes to every log message in your application log file: entity.guid, hostname, trace.id, span.id and entity.name. Example:

This is my log message. NR-LINKING|{entity.guid}|{hostname}|{trace.id}|{span.id}|{entity.name}|

If the log message is empty or blank, output message will also be empty. Example:

NR-LINKING|{entity.guid}|{hostname}|{trace.id}|{span.id}|{entity.name}|.

The output log message will be an empty string.

Some attributes may be empty if the log occurred outside a transaction or if they are not applicable to your application's context.

We offer a Dropwizard extension for logs in context with the Java agent. To get started, review the code and an example application on GitHub.

To configure logs in context for your Java app with the DropWizard extension:

1. Make sure you have the Dropwizard 1.3 or higher package installed and working on your application. Use the original Dropwizard appenders and logging factory installed and working on the application.

2. Make sure you have the New Relic Java agent version 5.6.0 or higher installed on your application, and that you have enabled the JVM argument -javaagent.

3. Update your project's dependencies to include the Dropwizard 1.3 extension as applicable:

   Gradle: Add the following to your build.gradle file:

   dependencies {
     implementation("com.newrelic.logging:dropwizard:2.0")
   }

   Copy

   Maven: Add the following to your pom.xml file:

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>dropwizard</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copy

4. Update your Dropwizard .yaml configuration file with a newrelic-json layout, replacing the currently used type: console or type: file with either type: newrelic-console or type: newrelic-file as appropriate. For example:

   logging:
     appenders:
       - type: newrelic-console
         # Add the two lines below if you don't have a layout specified on the appender.
         # If you have a layout, remove all parameters to the layout and set the type.
         layout:
           type: newrelic-json

   Copy

   The New Relic Dropwizard extension also supports a log-format layout type that uses the standard Dropwizard logging. For testing purposes, you can change the type of the layout with a one-line change:

   logging:
     appenders:
       - type: newrelic-file
         # This format will be ignored by the newrelic-json layout, but used by the log-format layout.
         logFormat: "%date{ISO8601} %c %-5p: %m trace.id=%mdc{trace.id} span.id=%mdc{span.id}%n"
         layout:
           # type: newrelic-json
           type: log-format

   Copy

We offer a java.util.logging extension for logs in context with the Java agent. To get started, review the code and an example application on GitHub.

To configure logs in context for your Java app with with the java.util.logging extension:

1. Make sure you have the java.util.logging package installed and working on the application.

2. Make sure you have the New Relic Java agent version 5.6.0 or higher installed on your application, and that you have enabled the JVM argument -javaagent.

3. Update your project's dependencies to include the java.util.logging extension as applicable. If you can't edit these files, you can instead add the jars directly to the application classpath.

   Gradle: Add the following to your build.gradle file:

   dependencies {
     implementation("com.newrelic.logging:jul:2.0")
   }

   Copy

   Maven: Add the following to your pom.xml file:

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>jul</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copy

4. Check if your logging file's handlers property is set to something other than NewRelicMemoryHandler. Look for a line listing the root logger's handlers, like this:

   handlers = java.util.logging.FileHandler

   Copy

5. Update your logging properties file to set the root logger's handler to NewRelicMemoryHandler so it intercepts messages destined for another handler:

   handlers = com.newrelic.logging.jul.NewRelicMemoryHandler

   Copy

6. Configure the NewRelicMemoryHandler by setting the target to the handler that was previously assigned to the root logger, so it captures data New Relic needs on the thread the log message is coming from:

   com.newrelic.logging.jul.NewRelicMemoryHandler.target = java.util.logging.FileHandler

   Copy

7. Use a NewRelicFormatter for the final handler. Update your logging properties file to set the formatter property like the following example. Make sure the handler where you set the formatter is the target handler from the previous step (java.util.logging.FileHandler in this example).

   java.util.logging.FileHandler.formatter = com.newrelic.logging.jul. NewRelicFormatter

   Copy

   The New Relic log format is JSON with telemetry metadata we use to correlate transactions and logs together. Currently we do not support any customization of that format.

   Once complete, JSON is logged instead of text. The JSON should be formatted as single objects, one per line, and should contain fields like log.level and thread.name. The trace.id, which is required for logs in context, should only have a value for log messages that occur within a transaction.

The most direct way to get the logs-in-context extensions is to add these dependencies to Maven's pom.xml or Gradle's build.gradle. This allows the packaging tools to pick up the correct dependencies.

If you can't edit these files, you can instead add the jars directly to the application classpath for your logging framework's configuration.

Before you modify the classpath:

1. Enable the JVM argument -javaagent on your app's Java agent.
2. Verify which logging framework the application is using.
3. Make sure you are able to change your logging framework's configuration.
4. Add the following three jars to the classpath if they aren't already present. Generally, we recommend taking the latest versions published on Maven Central.

• Group ID com.newrelic.logging and Artifact ID: Select the artifact named after your application's logging framework in Maven.
• Group ID com.fasterxml.jackson.core and Artifact ID: Use jackson-core.
• Group ID com.newrelic.agent.java and Artifact ID: Use newrelic-api.

We offer a Log4j 1.x extension for manual logs in context with the Java agent. To get started, review the code and an example application on GitHub.

To configure manual logs in context for your Java app with with the Log4j 1.x extension, you must configure the Log4j extension in code or via XML. Properties files are not supported because AsyncAppender instances can only be automatically configured via XML.

1. Make sure you have the Log4j 1.x package installed and working on the application.

2. Make sure you have the New Relic Java agent version 5.6.0 or higher installed on your application, and that you have enabled the JVM argument -javaagent.

3. Update your project's dependencies to include the Log4j 1.x extension as applicable.

   Gradle: Add the following to your build.gradle file:

   dependencies {
     implementation("com.newrelic.logging:log4j1:2.0")
   }

   Copy

   Maven: Add the following to your pom.xml file:

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>log4j1</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copy

4. In your logging configuration XML file, update your <appender> element with a NewRelicLayout, adding <layout class="com.newrelic.logging.log4j1.NewRelicLayout"/>:

   <appender name="TypicalFile" class="org.apache.log4j.FileAppender">
     <param name="file" value="logs/log4j1-app.log"/>
     <param name="append" value="false"/>
     <layout class="com.newrelic.logging.log4j1.NewRelicLayout"/> <!-- only this line needs to be added -->
   </appender>

   Copy

5. Use NewRelicAsyncAppender to wrap any appenders that will target New Relic's log forwarder. For example:

   <appender name="NewRelicFile"
             class="com.newrelic.logging.log4j1.NewRelicAsyncAppender">
     <appender-ref ref="TypicalFile" />
   </appender>

   Copy

6. Use the async appender on the root logger. For example:

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

   Copy

   Example configuration file for the Log4j 1.x extension:

   <?xml version="1.0" encoding="UTF-8" ?>
   <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
   <log4j:configuration debug="false">
     <appender name="TypicalFile" class="org.apache.log4j.FileAppender">
       <param name="file" value="logs/log4j1-app.log"/>
       <param name="append" value="false"/>
       <!-- layout has been replaced -->
       <layout class="com.newrelic.logging.log4j1.NewRelicLayout"/>
     </appender>
   
       <!-- this appender was added -->
     <appender name="NewRelicFile"
               class="com.newrelic.logging.log4j1.NewRelicAsyncAppender">
       <appender-ref ref="TypicalFile" />
     </appender>
   
     <appender name="TypicalConsole" class="org.apache.log4j.ConsoleAppender">
       <layout class="org.apache.log4j.PatternLayout">
         <param name="ConversionPattern" value="%-5p %c{1} - %m%n"/>
       </layout>
     </appender>
   
     <root>        ​
       <!-- the new appender was used here -->​​
       <appender-ref ref="NewRelicFile" />
       <appender-ref ref="TypicalConsole" />
     </root>
   
   </log4j:configuration>

   Copy

We offer a Log4j 2.x extension for logs in context with the Java agent. To get started, review the code and an example application on GitHub.

To configure logs in context for your Java app with with the Log4j 2.x extension:

1. Make sure you have the Log4j 2.13.2 or higher or Logs4j 2 binding package installed and working on your application.

2. Make sure you have the New Relic Java agent version 5.6.0 or higher installed on your application, and that you have enabled the JVM argument -javaagent.

3. Update your project's dependencies to include the Log4j 2.x extension as applicable:

   Gradle: Add the highlighted section to your build.gradle file:

   dependencies {
     implementation("com.newrelic.logging:log4j2:2.0")
   }

   Copy

   Maven: Add the highlighted section to your pom.xml file:

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>log4j2</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copy

4. In your logging configuration XML file, update your <configuration> element by adding the highlighted section:

   <Configuration xmlns="http://logging.apache.org/log4j/2.0/config"
         packages="com.newrelic.logging.log4j2"
   >

   Copy

   If you're using a properties file, add packages=com.newrelic.logging.log4j2.

5. Add <NewRelicLayout/> to use a NewRelicLayout element within one of the appenders. For example:

   <File name="MyFile" fileName="logs/app-log-file.log">
     <NewRelicLayout/>
   </File>

   Copy

   If you're using a properties file, only change the layout.type:

   appender.console.type = Console
   appender.console.name = STDOUT
   appender.console.layout.type = NewRelicLayout

   Copy

6. If you only modified an existing appender, skip this step. If you added a new appender, add <AppenderRef/> within <Root> to use this appender. Use the ref attribute to refer to appender name you created in the previous step. For example:

   <Root level="info">
     <AppenderRef ref="MyFile"/>
   </Root>

   Copy

   If you're using a properties file and added a new appender, add:

   rootLogger.level = info
   rootLogger.appenderRef.stdout.ref = STDOUT

   Copy

We offer a Logback extension for logs in context with the Java agent. To get started, review the code and an example application on GitHub.

To configure logs in context for your Java app with Logback:

1. Make sure you have Logback version 1.2.0 or higher and the New Relic Java agent version 5.6.0 or higher installed and working on your application.

2. Make sure you have the New Relic Java agent version 5.6.0 or higher installed on your application, and that you have enabled the JVM argument -javaagent.

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

   Gradle: Add the highlighted section to your build.gradle file:

   dependencies {
     implementation("com.newrelic.logging:logback:2.0")
   }

   Copy

   Maven: Add the highlighted section to your pom.xml file:

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>logback</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copy

4. Update your logging configuration xml to replace any existing <encoder> element.

   If you're 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>

   Copy

   If you're 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>

   Copy

5. 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>

   Copy

6. Make sure NewRelicAsyncAppender is the first appender used in your logger. Replace your root logger’s appenders with the ASYNC appender created in the previous step. Then list any other appenders after the NewRelicAsyncAppender in the <root> list.

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

   Copy

   Here are examples of an updated logging .xml file for the Logback extension. You can also see a working example in GitHub.

   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>

   Copy

   Two console appenders 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>

   Copy

We offer extensions for current versions of Spring and Spring Boot. If you already know the logging library, you can skip directly to that documentation:

• java.util.logging

• log4j 1

• log4j 2

• logback

  The extensions support default configurations only on Spring Boot 2.0 and higher.

  With Spring Boot:

  Here are tips to determine which logging library you have:

• If you have spring-boot-starter-log4j2 in your dependencies, you're using log4j 2.x. Refer to the Spring Boot log4j 2.x documentation for basic configuration, and the New Relic log4j 2 extension for customizing your configuration.

• If you're using Spring Boot but not the starter-log4j2, you're using logback by default. Refer to Spring Boot logback documentation for basic configuration, and the New Relic logback extension for customizing your configuration.

  With Spring (but not Spring Boot):

  Spring 5 or higher:

  Spring implements a bridge to other logging libraries that will automatically find them. However, those individual libraries must be configured and explicitly included in your project dependencies.

  To identify your logging dependency, consult your Gradle, Maven, or other build tool's dependency tree. Then follow the procedures to configure logs in context for your Java app with that extension.

  Spring 4 or lower:

  Spring version 4 and lower uses Apache Commons Logging for its bridge. Refer to the Spring documentation for information on configuring its bridge.