Trace context in logs (legacy agent)
The following content pertains to
AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries can send APM data in AppOptics and are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider transitioning to the SolarWinds Observability libraries for your APM needs. For more information about the benefits of migrating to the SolarWinds Observability libraries. Alternatively, you can use SolarWinds Observability as your primary APM solution.
If you have already transitioned to the new SolarWinds Observability Java Library, see the SolarWinds Java Library documentation for trace context in logs information.
SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.
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%nLog4j 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%nFor 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.