Associate trace IDs with business logs for a Python application - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Em sistemas distribuídos, localizar logs relevantes entre vários serviços após uma falha de requisição é difícil sem uma chave de correlação. O Application Real-Time Monitoring Service (ARMS) resolve esse problema ao injetar o contexto de rastreamento do OpenTelemetry — trace ID, span ID e nome do service — nos registros de log Python. Assim, você pode pesquisar logs no Simple Log Service (SLS) por trace ID para identificar a causa raiz com precisão.

Como funciona: O agente Python do ARMS integra-se ao módulo padrão logging do Python e adiciona campos de contexto de rastreamento a cada LogRecord. O agente cuida apenas da injeção; ele não coleta nem encaminha logs. Um pipeline separado de coleta de logs (geralmente o SLS) gerencia a entrega dos logs.

Importante

Somente o módulo padrão logging do Python oferece suporte à injeção automática de contexto de rastreamento por meio da variável de ambiente OTEL_PYTHON_LOG_CORRELATION. O Structlog e outros frameworks de terceiros não suportam injeção automática.

Início rápido

Defina três variáveis de ambiente e reinicie sua aplicação:

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'

Após reiniciar a aplicação, cada linha de log gerada durante uma requisição rastreada contém o contexto de rastreamento:

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 obter a configuração completa, incluindo a vinculação e verificação do SLS, continue nas seções abaixo.

Pré-requisitos

Uma aplicação Python monitorada pelo ARMS. Consulte Monitor Python applications.
Logs da aplicação coletados por meio do SLS. Consulte Data collection overview.

Vincule o SLS ao ARMS

Vincule seu projeto e Logstore do SLS ao ARMS para que o console possa correlacionar traces com logs.

Faça login no console do ARMS.
No painel de navegação à esquerda, escolha Application Monitoring > Application List.
Selecione uma região na barra de navegação superior e clique em sua aplicação.

Nota
Os ícones na coluna Language indicam a linguagem de programação: - : Java - : Go - : Python - - (Hífen): uma aplicação monitorada no Managed Service for OpenTelemetry
Na barra de navegação superior, escolha Configuration > Custom Configurations.
Na seção Application log Association configuration, defina Log Source como Log service SLS. Selecione a região onde o SLS está implantado e vincule um projeto e um Logstore.

Ative a correlação entre trace e log

Configure três variáveis de ambiente para ativar a injeção de contexto de rastreamento e definir o formato do log.

Variáveis de ambiente

Variável	Finalidade	Padrão
`OTEL_PYTHON_LOG_CORRELATION`	Ativa ou desativa a correlação entre trace e log. Defina como `true` para ativar. Se definida como `false` ou deixada em branco, a correlação fica desativada.	`false`
`OTEL_PYTHON_LOG_LEVEL`	Nível mínimo de log para correlação. Valores válidos: `debug`, `info`, `warning`, `error`.	-
`OTEL_PYTHON_LOG_FORMAT`	String de formatação para a saída de log. Personalize o valor conforme suas necessidades de negócio. Utilize os campos de contexto de rastreamento listados abaixo para incluir o contexto de rastreamento na saída de log.	-

Campos de contexto de rastreamento

Utilize estes campos na string de formatação OTEL_PYTHON_LOG_FORMAT para incluir o contexto de rastreamento na saída de log:

Campo	Descrição
`%(otelTraceID)s`	Trace ID que vincula o log a um trace distribuído
`%(otelSpanID)s`	ID do span gerado pelo log atual
`%(otelTraceSampled)s`	Indica se o trace foi amostrado (`True` ou `False`)
`%(otelServiceName)s`	Nome da aplicação registrado no ARMS

Defina as variáveis de ambiente

Defina as seguintes variáveis de ambiente antes de iniciar sua aplicação:

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'

Após o início da aplicação, a saída de log inclui o contexto de rastreamento:

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

Adicione contexto de rastreamento a handlers personalizados

A injeção automática de contexto de rastreamento ocorre apenas no logger raiz. Caso utilize handlers personalizados, configure o formatador deles para ler a variável de ambiente 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)

Adicione contexto de rastreamento ao structlog

Se sua aplicação utiliza structlog, a injeção automática de contexto de rastreamento não tem suporte. Adicione um processador personalizado ao seu pipeline do structlog para ler o contexto de rastreamento do SDK do 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(),
    ]
)

Após a configuração, cada entrada do structlog gerada durante uma requisição rastreada inclui os campos trace_id e span_id. O SLS utiliza esses campos para correlacionar o log com o trace distribuído correspondente.

Configure a coleta de logs (opcional)

O agente Python do ARMS é responsável apenas por injetar campos de contexto de rastreamento nos registros de log. Ele não coleta nem encaminha logs da aplicação. O SLS coleta seus logs diretamente — nenhum relatório adicional para o console do OpenTelemetry é necessário.

Para visualizar logs correlacionados no console do ARMS, configure o SLS para coletar logs da sua aplicação e entregá-los ao projeto e Logstore do SLS vinculados em Vincule o SLS ao ARMS.

Para mais informações sobre a coleta de logs do SLS, consulte Data collection overview.

Verifique a configuração

Envie uma requisição de teste para sua aplicação.

Verifique a saída de log da aplicação. Cada linha de log gerada durante uma requisição rastreada deve conter um valor trace_id diferente de zero:

   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

No console do ARMS, abra a página de detalhes do trace para a requisição e confirme se os logs associados exibem o trace ID correto.