Python應用業務日誌關聯調用鏈TraceId - Application Real-Time Monitoring Service

您可以在Python應用的業務日誌中關聯調用鏈的TraceId資訊，從而在應用出現問題時，能夠通過調用鏈的TraceId快速關聯到業務日誌，及時定位、分析並解決問題。

前提條件

已將Python應用接入ARMS。
已通過Log ServiceSLS完成日誌採集，具體操作，請參見資料擷取概述。

背景資訊

ARMS 在業務日誌中關聯調用鏈 TraceId 的功能是基於對日誌架構的埋點，目前支援 Python 官方日誌架構 Logging。如果您使用 StructLog 等結構化日誌架構，ARMS Python 探針不支援通過環境變數自動注入 TraceId，需要在 StructLog 的 Processor 鏈中手動讀取 OpenTelemetry 當前上下文，並將 trace_id 欄位加入日誌事件。

開啟關聯業務日誌與TraceId開關

登入ARMS控制台，在左側導覽列選擇應用監控 > 應用列表。
在應用列表頁面頂部選擇目標地區，然後單擊目標應用程式名稱。
說明
語言列的表徵圖含義如下：
：接入應用監控的Java應用。
：接入應用監控的Golang應用。
：接入應用監控的Python應用。
-：接入Managed Service for OpenTelemetry的應用。
在上方導覽列選擇應用配置 > 自定義配置。
在自定義配置頁簽的應用日誌關聯配置地區，選擇日誌源為Log ServiceSLS，選擇Log Service所在地區，然後綁定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]"
```