日志服务 Agent Trace 字段定义说明

本文档是面向 Agent 可观测场景的 Trace 统一语义规范，用于约定字段含义、数据类型、示例以及第三方接入时的字段要求；目前，OneSuite-Pilot 按照本规范上报 Agent Trace 数据。
说明：
本语义规范在 OpenTelemetry GenAI 语义规范的基础上进行扩展，OpenTelemetry GenAI 语义规范仍在修改和完善中，后续维护过程中可能发生调整。
数据模型
Onesuite-Pilot 将 AI Coding 活动转换为 OpenTelemetry Trace，并通过 CLS Trace Topic 上报。每条日志包含 Trace 顶层字段、Resource 字段和 Span Attributes 字段。
在 CLS 的 LogJson 中，attribute 和 resource 以 JSON 编码字符串存储，解析后分别为 JSON 对象。
{
  "traceID": "<32 位十六进制 Trace ID>",
  "spanID": "<16 位十六进制 Span ID>",
  "parentSpanID": "<父 Span ID>",
  "name": "chat <model>",
  "kind": "client",
  "start": "<Unix 纳秒时间戳>",
  "end": "<Unix 纳秒时间戳>",
  "duration": "<纳秒>",
  "statusCode": "OK",
  "resource": {
    "service.name": "codebuddy",
    "host.name": "<主机名>"
  },
  "attribute": {
    "gen_ai.span.kind": "chat",
    "gen_ai.operation.name": "chat",
    "gen_ai.agent.type": "codebuddy",
    "gen_ai.session.id": "<会话 ID>",
    "gen_ai.turn.id": "<轮次 ID>",
    "gen_ai.request.model": "<请求模型>",
    "gen_ai.usage.input_tokens": 1000,
    "gen_ai.usage.output_tokens": 200
  }
}
Span 类型与操作类型
gen_ai.span.kind
gen_ai.operation.name
说明
entry
enter_application
AI Coding 应用入口
agent
invoke_agent
Agent 调用
step
react
ReAct 推理与行动轮次
chat
chat
模型对话调用
tool
execute_tool
工具调用
Trace 顶层字段
字段名
类型
说明
示例
采集条件
traceID
string
Trace 的唯一标识，用于关联同一请求链路中的多个 Span。
17b5f957568ecb90b5b5b58d6bb56cbe
必须
spanID
string
当前 Span 的唯一标识。
66dbc3146404b6b2
必须
parentSpanID
string
当前 Span 的父 Span 标识；根 Span 通常为空。
4523b3266604f28c
必须
name
string
Span 名称，用于展示当前操作。
chat <model>
必须
kind
string
OpenTelemetry Span 类型。
client
必须
start
string
Span 开始时间，单位为纳秒。
1787150761999000000
必须
end
string
Span 结束时间，单位为纳秒。
1787150802462000000
必须
duration
string
Span 持续时间，单位为纳秒，通常为 end - start。
40463000000
必须
statusCode
string
Span 执行状态。
OK
必须
statusMessage
string
Span 状态的补充说明。
tool execution failed
产生状态说明时采集
attribute
JSON string
Span 业务属性集合，解析后为 JSON 对象。
{"gen_ai.span.kind":"chat"}
必须
resource
JSON string
Span 所属服务和运行环境属性集合，解析后为 JSON 对象。
{"service.name":"codebuddy"}
必须
traceState
string
W3C Trace Context 的扩展信息。
``
可选
links
JSON string
当前 Span 关联的其他 Trace 或 Span 链接。
[]
存在关联时采集
logs
JSON string
Span 关联的日志或事件信息。
[]
存在事件时采集
Resource 字段
字段名
类型
说明
示例
采集条件
service.name
string
产生 Trace 数据的应用或 Agent 服务名称。
codebuddy
必须
host.name
string
产生数据的主机名称。
VM-138-200-tencentos
必须
deployment.environment.name
string
应用运行环境名称。
production
配置了运行环境时采集
公共身份与上下文字段
字段名
类型
说明
示例
采集条件
gen_ai.span.kind
string
当前 Span 的业务类型。
chat
必须
gen_ai.operation.name
string
当前 Span 的具体操作名称。
chat、execute_tool
必须
gen_ai.agent.type
string
产生数据的 AI Coding Agent 类型。
codebuddy、workbuddy
必须
gen_ai.agent.id
string
与当前模型或工具调用关联的 Agent 标识。具体生成规则以实际版本为准。
<agent-id>
Chat、Tool Span 中按条件采集
gen_ai.agent.name
string
Agent 名称。
main
Agent Span 提供名称时采集
gen_ai.session.id
string
AI Coding 会话的唯一标识，用于关联同一会话中的多个 Span。
<session-id>
必须
gen_ai.turn.id
string
会话内某一轮用户请求或 Agent 处理轮次的标识。
<session-id>:t73
必须
gen_ai.step.id
string
ReAct 或 Agent 处理步骤的标识。
<session-id>:t73:s4
Step、Chat、Tool Span 中按条件采集
gen_ai.user.id
string
AI Coding 数据所属用户的标识。
122855467
必须
gen_ai.user.name
string
AI Coding 数据所属用户的展示名称。
user-name
必须
gen_ai.entry.type
string
AI 应用入口类型。
cli
Entry Span 时采集
LLM Chat 字段
字段名
类型
说明
示例
采集条件
gen_ai.provider.name
string
模型服务提供商名称。
anthropic
能获取时采集
gen_ai.request.model
string
请求时指定的模型名称。
claude-opus-5
Chat、Tool Span 中能获取时采集
gen_ai.response.model
string
实际返回结果所使用的模型名称。
claude-opus-5
能获取时采集
gen_ai.response.finish_reasons
string[]
模型生成结束原因。
["stop"]
Chat Span 中能获取时采集
gen_ai.chat.duration_ms
integer
Chat 操作自身的耗时，单位为毫秒。
16010
Chat Span 中能获取时采集
gen_ai.input.messages
JSON array
发给模型或 Agent 的输入消息列表。
[{"role":"user","parts":[...]}]
开启消息内容采集或产生消息数据时
gen_ai.input.messages.hash
string
输入消息内容的哈希值，用于关联或去重。
<32 位哈希>
产生哈希值时采集
gen_ai.input.messages_delta
JSON array
输入消息的增量变化信息。
[{"type":"append",...}]
产生增量信息时采集
gen_ai.output.messages
JSON array
模型或 Agent 返回的输出消息列表。
[{"role":"assistant","parts":[...]}]
产生输出消息时采集
Token 使用量字段
字段名
类型
说明
示例
采集条件
gen_ai.usage.input_tokens
integer
模型输入消耗的 Token 数。
1000
能获取时采集
gen_ai.usage.output_tokens
integer
模型输出消耗的 Token 数。
200
能获取时采集
gen_ai.usage.total_tokens
integer
输入和输出消耗的总 Token 数。
1200
能获取时采集
gen_ai.usage.cache_read.input_tokens
integer
从模型提供商缓存中读取的输入 Token 数。
500
能获取时采集
gen_ai.usage.cache_creation.input_tokens
integer
写入模型提供商缓存的输入 Token 数。
100
能获取时采集
gen_ai.usage.cache_miss.input_tokens
integer
未命中缓存的输入 Token 数。
50
能获取时采集
gen_ai.usage.reasoning_output_tokens
integer
推理过程产生的输出 Token 数。
0
能获取时采集
Agent 字段
字段名
类型
说明
示例
采集条件
gen_ai.agent.message_count
integer
Agent Span 内包含的消息数量。
13
Agent Span 中能获取时采集
gen_ai.agent.tool_call_count
integer
Agent Span 内发起的工具调用次数。
10
Agent Span 中能获取时采集
gen_ai.agent.name
string
Agent 名称。
main
Agent Span 提供名称时采集
gen_ai.agent.id
string
与当前模型或工具调用关联的 Agent 标识。
<agent-id>
Chat、Tool Span 中按条件采集
Tool 字段
以下字段主要出现在 gen_ai.span.kind=tool、gen_ai.operation.name=execute_tool 的 Span 中。
字段名
类型
说明
示例
采集条件
gen_ai.tool.call.id
string
一次工具调用的唯一标识。
call_<id>
Tool Span 时采集
gen_ai.tool.name
string
被调用的工具名称。
Bash、execute_command
Tool Span 时采集
gen_ai.tool.type
string
工具类型。
function
Tool Span 时采集
gen_ai.tool.call.arguments
JSON object / string
工具调用的输入参数。
{"command":"<masked>"}
Tool Span 中能获取时采集
gen_ai.tool.call.result
JSON object / string
工具调用的返回结果。
{"status":"success"}
Tool Span 中能获取时采集
gen_ai.tool.call.duration_ms
integer
工具调用耗时，单位为毫秒。
44
Tool Span 时采集
gen_ai.tool.error.type
string
工具调用失败时的错误类型。
tool_error
工具调用失败时采集
error.type
string
当前 Span 或操作的错误类型。
tool_error
发生错误时采集
说明：
gen_ai.tool.call.arguments 和 gen_ai.tool.call.result 可能以 JSON 对象或 JSON 字符串形式出现，使用时请兼容两种形式。
ReAct Step 字段
字段名
类型
说明
示例
采集条件
gen_ai.react.round
integer
ReAct 迭代轮次，通常从 1 开始递增。
8
相关 Span 中能获取时采集
gen_ai.react.finish_reason
string
ReAct 或模型调用的结束原因。
tool_calls、stop
能获取时采集
gen_ai.step.id
string
当前推理与行动步骤的唯一标识。
<session-id>:t73:s4
Step、Chat、Tool Span 中按条件采集
CodeBuddy、WorkBuddy 与代码上下文字段
字段名
类型
说明
示例
采集条件
agent.codebuddy.cwd
string
CodeBuddy 会话的当前工作目录。
/workspace/project
CodeBuddy 场景时采集
agent.workbuddy.cwd
string
WorkBuddy 会话的当前工作目录。
/workspace/project
WorkBuddy 场景时采集
git.domain
string
当前代码仓库所在 Git 服务域名。
git.example.com
能获取时采集
git.repo
string
当前代码仓库标识。
team/project
能获取时采集
git.branch
string
当前代码分支。
main
能获取时采集
observed_time_unix_nano
string
数据被观测或处理的时间，单位为纳秒。
1787197097104000000
实际产生该字段时采集
兼容性说明
本文档定义的是 Agent 可观测 Trace 的统一语义。不同 Agent、模型和 Span 类型可能只适用其中一部分字段，具体字段要求请以对应字段表中的采集条件为准。由于 OpenTelemetry GenAI 语义规范仍在演进，后续字段定义和语义可能随规范版本调整，并在版本说明中同步更新。
相关安装方法请参见 接入 AI Coding Agent 数据（Onesuite-Pilot）。

`gen_ai.span.kind`	`gen_ai.operation.name`	说明
entry	enter_application	AI Coding 应用入口
agent	invoke_agent	Agent 调用
step	react	ReAct 推理与行动轮次
chat	chat	模型对话调用
tool	execute_tool	工具调用

字段名	类型	说明	示例	采集条件
traceID	string	Trace 的唯一标识，用于关联同一请求链路中的多个 Span。	17b5f957568ecb90b5b5b58d6bb56cbe	必须
spanID	string	当前 Span 的唯一标识。	66dbc3146404b6b2	必须
parentSpanID	string	当前 Span 的父 Span 标识；根 Span 通常为空。	4523b3266604f28c	必须
name	string	Span 名称，用于展示当前操作。	chat <model>	必须
kind	string	OpenTelemetry Span 类型。	client	必须
start	string	Span 开始时间，单位为纳秒。	1787150761999000000	必须
end	string	Span 结束时间，单位为纳秒。	1787150802462000000	必须
duration	string	Span 持续时间，单位为纳秒，通常为 end - start。	40463000000	必须
statusCode	string	Span 执行状态。	OK	必须
statusMessage	string	Span 状态的补充说明。	tool execution failed	产生状态说明时采集
attribute	JSON string	Span 业务属性集合，解析后为 JSON 对象。	{"gen_ai.span.kind":"chat"}	必须
resource	JSON string	Span 所属服务和运行环境属性集合，解析后为 JSON 对象。	{"service.name":"codebuddy"}	必须
traceState	string	W3C Trace Context 的扩展信息。	``	可选
links	JSON string	当前 Span 关联的其他 Trace 或 Span 链接。	[]	存在关联时采集
logs	JSON string	Span 关联的日志或事件信息。	[]	存在事件时采集

Agent Trace 字段定义说明

本页目录：

数据模型

Span 类型与操作类型

Trace 顶层字段

Resource 字段

公共身份与上下文字段

LLM Chat 字段

Token 使用量字段

Agent 字段

Tool 字段

ReAct Step 字段

CodeBuddy、WorkBuddy 与代码上下文字段

兼容性说明