Connecting Java Logs and Traces

Automatically Inject Trace and Span IDs

Enable injection in the Java tracer’s configuration by adding -Ddd.logs.injection=true as a jvm startup argument or through environment variable DD_LOGS_INJECTION=true.

If your logs are JSON formated and you are using Logback there is nothing left to do. Otherwise with other logging libraries you need to activate MDC attributes autoinjection into your logs.

If your logs are raw formatted, update your formatter to include dd.trace_id and dd.span_id in your logger configuration:

<Pattern>"%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %X{dd.trace_id} %X{dd.span_id} - %m%n"</Pattern>

<Pattern>"%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %X{dd.trace_id:-0} %X{dd.span_id:-0} - %m%n"</Pattern>

Note: If the attribute.path for your trace ID is not dd.trace_id, ensure your trace ID reserved attribute settings account for the attribute.path. More information can be found in the FAQ on this topic.

Manually Inject Trace and Span IDs

If you prefer to manually correlate your traces with your logs, leverage the Datadog API to retrieve correlation identifiers:

• Use CorrelationIdentifier#getTraceId() and CorrelationIdentifier#getSpanId() API methods to inject identifiers at the beginning and end of each span to log (see examples below).

• Configure MDC to use the injected Keys:

  • dd.trace_id Active Trace ID during the log statement (or 0 if no trace)
  • dd.span_id Active Span ID during the log statement (or 0 if no trace)

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", String.valueOf(CorrelationIdentifier.getTraceId()));
    ThreadContext.put("dd.span_id", String.valueOf(CorrelationIdentifier.getSpanId()));
}

// Log something

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

<Pattern>"%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %X{dd.trace_id} %X{dd.span_id} - %m%n"</Pattern>

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", String.valueOf(CorrelationIdentifier.getTraceId()));
    MDC.put("dd.span_id", String.valueOf(CorrelationIdentifier.getSpanId()));
}

// Log something

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

<Pattern>"%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %X{dd.trace_id:-0} %X{dd.span_id:-0} - %m%n"</Pattern>

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. More information can be found in the FAQ on this topic.

See the Java logging documentation for more details about specific logger implementation or to learn how to log in JSON.

Further Reading

Additional helpful documentation, links, and articles:

Instrument manually your application to create traces.DOCUMENTATION Implement Opentracing across your applications.DOCUMENTATION Explore your services, resources, and tracesDOCUMENTATION Correlate request logs with traces automaticallyBLOG