Documentation forAppOptics

Trace context in logs (legacy agent)

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

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 Python Library, see the SolarWinds Python 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 Python agent can automatically add the trace context to logs generated by the Python logging module and other logging modules based on this standard module. In particular, it will add:

  • A string of the form ao.traceId=7435A9FE510AE4533414D425DADF4E180D2B4E36-0 to the beginning of each logged message
  • A custom entry in the LogRecord dictionary of the form 'ao': {'traceId': '7435A9FE510AE4533414D425DADF4E180D2B4E36-0'}.


This feature is disabled by default. Refer to Trace Context in Logs for information on how to enable it and the provided configuration options.

Automatic Insertion

Automatic insertion works for any logger that uses the Python logging module. When a message is logged, the logging facility creates a LogRecord instance which contains all information related to the event being logged. The Python agent will automatically add a new ao attribute to the created LogRecord instance, where the added attribute is itself a dictionary containing the Trace ID as {'traceId': <traceId>}.

In addition to the extension of the LogRecord instance, the agent will also insert the TraceId into the formatted message when it is emitted by a Handler. This insertion happens automatically without the need of modifying the Formatter of the respective Handler. The Trace ID will be injected at the beginning of the actual message to be logged (i.e., the string which is returned by the getMessage function of the LogRecord instance).


When this feature is enabled, the following code

import appotics_apm
import logging

logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
logging.warning('Warning to be logged.')

will produce a log message like: 2020-01-02 11:12:13,695 - root - WARNING - ao.traceId=7435A9FE510AE4533414D425DADF4E180D2B4E36-0 Warning to be logged.

Note that this automatic injection will only be performed if the message is passed through the formatter native to the logging module (i.e., logging.Formatter).

The trace context can also be added to structured logs generated by logging facilities which build on top of the native Python logging module, e.g. the python-json-logger library, by making use of the dictionary added to the attributes of the LogRecord instance.

Using the SDK

If your logging setup is not supported for automatic insertion, or for finer control, you can use the appoptics_apm.get_log_trace_id function which provides a convenient way to insert trace context into any kind of logs. Refer to Log Trace ID for more information.

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.