Associate trace IDs with business logs for a Python application - Application Real-Time Monitoring Service

Cuando una solicitud falla en un sistema distribuido, resulta difícil encontrar los registros relevantes entre distintos servicios si no se cuenta con una clave de correlación. Application Real-Time Monitoring Service (ARMS) resuelve este problema al inyectar el contexto de rastreo de OpenTelemetry (ID de rastreo, ID de span y nombre del servicio) en los registros de Python. De esta forma, puede buscar registros en Simple Log Service (SLS) mediante el ID de rastreo para identificar la causa raíz.

Funcionamiento: El agente de Python de ARMS se integra con el módulo estándar logging de Python y agrega campos de contexto de rastreo a cada LogRecord. El agente solo se encarga de la inyección; no recopila ni reenvía registros. Un pipeline de recopilación de registros independiente (por lo general SLS) gestiona la entrega de los registros.

Importante

Únicamente el módulo estándar logging de Python admite la inyección automática de contexto de rastreo mediante la variable de entorno OTEL_PYTHON_LOG_CORRELATION. Structlog y otros frameworks de terceros no son compatibles con la inyección automática.

Inicio rápido

Establezca tres variables de entorno y reinicie su aplicación:

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'

Una vez que la aplicación se reinicia, cada línea de registro generada dentro de una solicitud rastreada contiene el contexto de rastreo:

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

Para obtener la configuración completa, incluida la vinculación y verificación de SLS, continúe con las siguientes secciones.

Requisitos previos

Una aplicación Python monitoreada por ARMS. Consulte Monitor Python applications.
Registros de la aplicación recopilados mediante SLS. Consulte Data collection overview.

Vincular SLS a ARMS

Vincule su proyecto y logstore de SLS a ARMS para que la consola pueda correlacionar los rastreos con los registros.

Inicie sesión en la consola de ARMS.
En el panel de navegación izquierdo, seleccione Application Monitoring > Application List.
Seleccione una región en la barra de navegación superior y haga clic en su aplicación.

Nota
Los iconos en la columna Language indican el lenguaje de programación: - : Java - : Go - : Python - - (Guion): una aplicación monitoreada en Managed Service for OpenTelemetry
En la barra de navegación superior, seleccione Configuration > Custom Configurations.
En la sección Application log Association configuration, establezca Log Source como Log service SLS. Seleccione la región donde se despliega SLS y vincule un proyecto y un logstore.

Habilitar la correlación entre rastreos y registros

Configure tres variables de entorno para activar la inyección de contexto de rastreo y definir el formato de los registros.

Variables de entorno

Variable	Propósito	Valor predeterminado
`OTEL_PYTHON_LOG_CORRELATION`	Habilita o deshabilita la correlación entre rastreos y registros. Establézcala como `true` para habilitarla. Si se establece como `false` o se deja en blanco, la correlación se deshabilita.	`false`
`OTEL_PYTHON_LOG_LEVEL`	Nivel mínimo de registro para la correlación. Valores válidos: `debug`, `info`, `warning`, `error`.	-
`OTEL_PYTHON_LOG_FORMAT`	Cadena de formato para la salida de registros. Puede personalizar el valor según sus necesidades de negocio. Utilice los campos de contexto de rastreo que se enumeran a continuación para incluir dicho contexto en la salida de registros.	-

Campos de contexto de rastreo

Utilice estos campos en la cadena de formato OTEL_PYTHON_LOG_FORMAT para incluir el contexto de rastreo en la salida de registros:

Campo	Descripción
`%(otelTraceID)s`	ID de rastreo que vincula el registro con un rastro distribuido
`%(otelSpanID)s`	ID del span generado por el registro actual
`%(otelTraceSampled)s`	Indica si el rastro está muestreado (`True` o `False`)
`%(otelServiceName)s`	Nombre de la aplicación registrado en ARMS

Establecer las variables de entorno

Establezca las siguientes variables de entorno antes de iniciar su aplicación:

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'

Después de que la aplicación se inicia, la salida de registros incluye el contexto de rastreo:

Submitting thread
INFO:     Started server process [271]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
2025-01-02 21:55:31,142 WARNING [__main__] [app.py:14] [trace_id=534xxx021eb span_id=15xxx32 resource.service.name=fastapi-agent-manual trace_sampled=True] - calling client
INFO:     127.0.0.1:59956 - "GET / HTTP/1.1" 200 OK

Agregar contexto de rastreo a controladores personalizados

El contexto de rastreo se inyecta automáticamente solo en el registrador raíz. Si utiliza controladores personalizados, configure su formateador para que lea la variable de entorno OTEL_PYTHON_LOG_FORMAT:

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)

Agregar contexto de rastreo a structlog

Si su aplicación utiliza structlog, la inyección automática de contexto de rastreo no es compatible. Agregue un procesador personalizado a su pipeline de structlog que lea el contexto de rastreo desde el SDK de OpenTelemetry:

from opentelemetry import trace
import structlog

def add_otel_context(logger, method, event_dict):
    span = trace.get_current_span()
    ctx = span.get_span_context()
    if ctx.is_valid:
        event_dict['trace_id'] = format(ctx.trace_id, '032x')
        event_dict['span_id'] = format(ctx.span_id, '016x')
    return event_dict

structlog.configure(
    processors=[
        add_otel_context,
        structlog.processors.JSONRenderer(),
    ]
)

Tras la configuración, cada entrada de structlog generada dentro de una solicitud rastreada incluye los campos trace_id y span_id. SLS utiliza estos campos para correlacionar el registro con el rastro distribuido correspondiente.

Configurar la recopilación de registros (opcional)

El agente de Python de ARMS solo se encarga de inyectar campos de contexto de rastreo en los registros. No recopila ni reenvía los registros de la aplicación. SLS recopila directamente los registros de su aplicación, por lo que no es necesario realizar ningún reporte adicional a la consola de OpenTelemetry.

Para consultar los registros correlacionados en la consola de ARMS, configure SLS para recopilar los registros de su aplicación y entregarlos al proyecto y logstore de SLS que vinculó en Vincular SLS a ARMS.

Para obtener más información sobre la recopilación de registros de SLS, consulte Data collection overview.

Verificar la configuración

Envíe una solicitud de prueba a su aplicación.

Revise la salida de registros de la aplicación. Cada línea de registro generada dentro de una solicitud rastreada contiene un valor distinto de cero para trace_id:

   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

En la consola de ARMS, abra la página de detalles del rastro correspondiente a la solicitud y confirme que los registros asociados muestran el ID de rastreo correcto.