Documentation forAppOptics

Trace context in logs (legacy agent)

The following content pertains to trace context in logs for the legacy AppOptics PHP 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 PHP Library, see the SolarWinds PHP 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 PHP agent can automatically append the trace context to internal errors/warnings and PHP logs generated with the error_log function. See Automatic Insertion of Trace ID into Logs for information on how to configure automatic insertion.

Logging Frameworks in PHP have their own ways of handling log messages; in this case, you can use the SDK function appoptics_get_log_trace_id() to add the trace context to messages. Below are examples on how to do this for some of the most popular frameworks.


Capturing the trace context can be done via a monolog_processor:

$logger->pushProcessor(function ($record) {
  $record['message'] .= sprintf(' [ao.traceId=%s]', appoptics_get_log_trace_id());
  return $record;


In log4PHP, either the NDC or the MDC Logger can be used to add the trace context to log mesages.


LoggerNDC::push(sprintf('ao.traceId=%s', appoptics_get_log_trace_id()));

In the configuration file use the LoggerLayoutPattern and in the value of the conversion pattern, add %x wherever the trace context should appear.


LoggerMDC::put("ao.traceId", sprintf('%s', appoptics_get_log_trace_id()));

In the configuration file use the LoggerLayoutPattern and in the value of the conversion pattern, add ao.traceId=%X{ao.traceId} wherever the trace context should appear.


KLogger does not provide a way to automatically insert custom values but it allows for a $context variable, that adds custom KVs to a log message. In order to add the trace context to the logs, create the context:

$context = ['ao.traceId' => appoptics_get_log_trace_id()];

This variable then can be passed in together with the log message:

$logger->error('An error log', $context);


Analog allows for custom handlers be defined:

function appopticsInit($handler) {
  return function ($info) use ($handler) {
    $info["message"] .= sprintf(' [ao.traceId=%s]', appoptics_get_log_trace_id());

Register this handler with Analog and pass in any other handler of choice, e.g.:




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.