Logs in context for the Java agent connects your logs and APM data in New Relic. Bringing all of this data together in a single tool helps you quickly get to the root cause of an issue and find the log lines that you need to identify and resolve a problem.
Set up your Java app
To enable logs in context for APM apps monitored by Java:
- Make sure you have already set up logging in New Relic. This includes configuring a supported log forwarder that collects your application logs and extends the metadata that is forwarded to New Relic.
- Install or update to the latest Java agent version. Use Java agent version 5.6.0 or higher for logs in context.
- Enable the JVM argument
-javaagent
, and enable distributed tracing. - Configure logs in context for Java to enrich your log data, using any of the following extensions as applicable. If you use Spring or Spring Boot and aren't sure which extension you need, see our Spring documentation.
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:
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.
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
.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")}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>Update your Dropwizard
.yaml
configuration file with anewrelic-json
layout, replacing the currently usedtype: console
ortype: file
with eithertype: newrelic-console
ortype: 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
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-jsontype: log-format
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:
Make sure you have the java.util.logging package installed and working on the application.
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
.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 applicationclasspath
.Gradle: Add the following to your
build.gradle
file:dependencies {implementation("com.newrelic.logging:jul:2.0")}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>Check if your logging file's
handlers
property is set to something other thanNewRelicMemoryHandler
. Look for a line listing the root logger's handlers, like this:handlers = java.util.logging.FileHandlerUpdate 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.NewRelicMemoryHandlerConfigure 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.FileHandlerUse a
NewRelicFormatter
for the final handler. Update your logging properties file to set theformatter
property like the following example. Make sure the handler where you set the formatter is thetarget
handler from the previous step (java.util.logging.FileHandler
in this example).java.util.logging.FileHandler.formatter = com.newrelic.logging.jul. NewRelicFormatterThe 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
andthread.name
. Thetrace.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:
- Enable the JVM argument
-javaagent
on your app's Java agent. - Verify which logging framework the application is using.
- Make sure you are able to change your logging framework's configuration.
- 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: Usejackson-core
. - Group ID
com.newrelic.agent.java
and Artifact ID: Usenewrelic-api
.
We offer a Log4j 1.x extension 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 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.
Make sure you have the Log4j 1.x package installed and working on the application.
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
.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")}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>In your logging configuration XML file, update your
<appender>
element with aNewRelicLayout
, 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>
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>
Use the async appender on the root logger. For example:
<root> <appender-ref ref="NewRelicFile" /> </root>
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>
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:
Make sure you have the Log4j 2.13.2 or higher or Logs4j 2 binding package installed and working on your application.
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
.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") }
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>
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" >
If you're using a properties file, add
packages=com.newrelic.logging.log4j2
.Add
<NewRelicLayout/>
to use aNewRelicLayout
element within one of the appenders. For example:<File name="MyFile" fileName="logs/app-log-file.log"> <NewRelicLayout/> </File>
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
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 theref
attribute to refer to appendername
you created in the previous step. For example:<Root level="info"> <AppenderRef ref="MyFile"/> </Root>
If you're using a properties file and added a new appender, add:
rootLogger.level = info rootLogger.appenderRef.stdout.ref = STDOUT
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:
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.
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
.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") }
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>
Update your logging configuration
xml
to replace any existing<encoder>
element.If you're logging to the console (
stdout/stderr
), look forConsoleAppender
and replace:<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"><encoder class="com.newrelic.logging.logback.NewRelicEncoder"/></appender>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>Update your logging configuration
xml
with theNewRelicAsyncAppender
. To ensure thatNewRelicAsyncAppender
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>Make sure
NewRelicAsyncAppender
is the first appender used in your logger. Replace your root logger’s appenders with theASYNC
appender created in the previous step. Then list any other appenders after theNewRelicAsyncAppender
in the<root>
list.<root><appender-ref ref="ASYNC" /></root>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>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>
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:
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.
View logs in UI
To verify that you have configured the log appender correctly, run your application, then check your logs data in New Relic One using the query operator has:span.id has:trace.id
.
If everything is configured correctly and your data is being forwarded to New Relic with the enriched metadata, your logs should now be emitted as JSON and contain trace.id
and span.id
fields. If you don't see log data in the UI, follow the troubleshooting procedures.
What's next?
After you set up APM logs in context, make the most of your logging data:
- Explore the logging data across your platform with our Logs UI.
- See your logs in context of your app's performance in the APM UI. Troubleshoot errors with distributed tracing, stack traces, application logs, and more.
- Get deeper visibility into both your application and your platform performance data by forwarding your logs with our infrastructure monitoring agent. Review your infrastructure logs in the UI.
- Set up alerts.
- Query your data and create dashboards.