Em sistemas distribuídos, localizar logs relevantes entre diversos serviços após uma falha é 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 serviço — nos registros de log Python. Assim, você pode pesquisar logs no Simple Log Service (SLS) pelo trace ID para identificar a causa raiz.
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 (geralmente o SLS) gerencia a entrega dos logs.
Apenas o módulo padrão logging do Python tem suporte. Outros frameworks de log não são compatíveis.
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 conterá 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 successfullyPara obter a configuração completa, incluindo a vinculação ao SLS e a verificação, prossiga com as seções abaixo.
Pré-requisitos
Uma aplicação Python monitorada pelo ARMS. Consulte Monitorar aplicações Python.
Logs da aplicação coletados por meio do SLS. Consulte Visão geral da coleta de dados.
Vincule o SLS ao ARMS
Vincule seu projeto e Logstore do SLS ao ARMS para que o console possa correlacionar rastreamentos com logs.
Faça login no console do ARMS.
No painel de navegação à esquerda, escolha .
-
Selecione uma região na barra de navegação superior e clique em sua aplicação.
NotaOs í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 rastreamento 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 |
|
|
Ativa ou desativa a correlação entre rastreamento e log. Defina como |
|
|
|
Nível mínimo de log para correlação. Valores válidos: |
- |
|
|
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 essas informações na saída. |
- |
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 |
|
|
Trace ID que vincula o log a um rastreamento distribuído |
|
|
ID do span gerado pelo log atual |
|
|
Indica se o rastreamento foi amostrado ( |
|
|
Nome da aplicação registrado no ARMS |
Defina as variáveis de ambiente
Configure 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'Depois que a aplicação iniciar, a saída de log incluirá o contexto de rastreamento:
Adicione contexto de rastreamento a handlers personalizados
O contexto de rastreamento é injetado automaticamente 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)Configure a coleta de logs (opcional)
Por padrão, o agente Python do ARMS não coleta logs da aplicação. Para visualizar logs correlacionados no console do ARMS, configure um pipeline de coleta para enviar os logs ao projeto e Logstore do SLS vinculados na seção anterior.
Para mais informações, consulte Visão geral da coleta de dados.
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 gerada dentro de uma requisição rastreada deve conter um valor
trace_iddiferente 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 rastreamento para a requisição e confirme se os logs associados exibem o trace ID correto.