Java: Configure with Log4j 2.x

New Relic offers a Log4j 2.x 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 Log4j 2.x, ensure your configuration meets the following requirements:

Configure logs in context with New Relic Logs

To configure New Relic logs in context with Log4j 2.x:

  1. Enable New Relic Logs with a compatible log forwarding plugin.
  2. Install or update the Java agent.
  3. Configure the Log4j 2.x 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 Log4j 2.x extension

To configure logs in context with the Log4j 2.x extension, complete the following steps:

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

    To update with Gradle, add the highlighted section to your build.gradle file:

    dependencies {

    To update with Maven, add the highlighted section to your pom.xml file:

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

    <Configuration xmlns=""

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

  3. Once updated, add <NewRelicLayout/> to use a NewRelicLayout element within one of the appenders. For example:

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

    If you are using a properties file, change only the layout.type property, as shown below:

    appender.console.type = Console = STDOUT
    appender.console.layout.type = NewRelicLayout
  4. If you only modified an existing appender, you can skip this step.

    Add <AppenderRef/> within <Root> to use this appender. The ref attribute refers to the name of the appender you created in the previous step. For example:

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

    If you are using a properties file, you will need to add a property if you added a new appender:

    rootLogger.level = info
    rootLogger.appenderRef.stdout.ref = STDOUT
  5. Set the log4j2.messageFactory system property to the NewRelicMessageFactory. The exact method for making this change many vary, depending on your application framework. One of options listed below may work for you, or you may refer to the log4j 2.x documentation for more information on the MessageFactory:

    • One option is to change the java command-line with -D. Many frameworks use the JAVA_OPTS environment variable.
    • If you have application properties files in your project, you can try adding the following:

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

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: