控制 LLM 應用對話歷史採集行為 - Application Real-Time Monitoring Service

預設情況下，探針會在 LLM 相關調用（如 LLM 調用、agent 調用）中記錄對話歷史，對話歷史內容格式遵循 OpenTelemetry 規範。本文介紹如何配置 LLM 應用的對話歷史採集行為。

為適配多種記錄情境，當前ARMS探針支援以下三種對話歷史採集與記錄模式：

將交談記錄在 Span Attributes 中（預設）。
停止記錄對話歷史。
將交談記錄在日誌中。

您可以通過調整配置，修改 LLM 應用對話歷史採集行為，以滿足不同的採集需求。

前提條件

已安裝 Python 探針或 Java 探針。

架構版本與探針版本要求如下：

Python 應用

組件/架構名	組件版本支援範圍	支援情境	探針版本要求
OpenAI Python SDK	1.X	ChatCompletion Completion Embedding	2.0.0 及以上版本

Java 應用

組件/架構名	組件版本支援範圍	支援情境	探針版本要求
OpenAI Java SDK	1.1.0+	ChatCompletion Completion Embedding	4.6.0 及以上版本
Spring AI	1.0.0+	OpenAI ChatModel ChatClient (Default) ToolManager (Default)	4.6.0 及以上版本
Spring AI Alibaba	1.0.0.3+	DashScope ChatModel	4.6.0 及以上版本

樣本

本文以一次包含 function 的 React Agent 調用過程為例，LLM 應用會攜帶工具定義調用大模型，模型會返回一次 tool_call 要求。在應用側完成工具調用後，應用會攜帶工具調用結果再次調用大模型並產生最終結果。調用過程時序圖如下所示：

將對話歷史記錄到 Span Attributes 中

採集行為與資料格式

該模式為預設行為，探針會將輸入訊息、輸出訊息、系統指令、工具定義等以 JSON 格式記錄在 Span 的 Attributes 中。

Attributes 名稱	含義	Schema	內容完整性
`gen_ai.input.messages`	輸入訊息	gen_ai.input.messages	完整記錄
`gen_ai.output.messages`	輸出訊息	gen_ai.output.messages	完整記錄
`gen_ai.system_instructions`	系統指令	gen_ai.system_instructions	完整記錄
`gen_ai.tool.definitions`	工具定義	-	type name description

配置方式

通過以下環境變數配置：
環境變數名
值
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
True
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY
"span-attributes"

對於 Java 應用，您也可以通過在啟動命令中添加 System Properties 的方式配置，如：

-Dotel.instrumentation.genai.capture-message-content=true \
-Dotel.instrumentation.genai.message-content.capture-strategy=span-attributes

樣本

GenAI Client Span 1

屬性	值
Span 名稱	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.operation.name`	`"chat"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`17`
`gen_ai.usage.input_tokens`	`47`
`gen_ai.response.finish_reasons`	`["tool_calls"]`
`gen_ai.input.messages`	`[ { "role": "user", "parts": [ { "type": "text", "content": "Weather in Paris?" } ] } ]`
`gen_ai.output.messages`	`[ { "role": "assistant", "parts": [ { "type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name": "get_weather", "arguments": { "location": "Paris" } } ], "finish_reason": "tool_call" } ]`
`gen_ai.tool.definitions`	`[ { "type": "function", "name": "get_weather", "description": "Get the current temperature for a specific location." } ]`

GenAI Client Span 2

屬性	值
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`52`
`gen_ai.usage.input_tokens`	`97`
`gen_ai.response.finish_reasons`	`["stop"]`
`gen_ai.input.messages`	`[ { "role": "user", "parts": [ { "type": "text", "content": "Weather in Paris?" } ] }, { "role": "assistant", "parts": [ { "type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name": "get_weather", "arguments": { "location": "Paris" } } ] }, { "role": "tool", "parts": [ { "type": "tool_call_response", "id": " call_VSPygqKTWdrhaFErNvMV18Yl", "response": "rainy, 57°F" } ] } ]`
`gen_ai.output.messages`	`[ { "role": "assistant", "parts": [ { "type": "text", "content": "The weather in Paris is currently rainy with a temperature of 57°F." } ], "finish_reason": "stop" } ]`

停止採集對話歷史

採集行為與資料格式

在該模式下，探針不會記錄輸入訊息、輸出訊息、系統指令等詳細內容，工具定義僅會以 JSON 格式記錄基本資料。

Attributes 名稱	含義	Schema	內容完整性
`gen_ai.input.messages`	輸入訊息	gen_ai.input.messages	不會記錄
`gen_ai.output.messages`	輸出訊息	gen_ai.output.messages	不會記錄
`gen_ai.system_instructions`	系統指令	gen_ai.system_instructions	不會記錄
`gen_ai.tool.definitions`	工具定義	-	type name

配置方式

通過以下環境變數配置：
環境變數名
值
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
False
對於 Java 應用，您也可以通過在啟動命令中添加 System Properties 的方式配置，如：
```
-Dotel.instrumentation.genai.capture-message-content=false
```

樣本

GenAI Client Span 1

屬性	值
Span 名稱	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.operation.name`	`"chat"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`17`
`gen_ai.usage.input_tokens`	`47`
`gen_ai.response.finish_reasons`	`["tool_calls"]`
`gen_ai.tool.definitions`	`[ { "type": "function", "name": "get_weather" } ]`

GenAI Client Span 2

屬性	值
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`52`
`gen_ai.usage.input_tokens`	`97`
`gen_ai.response.finish_reasons`	`["stop"]`

將對話歷史記錄到本地日誌中

採集行為與資料格式

在該模式下，Span 的 Attributes 中僅會保留基本資料，探針會將輸入訊息、輸出訊息、系統指令、工具定義等以 JSON 格式記錄在單行日誌中，並儲存在本地記錄檔下。

Attributes 名稱	含義	Schema	內容完整性
`gen_ai.input.messages`	輸入訊息	gen_ai.input.messages	完整記錄
`gen_ai.output.messages`	輸出訊息	gen_ai.output.messages	完整記錄
`gen_ai.system_instructions`	系統指令	gen_ai.system_instructions	完整記錄
`gen_ai.tool.definitions`	工具定義	-	type name description

預設情況下，探針啟動時會按照如下優先順序進行嘗試，找到第一個可用的目錄作為日誌地址。

如果已通過 APSARA_APM_AGENT_WORKSPACE_DIR 環境變數指定目錄，日誌會記錄在指定目錄的 .apsara-apm/{language}/logs 目錄下。
探針日誌目錄：/home/admin/.opt/.apsara-apm/{language}/logs
home目錄：~/.apsara-apm/{language}/{agent_version}_{agent_commit_id}/logs

應用啟動時，探針會在 stdout 中列印一行提示日誌，您可以通過該目錄找到日誌的儲存目錄。為了方便目錄統一管理，建議您通過 APSARA_APM_AGENT_WORKSPACE_DIR 環境變數指定目錄。

對話歷史記錄檔名以genai_messages_{ip}_{pid}.log的格式命名，記錄檔最大為 256 MB，超出該大小會進行檔案輪轉。檔案系統中僅會保留最近的兩個記錄檔，過舊的檔案會被刪除。

配置方式

通過以下環境變數配置：
環境變數名
值
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
True
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY
"event"

對於 Java 應用，您也可以通過在啟動命令中添加 System Properties 的方式配置，如：

-Dotel.instrumentation.genai.capture-message-content=true \
-Dotel.instrumentation.genai.message-content.capture-strategy=event

樣本

GenAI Client Span 1

屬性	值
Span 名稱	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.operation.name`	`"chat"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`17`
`gen_ai.usage.input_tokens`	`47`
`gen_ai.response.finish_reasons`	`["tool_calls"]`

GenAI Client Event 1

spanId 對應 GenAI Client Span 1。

{
  "scope": {
    "name": "aliyun.instrumentation.openai",
    "version": "1.0.1"
  },
  "timeUnixNano": 1760080084146812928,
  "severity": "UNSPECIFIED",
  "attributes": {
    "event.name": "gen_ai.client.inference.operation.details",
    "gen_ai.provider.name": "openai",
    "gen_ai.operation.name": "chat",
    "gen_ai.request.model": "gpt-4",
    "gen_ai.request.max_tokens": 200,
    "gen_ai.request.top_p": 1.0,
    "gen_ai.response.id": "chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l",
    "gen_ai.response.model": "gpt-4-0613",
    "gen_ai.usage.output_tokens": 17,
    "gen_ai.usage.input_tokens": 47,
    "gen_ai.response.finish_reasons": ["tool_calls"],
    "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Weather in Paris?\"}]}]",
    "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"tool_call\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"name\":\"get_weather\",\"arguments\":{\"location\":\"Paris\"}}],\"finish_reason\":\"tool_call\"}]",
    "gen_ai.tool.definitions": "[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get the current temperature for a specific location.\"}]"
  },
  "traceId": "0b46a347592ac487ed092ebe802c6818",
  "spanId": "b3c40af8cd1a522c"
}

GenAI Client Span 2

屬性	值
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`52`
`gen_ai.usage.input_tokens`	`97`
`gen_ai.response.finish_reasons`	`["stop"]`

GenAI Client Event 2

Span id 對應 GenAI Client Span 2。

{
  "scope": {
    "name": "aliyun.instrumentation.openai",
    "version": "1.0.1"
  },
  "timeUnixNano": 1760080084176812928,
  "severity": "UNSPECIFIED",
  "attributes": {
    "event.name": "gen_ai.client.inference.operation.details",
    "gen_ai.provider.name": "openai",
    "gen_ai.operation.name": "chat",
    "gen_ai.request.model": "gpt-4",
    "gen_ai.request.max_tokens": 200,
    "gen_ai.request.top_p": 1.0,
    "gen_ai.response.id": "chatcmpl-VSPygqKTWdrhaFErNvMV18Yl",
    "gen_ai.response.model": "gpt-4-0613",
    "gen_ai.usage.output_tokens": 52,
    "gen_ai.usage.input_tokens": 97,
    "gen_ai.response.finish_reasons": ["stop"],
    "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Weather in Paris?\"}]},{\"role\":\"assistant\",\"parts\":[{\"type\":\"tool_call\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"name\":\"get_weather\",\"arguments\":{\"location\": \"Paris\"}}]},{\"role\":\"tool\",\"parts\":[{\"type\":\"tool_call_response\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"response\":\"rainy, 57°F\"}]}]",
    "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"text\",\"content\":\"The weather in Paris is currently rainy with a temperature of 57°F.\"}],\"finish_reason\":\"sto\"}]"
  },
  "traceId": "0b46a347592ac487ed092ebe802c6818",
  "spanId": "0a706a178bd746c5"
}

將對話歷史記錄到 SLS 中

在將交談記錄到本地日誌模式下，您可以使用 LoongCollector 進一步將本地日誌採集到 SLS 中，以便進一步實現日誌的處理和消費。

步驟1：安裝 LoongCollector

如您的環境已經安裝過 LoongCollector，則可以跳過該步驟。

環境類型	參考文檔
Linux	LoongCollector安裝（Linux）
Windows	LoongCollector安裝（Linux）
Kubernetes	LoongCollector安裝（Kubernetes）

步驟2：建立採集配置

登入Log Service控制台，單擊目標Project，展開需要儲存日誌的日誌庫（Logstore），然後單擊資料接入右側的表徵圖，單擊JSON - 文本日誌地區的立即接入。
選擇已有的機器組或為日誌所在機器建立機器組。
建立採集配置，請將輸入配置下的檔案路徑替換為實際的日誌目錄，您可以查看應用啟動時列印的標準輸出來確認具體目錄位址，處理配置可以選擇常規的 JSON 解析。
建議至少為日誌添加以下索引，以便檢索和分析資料。

說明

更詳細的日誌採集操作請參見主機文本日誌採集。

步驟3：在 SLS 中查看採集的日誌

初次配置完成後，日誌會在幾分鐘內被採集到 SLS 中：

調整訊息長度限制

為防止過長的訊息長度引起用量過度增加，預設情況下探針會對超長的訊息內容進行截斷處理，當前預設的長度為每條訊息 8192 字元。被截斷的訊息末尾中會存在...[truncated]的標識符，如：

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris...[truncated]"
      }
    ],
    "finish_reason": "stop"
  }
]

配置方式

通過以下環境變數配置：
環境變數名
值
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH
8192
對於 Java 應用，您也可以通過在啟動命令中添加 System Properties 的方式配置，如：
```
-Dotel.instrumentation.genai.message-content.max-length=8192
```

會被截斷的訊息體

對話歷史類型	訊息
`gen_ai.input.messages`	TextPart.content
`gen_ai.output.messages`	TextPart.content
`gen_ai.system_instructions`	TextPart.content

環境變數名	值
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	`True`
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY	`"span-attributes"`

環境變數名	值
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	`False`

環境變數名	值
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH	8192