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

採集行為與資料格式

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

配置方式

• 通過以下環境變數配置：

  環境變數名	值
  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

樣本

[
  {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "content": "Weather in Paris?"
      }
    ]
  }
]

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "tool_call",
        "id": "call_VSPygqKTWdrhaFErNvMV18Yl",
        "name": "get_weather",
        "arguments": {
          "location": "Paris"
        }
      }
    ],
    "finish_reason": "tool_call"
  }
]

[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current temperature for a specific location."
  }
]

[
  {
    "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"
      }
    ]
  }
]

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris is currently rainy with a temperature of 57°F."
      }
    ],
    "finish_reason": "stop"
  }
]

採集行為與資料格式

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

配置方式

• 通過以下環境變數配置：

  環境變數名	值
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	False

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

  -Dotel.instrumentation.genai.capture-message-content=false

樣本

[
  {
    "type": "function",
    "name": "get_weather"
  }
]

採集行為與資料格式

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

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

1. 如果已通過 APSARA_APM_AGENT_WORKSPACE_DIR 環境變數指定目錄，日誌會記錄在指定目錄的 .apsara-apm/{language}/logs 目錄下。

2. 探針日誌目錄：/home/admin/.opt/.apsara-apm/{language}/logs

3. home目錄：~/.apsara-apm/{language}/{agent_version}_{agent_commit_id}/logs

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

Picked up [/Uxxxs/tools/log/.apsara-apm/python] as Agent Workspace.

對話歷史記錄檔名以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

樣本

{
  "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"
}

{
  "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"
}

步驟1：安裝 LoongCollector

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

步驟2：建立採集配置

1. 登入Log Service控制台，單擊目標Project，展開需要儲存日誌的日誌庫（Logstore），然後單擊資料接入右側的表徵圖，單擊JSON - 文本日誌地區的立即接入。

2. 選擇已有的機器組或為日誌所在機器建立機器組。

   在使用情境中選擇主機情境，安裝環境選擇ECS，在應用機器組列表中確認已添加目標機器組（例如 genai）。

3. 建立採集配置，請將輸入配置下的檔案路徑替換為實際的日誌目錄，您可以查看應用啟動時列印的標準輸出來確認具體目錄位址，處理配置可以選擇常規的 JSON 解析。

   例如，配置名稱設定為 playground-test-config，輸入類型選擇文本日誌採集，檔案路徑參考格式為 /home/admin/logs/.apsara-apm/java/**/logs/genai_messages_*.log，最大目錄監控深度設為 1。

   xxx
   Picked up /home/admin/logs/.apsara-apm/java/4.6.0_4e280e61/ as Agent Workspace.
   Unable to locate the -XX:ErrorFile parameter in the JVM options.
   If you are using Kubernetes, we recommend updating ack-onepilot to version 3.2.3 or later.
   For other environments, please consider adding the following parameters manually:
   -XX:ErrorFile=/{JavaAgentDirectory}/hs_err_pid%p.log
   -XX:OnError=/{JavaAgentDirectory}/crash_log_collector.sh
   These settings will enable automatic crash log collection to ARMS, helping us monitor
    incidents and provide timely feedback.
   Please note that this reminder does not affect the functionality of ARMS.
   If you prefer not to make these changes, feel free to disregard this message.
   Apsara Java Agent start cost: 5071 ms

4. 建議至少為日誌添加以下索引，以便檢索和分析資料。
   建立索引配置：開啟全文索引，關閉大小寫敏感和包含中文。在指定欄位查詢中添加以下欄位索引：attributes（json 類型，開啟大小寫敏感和包含中文）、resource（json 類型，開啟大小寫敏感和包含中文）、spanId（text 類型，關閉大小寫敏感和包含中文）、traceId（text 類型，關閉大小寫敏感和包含中文）。
   
   
   
   

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

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

▼ attributes: {}
    event.name: "gen_ai.client.inference.operation.details"
    gen_ai.input.messages: "[{"role":"system","parts":[{"type":"text","content":"\t
xxx
xxx
xxx
:
xxx
                              xxx"}]},{"role":"user","parts":[{"type":"text","content":"xxx"}]}]"
    gen_ai.operation.name: "invoke_agent"
    gen_ai.output.messages: "[{"role":"assistant","parts":[{"type":"text","content":"
xxx
                                    "}],"finishReason":"stop"}]"
    gen_ai.provider.name: "spring-ai"
    gen_ai.request.model: "qwen-max"
    gen_ai.request.temperature: 0.8
  ► gen_ai.response.finish_reasons: []
    gen_ai.response.id: "0d98f.xxx"
    gen_ai.tool.definitions: "[{"type":"function","name":"getBookingDetails"},{"type":"function","name":"cancelBooking"},{"type":"function","name":"changeBooking"}]"
    gen_ai.usage.input_tokens: 1300
    gen_ai.usage.output_tokens: 59
body:
▼ resource: {}
  ► attributes: {}

配置方式

• 通過以下環境變數配置：

  環境變數名	值
  OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH	8192

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

  -Dotel.instrumentation.genai.message-content.max-length=8192

會被截斷的訊息體