New Relic offers a Logback extension to connect your log data to New Relic Logs-in-context for Java, allowing you link to your log data with related data across the rest of the New Relic platform. This document explains how to enable this feature and get started using it.
The code and an example application are available on GitHub.
New Relic's logs-in-context (linking logs directly to Applications, APM errors, and APM traces and spans) for New Relic Logs is currently available as a beta feature. Your use of the early access service is at your own risk. New Relic disclaims all warranties, express or implied, regarding the beta services.
Compatibility and requirements
To use New Relic Logs-in-context with Logback, ensure your configuration meets the following requirements:
- New Relic Logs enabled, with a compatible log forwarder installed
- Java agent 5.6.0 or higher: Install or update
- Distributed tracing enabled
- Logback 1.2.0 or higher installed and working on the application.
New Relic Logs must be enabled and a compatible log forwarder must be installed prior to enabling logs-in-context. For more information, see Introduction to New Relic Logs.
Enable logs-in-context with New Relic Logs
To enable New Relic logs-in-context with Logback:
- Install or update the Java agent.
- Enable and configure the Logback extension.
- Check for logging data.
Install or update the Java agent
Install or update to the most recent Java agent version, and enable Distributed tracing.
Enable and configure the Logback extension
To enable logs-in-context with the Logback extension, complete the following steps:
-
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.0-rc2") }
-
To update with Maven, add the following to your
pom.xml
file:<dependencies> <dependency> <groupId>com.newrelic.logging</groupId> <artifactId>logback</artifactId> <version>1.0-rc2</version> </dependency> </dependencies>
-
-
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>
-
Update your logging configuration xml with the
NewRelicAsyncAppender
. 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 appender used in your logger. Replace your root logger’s appenders with theASYNC
appender created in the previous step.<root> <appender-ref ref="ASYNC" /> </root>
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:
- Includes
trace.id
andspan.id
fields - 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 enabled logs-in-context, here are some potential next steps:
- Explore your data using the Logs UI.
- Troubleshoot errors with distributed tracing, stack traces, application logs, and more.
- Query your data in Insights and create custom dashboards, charts, or alerts.