Link Python App Logs with Trace IDs for Faster Debugging via ARMS - Application Real-Time Monitoring Service

When a request fails in a distributed system, finding the relevant logs across services is difficult without a correlation key. Application Real-Time Monitoring Service (ARMS) solves this by injecting OpenTelemetry trace context -- trace ID, span ID, and service name -- into Python log records. You can then search logs in Simple Log Service (SLS) by trace ID to pinpoint the root cause.

How it works: The ARMS Python agent hooks into Python's standard logging module and adds trace context fields to each LogRecord. The agent handles injection only -- it does not collect or forward logs. A separate log collection pipeline (typically SLS) handles log delivery.

Important

Only the Python standard logging module is supported. Other log frameworks are not supported.

Quick start

Set three environment variables and restart your application:

export OTEL_PYTHON_LOG_CORRELATION=true
export OTEL_PYTHON_LOG_LEVEL=info
export OTEL_PYTHON_LOG_FORMAT='%(asctime)s %(levelname)s [%(name)s] [%(filename)s:%(lineno)d] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s resource.service.name=%(otelServiceName)s trace_sampled=%(otelTraceSampled)s] - %(message)s'

After the application restarts, each log line produced within a traced request contains the trace context:

2026-03-10 14:30:00,123 INFO [my_app] [app.py:42] [trace_id=ac1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6 span_id=1a2b3c4d5e6f7a8b resource.service.name=my-python-app trace_sampled=True] - Order created successfully

For the full setup, including SLS binding and verification, continue with the sections below.

Prerequisites

A Python application monitored by ARMS. See Monitor Python applications.
Application logs collected through SLS. See Data collection overview.

Bind SLS to ARMS

Link your SLS project and Logstore to ARMS so the console can correlate traces with logs.

Log on to the ARMS console.
In the left-side navigation pane, choose Application Monitoring > Application List.
Select a region in the top navigation bar and click your application.
Note
Icons in the Language column indicate the programming language: - : Java - : Go - : Python - - (Hyphen): an application monitored in Managed Service for OpenTelemetry
In the top navigation bar, choose Configuration > Custom Configurations.
In the Application log Association configuration section, set Log Source to Log service SLS. Select the region where SLS is deployed, and bind a project and a Logstore.

Enable trace-log correlation

Configure three environment variables to activate trace context injection and define the log format.

Environment variables

Variable	Purpose	Default
`OTEL_PYTHON_LOG_CORRELATION`	Enable or disable trace-log correlation. Set to `true` to enable. If set to `false` or left blank, correlation is disabled.	`false`
`OTEL_PYTHON_LOG_LEVEL`	Minimum log level for correlation. Valid values: `debug`, `info`, `warning`, `error`.	-
`OTEL_PYTHON_LOG_FORMAT`	Format string for log output. You can customize the value based on your business requirements. Use the trace context fields listed below to include trace context in log output.	-

Trace context fields

Use these fields in the OTEL_PYTHON_LOG_FORMAT format string to include trace context in log output:

Field	Description
`%(otelTraceID)s`	Trace ID that links the log to a distributed trace
`%(otelSpanID)s`	The ID of the span generated by the current log
`%(otelTraceSampled)s`	Whether the trace is sampled (`True` or `False`)
`%(otelServiceName)s`	Application name registered in ARMS

Set the environment variables

Set the following environment variables before starting your application:

export OTEL_PYTHON_LOG_CORRELATION=true
export OTEL_PYTHON_LOG_LEVEL=info
export OTEL_PYTHON_LOG_FORMAT='%(asctime)s %(levelname)s [%(name)s] [%(filename)s:%(lineno)d] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s resource.service.name=%(otelServiceName)s trace_sampled=%(otelTraceSampled)s] - %(message)s'

After the application starts, log output includes trace context:

Add trace context to custom handlers

Trace context is automatically injected into the root logger only. If you use custom handlers, set their formatter to read from the OTEL_PYTHON_LOG_FORMAT environment variable:

import os
import logging

# Read the format string from the environment variable
log_format = os.getenv('OTEL_PYTHON_LOG_FORMAT')

# Create a custom handler with trace context fields
my_handler = logging.StreamHandler()
formatter = logging.Formatter(log_format)
my_handler.setFormatter(formatter)

# Attach the handler to a logger
logger = logging.getLogger('my_module')
logger.addHandler(my_handler)
logger.setLevel(logging.INFO)

Configure log collection (optional)

By default, the ARMS Python agent does not collect application logs. To view correlated logs in the ARMS console, configure a log collection pipeline to upload logs to the SLS project and Logstore that you bound in the previous section.

For more information, see Data collection overview.

Verify the configuration

Send a test request to your application.

Check the application log output. Each log line produced within a traced request contains a non-zero trace_id value:

   2026-03-10 14:30:00,123 INFO [my_app] [app.py:42] [trace_id=ac1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6 span_id=1a2b3c4d5e6f7a8b resource.service.name=my-python-app trace_sampled=True] - Order created successfully

In the ARMS console, open the trace details page for the request and confirm that the associated logs display the correct trace ID.