Documentation forAppOptics

Trace context in logs (legacy agent)

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

AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries 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 migrating to SolarWinds Observability.

If you have already transitioned to the new SolarWinds Observability Ruby Library, see the SolarWinds Ruby 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.

Overview

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 Ruby agent can automatically add the trace context to logs. It will do so by adding a string like ‘ao.traceId=7435A9FE510AE4533414D425DADF4E180D2B4E36-0' to the end of each logged line.

Configuration

This feature can be enabled in the Configuration File via the AppOpticsAPM::Config[:log_traceId] setting, which takes the following options:

  • :never (default)
  • :sampled only include the Trace ID for sampled requests
  • :traced include the Trace ID for all traced requests
  • :always always add a Trace ID. It will be ‘0000000000000000000000000000000000000000-0’ when there is no tracing context.

Automatic Insertion

Automatic insertion works for any Logger that uses Logger::Formatter, including:

  • ActiveSupport::Logger which uses ActiveSupport::Logger::SimpleFormatter < Logger::Formatter
  • ActiveSupport::TaggedLogging which usually extends Logger::Formatter with its own formatter

The gems lumberjack and logging are also supported.

Using the SDK

If your logger is not supported for automatic insertion, or for finer control, you can use the AppOpticsAPM::SDK to add Trace ID to application logs. Below are examples for popular logging libaries.

Lograge

Lograge is a formatter for Rails logs currently not supported for automatic insertion. Instead you can use its custom_options and our SDK to configure lograge to include the Trace ID:

Lograge.custom_options = lambda do |event|
  AppOpticsAPM::SDK.current_trace.hash_for_log
end

The hash_for_log SDK method respects the configuration settings for AppOpticsAPM::Config[:log_traceId]. For example: It will return an empty hash if the setting is :never

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.