Before you begin

Ensure log collection is configured. See Java Log Collection for Log4j, Log4j 2, or Logback instructions.

Automatic injection

Starting in version 0.74.0, the Java tracer automatically injects trace correlation identifiers into JSON formatted logs. For earlier versions, enable automatic injection in the Java tracer by adding dd.logs.injection=true as a system property, or through the environment variable DD_LOGS_INJECTION=true. Full configuration details can be found on the Java tracer configuration page.

For a more universal, configuration-based approach, you can also use OpenTelemetry’s log appenders. See Correlating OpenTelemetry Traces and Logs for setup instructions.

Notes:

• Automatic injection of trace correlation is available for Log4j2, Log4j, or SLF4J and Logback.
• If the attribute.path for your trace ID is not dd.trace_id, ensure that your trace ID reserved attribute settings account for the attribute.path. For more information, see Correlated Logs Not Showing Up in the Trace ID Panel.

Manual injection

If you prefer to manually add correlation identifiers to your logs, you can use a tracing API. Datadog recommends using the standard OpenTelemetry API for vendor-neutrality and broader compatibility. Alternatively, you can use the Datadog-specific API.

OpenTelemetry API (Recommended)

To correlate logs and traces with the OpenTelemetry API, first add the opentelemetry-api dependency to your project.

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.40.0</version> <scope>provided</scope>
</dependency>

compileOnly 'io.opentelemetry:opentelemetry-api:1.40.0'

compileOnly("io.opentelemetry:opentelemetry-api:1.40.0")

After adding the dependency, use the OpenTelemetry Span class to access the current trace and span IDs and add them to your logging context.

For example:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import org.slf4j.MDC;

// ...

SpanContext spanContext = Span.current().getSpanContext();
if (spanContext.isValid()) {
   try {
        MDC.put("dd.trace_id", spanContext.getTraceId());
        MDC.put("dd.span_id", spanContext.getSpanId());
        // Log something
    } finally {
        MDC.remove("dd.trace_id");
        MDC.remove("dd.span_id");
    }
}

Note: If no span is active, spanContext.isValid() returns false, and no IDs are added to the logs.

Datadog API

To manually correlate logs and traces with the Datadog API, add the dd-trace-api dependency to your project.

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>dd-trace-api</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

implementation 'com.datadoghq:dd-trace-api:LATEST_VERSION'

implementation("com.datadoghq:dd-trace-api:LATEST_VERSION")

Replace LATEST_VERSION with the same version as your Datadog Java tracer (dd-java-agent).

After you add the dependency, use CorrelationIdentifier.getTraceId() and CorrelationIdentifier.getSpanId() to retrieve and inject the IDs into your logging context, as shown in the following examples.

import org.apache.logging.log4j.ThreadContext;
import datadog.trace.api.CorrelationIdentifier;

// There must be spans started and active before this block.
try {
    ThreadContext.put("dd.trace_id", CorrelationIdentifier.getTraceId());
    ThreadContext.put("dd.span_id", CorrelationIdentifier.getSpanId());

// Log something

} finally {
    ThreadContext.remove("dd.trace_id");
    ThreadContext.remove("dd.span_id");
}

import org.slf4j.MDC;
import datadog.trace.api.CorrelationIdentifier;

// There must be spans started and active before this block.
try {
    MDC.put("dd.trace_id", CorrelationIdentifier.getTraceId());
    MDC.put("dd.span_id", CorrelationIdentifier.getSpanId());

// Log something

} finally {
    MDC.remove("dd.trace_id");
    MDC.remove("dd.span_id");
}

import org.tinylog.ThreadContext;
import datadog.trace.api.CorrelationIdentifier;

// There must be spans started and active before this block.
try {
    ThreadContext.put("dd.trace_id", CorrelationIdentifier.getTraceId());
    ThreadContext.put("dd.span_id", CorrelationIdentifier.getSpanId());

// Log something

} finally {
    ThreadContext.remove("dd.trace_id");
    ThreadContext.remove("dd.span_id");
}

Note: If you are not using a Datadog Log Integration to parse your logs, custom log parsing rules need to ensure that dd.trace_id and dd.span_id are being parsed as strings. For more information, see Correlated Logs Not Showing Up in the Trace ID Panel.

See the Java log collection documentation for more details about specific logger implementation and instructions for logging in JSON format.

Further Reading

Additional helpful documentation, links, and articles:

Manually instrument your application to create traces.DOCUMENTATION Explore your services, resources, and tracesDOCUMENTATION Correlate request logs with traces automaticallyBLOG Ease troubleshooting with cross product correlation.GUIDE