Java Log Correlation - Atatus Docs

Atatus Java APM Agent extends your application’s logging capabilities with log correlation, allowing you to connect logs, traces, and errors for easier debugging and deeper observability. These features help you:

Automatically include trace, transaction, and error IDs in your application logs.
Seamlessly connect logs and traces within the Atatus dashboard.
Navigate from any log entry to its corresponding trace or error and vice versa.

Log Correlation

Log correlation lets you trace individual requests across systems by automatically adding correlation identifiers (trace, transaction, and error IDs) to your logs. With log correlation enabled, the Atatus Java Agent automatically injects these identifiers into the slf4j MDC (or its equivalent) of supported logging frameworks:

Field	Description
`trace.id`	Uniquely identifies a request across distributed services
`transaction.id`	Marks the primary transaction being traced
`error.id`	Correlates a log entry with a captured exception

These IDs connect your logs with traces and errors, making it easy to jump from a log entry to its related transaction or exception inside the Atatus dashboard. Note: Log correlation is enabled by default in all versions of the Atatus Java Agent, so no additional configuration is required.

Supported Logging Frameworks

The Atatus Java Agent supports correlation injection for the following logging frameworks:

Framework	Supported Versions	Notes
slf4j	`1.4.1+`	Standard slf4j MDC
Logback	`1.1.x` to `1.4.x`	Uses slf4j MDC
log4j2	`2.0+`	Uses `ThreadContext` for correlation
log4j1	`1.x`	Uses MDC
JBoss Logging	`3.x`	Uses JBoss MDC implementation
java.util.logging (JUL)	All supported Java versions	Correlation only via log reformatting
Tomcat JULI	`7.x` to `10.x`	Trace correlation requires log reformatting

For frameworks like java.util.logging (JUL) that do not provide a native MDC, correlation is supported only by enabling log reformatting in the agent.

Correlation in Structured Logs

For structured logging (such as JSON), the Atatus Java Agent automatically injects the correlation IDs into the logger’s MDC (Mapped Diagnostic Context). Since structured log encoders serialize MDC entries as part of the log record by default, the trace.id, transaction.id, and error.id fields appear in your log output without any additional configuration.

Correlation in Unstructured (Plain Text) Logs

When using unstructured (plain text) log formats with Logback or log4j, you must update your logging pattern layout to include the MDC values so that the injected correlation IDs appear in your log output. Add %X to log all MDC values, or %X{trace.id} to log only the trace ID.

Logback Example

Update your logback.xml pattern to include the correlation IDs:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [trace.id=%X{trace.id} transaction.id=%X{transaction.id}] %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

log4j2 Example

Update your log4j2.xml pattern layout:

<Configuration>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - [trace.id=%X{trace.id} transaction.id=%X{transaction.id}] %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

Example Log Output

After applying the pattern changes above, your plain text logs will look like:

10:40:00.123 [http-nio-8080-exec-1] INFO  com.example.MyController - [trace.id=b899fc7915e801b7558e336e4952bafe transaction.id=c1ae84c8642891eb] Processing request
10:40:00.456 [http-nio-8080-exec-1] INFO  com.example.MyService - [trace.id=b899fc7915e801b7558e336e4952bafe transaction.id=c1ae84c8642891eb] Completed successfully

Error Capturing and Correlation

When an exception is reported to the logger using calls like:

logger.error("Something went wrong", exception);

The Atatus Java Agent automatically:

Reports the error to the Atatus dashboard.
Generates an error.id and injects it into the logger MDC for the duration of the logger invocation.
Includes the error.id in the log output (provided the log pattern allows it).

This makes it easy to jump from a logged exception directly to the corresponding error entry in the Atatus dashboard.

​Log Correlation

​Supported Logging Frameworks

​Correlation in Structured Logs

​Correlation in Unstructured (Plain Text) Logs

​Logback Example

​log4j2 Example

​Example Log Output

​Error Capturing and Correlation