---
title: "log4j 2.x"
url: https://docs.sentry.io/platforms/java/legacy/log4j2/
---

# log4j 2.x | Sentry for Java

##### Note

An [updated Java SDK](https://docs.sentry.io/platforms/java.md) SDK supersedes this deprecated version. Sentry preserves this documentation for customers using the old client. We recommend using the updated Java SDK for new projects.

The `sentry-log4j2` library provides [Log4j 2](https://logging.apache.org/log4j/2.x/) support for Sentry via an [Appender](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html) that sends logged exceptions to Sentry. Once this integration is configured you can *also* use Sentry’s static API, [as shown on the usage page](https://docs.sentry.io/platforms/java/legacy/usage.md), in order to do things like record breadcrumbs, set the current user, or manually send events.

The source can be found [on GitHub](https://github.com/getsentry/sentry-java/tree/master/sentry-log4j2).

### [Installation](https://docs.sentry.io/platforms/java/legacy/log4j2.md#installation)

```xml
<dependency>
    <groupId>io.sentry</groupId>
    <artifactId>sentry-log4j2</artifactId>
    <version>1.7.30</version>
</dependency>
```

For other dependency managers see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-log4j2).

### [Usage](https://docs.sentry.io/platforms/java/legacy/log4j2.md#usage)

The following example configures a `ConsoleAppender` that logs to standard out at the `INFO` level and a `SentryAppender` that logs to the Sentry server at the `WARN` level. The `ConsoleAppender` is only provided as an example of a non-Sentry appender that is set to a different logging threshold, like one you may already have in your project.

Example configuration using the `log4j2.xml` format:

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<Configuration>

  <Appenders>
    <Console name="CONSOLE" target="SYSTEM_OUT">
      <PatternLayout
        pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"
      />
    </Console>
    <Sentry name="SENTRY" />
  </Appenders>

  <Loggers>
    <Root level="INFO">
      <AppenderRef ref="CONSOLE" />
      <!-- Note that the Sentry logging threshold is overridden to the WARN level -->
      <AppenderRef ref="SENTRY" level="WARN" />
    </Root>
  </Loggers>

</Configuration>
```

Next, **you’ll need to configure your DSN** (client key) and optionally other values such as `environment` and `release`. [See the configuration page](https://docs.sentry.io/platforms/java/legacy/configuration.md#setting-the-dsn) for ways you can do this.

### [Additional Data](https://docs.sentry.io/platforms/java/legacy/log4j2.md#additional-data)

It’s possible to add extra data to events thanks to [the marker system](https://logging.apache.org/log4j/2.x/manual/markers.html) provided by Log4j 2.x.

#### [Mapped Tags](https://docs.sentry.io/platforms/java/legacy/log4j2.md#mapped-tags)

By default all MDC parameters are stored under the “Additional Data” tab in Sentry. By specifying the `mdctags` option in your configuration you can choose which MDC keys to send as tags instead, which allows them to be used as filters within the Sentry UI.

```java
void logWithExtras() {
  // ThreadContext ("MDC") extras
  ThreadContext.put("Environment", "Development");
  ThreadContext.put("OS", "Linux");

  // This sends an event where the Environment and OS MDC values are set as additional data
  logger.error("This is a test");
}
```

### [In Practice](https://docs.sentry.io/platforms/java/legacy/log4j2.md#in-practice)

```java
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.Marker;
import org.apache.logging.log4j.MarkerManager;

public class MyClass {
  private static final Logger logger = LogManager.getLogger(MyClass.class);
  private static final Marker MARKER = MarkerManager.getMarker("myMarker");

  void logSimpleMessage() {
    // This sends a simple event to Sentry
    logger.error("This is a test");
  }

  void logWithBreadcrumbs() {
    // Record a breadcrumb that will be sent with the next event(s),
    // by default the last 100 breadcrumbs are kept.
    Sentry.record(
        new BreadcrumbBuilder().setMessage("User made an action").build()
    );

    // This sends a simple event to Sentry
    logger.error("This is a test");
  }

  void logWithTag() {
    // This sends an event with a tag named 'log4j2-Marker' to Sentry
    logger.error(MARKER, "This is a test");
  }

  void logWithExtras() {
    // MDC extras
    ThreadContext.put("extra_key", "extra_value");
    // NDC extras are sent under 'log4j2-NDC'
    ThreadContext.push("Extra_details");
    // This sends an event with extra data to Sentry
    logger.error("This is a test");
  }

  void logException() {
    try {
      unsafeMethod();
    } catch (Exception e) {
      // This sends an exception event to Sentry
      logger.error("Exception caught", e);
    }
  }

  void unsafeMethod() {
    throw new UnsupportedOperationException("You shouldn't call this!");
  }
}
```