Logback

The sentry-logback library provides Logback support for Sentry via an Appender 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, in order to do things like record breadcrumbs, set the current user, or manually send events.

The source can be found on GitHub.

Installation

Copied
<dependency>
    <groupId>io.sentry</groupId>
    <artifactId>sentry-logback</artifactId>
    <version>3.2.0</version>
</dependency>

For other dependency managers see the central Maven repository.

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 ERROR 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 logback.xml format:

Copied
<configuration>
    <!-- Configure the Console appender -->
    <appender name="Console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Configure the Sentry appender, overriding the logging threshold to the WARN level -->
    <appender name="Sentry" class="io.sentry.logback.SentryAppender">
        <options>
            <!-- NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry project/dashboard -->
            <dsn>https://examplePublicKey@o0.ingest.sentry.io/0</dsn>
        </options>
    </appender>

    <!-- Enable the Console and Sentry appenders, Console is provided as an example
 of a non-Sentry logger that is set to a different logging threshold -->
    <root level="INFO">
        <appender-ref ref="Console" />
        <appender-ref ref="Sentry" />
    </root>
</configuration>

DSN Configuration

Note that you need to configure your DSN (client key).

Copied
<appender name="Sentry" class="io.sentry.logback.SentryAppender">
    <options>
        <!-- NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry project/dashboard -->
        <dsn>https://examplePublicKey@o0.ingest.sentry.io/0</dsn>
    </options>
</appender>

If the DSN is not present in the logback.xml configuration, Sentry will attempt to read it from the system property sentry.dsn, environment variable SENTRY_DSN or the dsn property in sentry.properties file. See the configuration page for more details on external configuration.

Advanced Configuration

Optionally you can configure other values such as environment and release. See the configuration page for the in-depth explanation of each property.

Copied
<appender name="Sentry" class="io.sentry.logback.SentryAppender">
    <options>
        <!-- NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry project/dashboard -->
        <dsn>https://examplePublicKey@o0.ingest.sentry.io/0</dsn>
        <shutdownTimeout>2000</shutdownTimeout>
        <flushTimeoutMillis>15000</flushTimeoutMillis>
        <debug>false</debug>
        <maxBreadcrumbs>100</maxBreadcrumbs>
        <release>1.0.0</release>
        <environment>production</environment>
        <sampleRate>1.0</sampleRate>
        <attachThreads>false</attachThreads>
        <attachStacktrace>false</attachStacktrace>
        <serverName>host-4</serverName>
        <connectionTimeoutMillis>5000</connectionTimeoutMillis>
        <readTimeoutMillis>5000</readTimeoutMillis>
    </options>
</appender>

Minimum log level

Two log levels are used to configure this integration (see options below). One will configure the lowest level required for a log message to become an event (minimumEventLevel) sent to Sentry. The other option (minimumBreadcrumbLevel) configures the lowest level a message has to be to become a breadcrumb. Breadcrumbs are kept in memory (by default the last 100 records) and are sent with events. For example, by default, if you log 100 entries with logger.info or logger.warn, no event is sent to Sentry. If you then log with logger.error, an event is sent to Sentry which includes those 100 info or warn messages. For this to work, SentryAppender needs to receive all log entries in order to decide what to keep as breadcrumb or sent as event. Make sure to set the SentryAppender log level configuration to a value lower than what you set for the minimumBreadcrumbLevel and minimumEventLevel to make sure SentryAppender receives these log messages.

Copied
<appender name="Sentry" class="io.sentry.logback.SentryAppender">
    <options>
        <!-- NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry project/dashboard -->
        <dsn>https://examplePublicKey@o0.ingest.sentry.io/0</dsn>
    </options>
    <!-- Optionally change minimum Event level. Default for Events is ERROR -->
    <minimumEventLevel>WARN</minimumEventLevel>
    <!-- Optionally change minimum Breadcrumbs level. Default for Breadcrumbs is INFO -->
    <minimumBreadcrumbLevel>DEBUG</minimumBreadcrumbLevel>
</appender>

Additional Data

It’s possible to add extra data to events thanks to the MDC system provided by Logback.

Mapped Tags

By default all MDC parameters are stored under the “MDC” tab in Sentry.

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

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

Note that MDC manages data on a per-thread basis, and that a child thread does not automatically inherit MDC properties from its parent.

In Practice

Copied
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MyClass {
    private static final Logger logger = LoggerFactory.getLogger(MyClass.class);

    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.addBreadcrumb("User made an action");

        // Log entries below `minimumEventLevel` and above or equal to `minimumBreadcrumbLevel`
        // are recorded as breadcrumbs
        logger.info("User made another action");

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

    void logWithExtras() {
        // MDC extras
        MDC.put("extra_key", "extra_value");
        // 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!");
    }
}
You can edit this page on GitHub.