应用实时监控服务ARMS：控制 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. 登录日志服务控制台，单击目标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

会被截断的消息体