Python应用业务日志关联调用链TraceId - 应用实时监控服务ARMS

您可以在Python应用的业务日志中关联调用链的TraceId信息，从而在应用出现问题时，能够通过调用链的TraceId快速关联到业务日志，及时定位、分析并解决问题。

前提条件

已将Python应用接入ARMS。
已通过日志服务SLS完成日志采集，具体操作，请参见数据采集概述。

背景信息

ARMS 在业务日志中关联调用链 TraceId 的功能是基于对日志框架的埋点，目前支持 Python 官方日志框架 Logging。如果您使用 StructLog 等结构化日志框架，ARMS Python 探针不支持通过环境变量自动注入 TraceId，需要在 StructLog 的 Processor 链中手动读取 OpenTelemetry 当前上下文，并将 trace_id 字段加入日志事件。

开启关联业务日志与TraceId开关

登录ARMS控制台，在左侧导航栏选择应用监控 > 应用列表。
在应用列表页面顶部选择目标地域，然后单击目标应用名称。
说明
语言列的图标含义如下：
：接入应用监控的Java应用。
：接入应用监控的Golang应用。
：接入应用监控的Python应用。
-：接入可观测链路 OpenTelemetry 版的应用。
在上方导航栏选择应用配置 > 自定义配置。
在自定义配置页签的应用日志关联配置区域，选择日志源为日志服务SLS，选择日志服务所在地域，然后绑定Project和Logstore。

配置Python探针。

设置如下环境变量，在探针中开启关联业务日志与TraceId功能。
```
# 默认为false
OTEL_PYTHON_LOG_CORRELATION=true   
```
说明
环境变量OTEL_PYTHON_LOG_CORRELATION设置为true则开启关联业务日志与TraceId，不设置或设置为false则关闭业务日志与TraceId关联。
通过以下环境变量设置需要关联TraceId的业务日志级别。
```
#  设置需要关联traceId的日志级别，可选值为：debug、info、warning、error
OTEL_PYTHON_LOG_LEVEL=warning
```
说明
环境变量OTEL_PYTHON_LOG_LEVEL设置为warning则日志级别为warning及以上的日志会关联TraceId。

通过以下环境变量设置关联TraceId后的日志格式，您可以根据需求自行增减格式内容。

#   设置日志格式, 以下是默认格式。可以根据需求增减。
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"

otelTraceID：TraceId
otelSpanID：当前日志生成所属的SpanId
otelTraceSampled：采样标识
otelServiceName：应用名称

日志关联TraceId只支持自动关联root logger，如需自动关联自定义handler中日志，请手动配置formatter格式。
```
formatter = logging.Formatter(os.getenv('OTEL_PYTHON_LOG_FORMAT'))
my_handler.setFormatter(formatter)
```

以上环境变量配置完成后，打印的日志格式如下。

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

（可选）配置 SLS 日志采集接入，将应用日志上传至上述步骤绑定的 Project 和 Logstore 中。

ARMS Python 探针默认不会采集应用日志，探针仅负责在日志记录中注入 Trace 上下文字段。应用日志由 SLS 直接采集，无需额外上报到 OpenTelemetry 控制台。

常见问题

vLLM服务框架打印的日志为什么无法关联TraceId?
- 因为vLLM框架默认会使用自定义的handler来控制日志的输出格式以及输出方式，您可以通过配置VLLM_LOGGING_PREFIX环境变量来进行关联，例如：
```
export VLLM_LOGGING_PREFIX="[%(filename)s:%(lineno)d] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s resource.service.name=%(otelServiceName)s trace_sampled=%(otelTraceSampled)s]"
```