Trace context in logs (legacy agent)

The following content pertains to trace context in logs for the legacy AppOptics Java Agent.

Adding trace context to application logs provides the ability to correlate the log messages from a traced transaction, and if sampled, the log messages to the transaction trace detail.

The AppOptics Java agent offers several options to include trace context into logs managed by several popular Java logging frameworks, and provides a custom SDK call which can be used if the automatic options do not support your logger.

How to Add Trace Context to Logs

There are 3 options to include trace context into logs:

Automatic Attribute in MDC/Thread Context

Logging frameworks such as Log4j 1.2, Log4j 2 and Logback/Slf4j provide implementation of MDC (Mapped Diagnostic Context), which basically is a map that provides context information when a log message is constructed.

Our agent inserts ao.traceId into the MDC map with the Trace ID value.

Such a value can then be included in the logging layout by using pattern such as %X{ao.traceId}

This feature is disabled by default, more detail can be found in the Configuration section.

Automatic Insertion

Our Agent can automatically insert an extra node into structured logs with trace context information.

The inserted node will have key ao.traceId

Auto-insert is only supported for Log4j2 for YAML, JSON and XML layout.

This feature is disabled by default, more details can be found in the Configuration section.

Using the SDK

Trace context can be manually inserted into log messages; this can be used if your application logger is not supported by the automatic options above. The string value of the Trace context can be obtained using the SDK method Trace.getCurrentLogTraceID. Note that if the agent is not available or not started propertly, the value will be an empty string.

Supported Frameworks

Log4j 1.2

Our agent provides automatic attribute for MDC, the trace context is inserted into MDC with key ao.traceId

A quick example for PatternLayout using MDC

%d %p [%c{1}] %X{ao.traceId} - %m%n

Log4j 2

Our agent supports automatic attribute for Thread Context, and automatic insertion.

A quick example for PatternLayout using Log4j 2 Thread Context

%d %p [%c{1}] %X{ao.traceId} - %m%n

For automatic insertion, our agent supports the YAML, XML and JSON layouts (under Jackson). For example, if enabled, then XML node as below will be inserted into the log output Event node.

<ao.traceId>9576DAF3275C079CE6778773600301BD78CD67D8-1</ao.traceId>

Logback/Slf4j

Our agent supports automatic attribute for MDC.

A quick example of setting the pattern in encoder using MDC:

<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{50} %X{ao.traceId} - %msg%n</pattern>

Take note that even though we do not support automatic insertion for Logback, most of the structured layouts for Logback should output the MDC values by default.

For example, when automatic attribute for MDC is enabled, this is the output of the JSON layout:

"mdc" : {
  "ao.traceId" : "5DADC78A4B1572FBE88548447849075A7B8821A1-1"
},

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.