#Correlating Application Logs with Traces

When the OpenTelemetry Java agent instruments your application, it can automatically add the active trace context — trace_id, span_id, and trace_flags — to your application's logging context (MDC). By printing these values in your log output, you can pivot directly from a log line to its corresponding trace, and from a trace back to the logs that a request produced.

This page explains how to surface the trace context in logs for Java applications.

#How it works

The Java agent ships logging instrumentations that copy the current span context into your logging library's MDC (Mapped Diagnostic Context). You do not parse HTTP headers or write any code to do this — the agent extracts the context from propagation headers and populates the MDC automatically. The injected keys are:

These keys use snake_case and are the agent's built-in defaults. Injection is enabled by default, so the only thing you have to do is reference the keys in your log output pattern.

The instrumentation is matched to your logging library:

If you ever need to turn a specific injection off (or back on), set the corresponding property or environment variable on the workload. Each defaults to true:

#Surfacing the IDs in your log output

Choose the option that matches how your application is configured. All three reference the same snake_case MDC keys, so a sampled request produces a log line such as:

2026-06-12 10:15:42.123 trace_id=4bf92f3577b34da6a3ce929d0e0e4736 span_id=00f067aa0ba902b7 trace_flags=01 INFO  ProviderController - request /hello

#Spring Boot

For a Spring Boot application, the simplest approach is to override logging.pattern.level so the IDs are prepended to every log line without rewriting the whole pattern:

logging.pattern.level = trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p

#Logback

If you manage your own logback.xml or logback-spring.xml, reference the keys with %X{...} (which is equivalent to %mdc{...} in Logback) inside the pattern:

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %-5level %logger{36} - %msg%n</pattern>
  </encoder>
</appender>

For applications that rely on Spring Boot's default console appender, you can override the CONSOLE_LOG_PATTERN property instead, embedding the same %X{trace_id} tokens in the pattern.

#Log4j 2

For Log4j 2, reference the keys with %X{...} in a PatternLayout:

<Console name="Console" target="SYSTEM_OUT">
  <PatternLayout
    pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %-5p %c{1} - %m%n"/>
</Console>

#OpenTelemetry agent keys vs. Spring Boot / Micrometer native correlation

#Exporting logs through OTLP

The patterns above are for textual logs (console or file) that are read or scraped as text. If you instead export logs directly through OTLP, the trace_id and span_id are carried in the OTLP log record's dedicated fields rather than as MDC attributes, so OTLP-exported logs stay correlated without adding the IDs to the log pattern.

#Other languages

The other OpenTelemetry languages also correlate logs with traces under zero-code (auto-instrumentation), but the injected field names and how you enable them differ per language. Refer to the upstream guidance for the language you use:

#References

• Logger MDC auto-instrumentation — the authoritative list of injected keys and supported logging libraries.
• Logback MDC instrumentation README — pattern examples and configuration options.
• Java agent configuration and suppressing specific instrumentation — how to toggle individual instrumentations.