日志服务 AgentObs Trace 规范字段定义说明

本文档定义 Agent 可观测中 Trace 数据的字段规范，包括每个字段的含义、数据类型和取值示例。Agent 可观测控制台中的会话分析、调用链、Token 用量与成本统计等功能，均基于这些字段计算和展示。
说明：
本语义规范在 OpenTelemetry GenAI 语义规范的基础上进行扩展，OpenTelemetry GenAI 语义规范仍在修改和完善中，后续维护过程中可能发生调整。
如何使用本文档
不同接入方式对本文档的使用方式不同，请参见下表。各接入方式的详细说明请参见 选择接入方式。
接入方式
使用方式
通过 Onesuite-Pilot 采集器、官方 SDK 与插件等 AgentObs 官方方式接入
数据会自动按本文档规范上报。您可以根据此规范查阅字段含义，用于日志检索分析、自定义仪表盘等。
通过 Langfuse SDK 上报
Langfuse SDK 保留自身的字段语义，具体字段含义请参见 Langfuse SDK Trace 字段说明。
自行埋点，或通过 OpenTelemetry SDK 等第三方方式接入
请按本文档的字段名和数据类型上报。字段名或类型不一致时，AgentObs 可能无法正确识别数据内容。
数据模型
AgentObs Trace 数据写入 Agent 可观测应用关联的 Trace 日志主题，每条日志对应一个 Span，由以下三部分组成：
Trace 顶层字段：所有 Span 共有的链路信息，例如 traceID、spanID、耗时和状态。
Resource 字段：产生数据的服务和运行环境信息，例如服务名称和主机名。
Attribute 字段：业务语义字段，具体包含哪些字段由 Span 类型（gen_ai.span.kind）决定。
查阅字段时，请先确认 Span 类型，再参见对应章节：
所有 Span：公共身份与上下文字段。
chat：LLM Chat 字段、Token 使用量字段和成本字段。
agent：Agent 字段。
tool：Tool 字段。
step：ReAct Step 字段。
chain、retriever、rerank：Chain 字段、Retriever 字段和 Rerank 字段。
如需了解产品整体能力，请访问 Agent 可观测产品页，或参见 选择接入方式。
在 Trace 日志主题的原始记录中，attribute 和 resource 以 JSON 编码字符串存储，以下示例为 attribute 和 resource 解析后的 Agent Trace 结构。
{
  "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。其中 chain、retriever、rerank 为可选类型，仅在接入支持编排管道或 RAG 的框架时出现。
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
工具调用。
chain
chain
LangChain 或 LangGraph 编排管道节点，OpenTelemetry Span Kind 为 INTERNAL，常见父级为 agent、step、chain。
retriever
retrieval
文档检索操作，OpenTelemetry Span Kind 为 INTERNAL，常见父级为 step、chain。
rerank
rerank_documents
文档重排序操作，OpenTelemetry Span Kind 为 INTERNAL，常见父级为 step、chain、retriever。
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
service.version
string
产生 Trace 数据的应用或 Agent 版本。
1.0.7
service.instance.id
string
产生 Trace 数据的服务实例标识。
codebuddy@VM-51:12345
host.ip
string
产生 Trace 数据的主机 IP 地址。
10.0.51.187
process.pid
integer
产生 Trace 数据的进程 ID。
4030910
process.runtime.name
string
进程运行时名称。
python
process.runtime.version
string
进程运行时版本。
3.11.0
telemetry.sdk.name
string
OpenTelemetry SDK 名称。
tencentcloud-cls-sdk-langchain
telemetry.sdk.language
string
OpenTelemetry SDK 使用的语言。
python
telemetry.sdk.version
string
OpenTelemetry SDK 版本。
1.0.5
cloud.provider
string
云服务提供商。
tencent_cloud
cloud.region
string
云资源所在地域。
ap-guangzhou
os.type
string
操作系统类型。
linux
os.version
string
操作系统版本。
5.15.0
公共身份与上下文字段
字段名
类型
说明
示例
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>
gen_ai.agent.name
string
Agent 名称。
main
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
gen_ai.user.id
string
AI Coding 数据所属用户的标识。
122855467
gen_ai.user.name
string
AI Coding 数据所属用户的展示名称。
user-name
gen_ai.entry.type
string
AI 应用入口类型。
CLI
gen_ai.system
string
GenAI 系统或模型服务类型。
anthropic、openai、deepseek
gen_ai.agent.scope
string
Agent 的执行范围；子 Agent 取值为 subagent。
subagent
gen_ai.subagent.parent_tool_call.id
string
触发子 Agent 的父工具调用 ID。
call_abc123
gen_ai.entry.platform
string
AI 应用入口所在平台。
terminal、vscode、jetbrains
gen_ai.entry.channel_id
string
IDE 实例或接入频道标识。
channel_01
LLM Chat 字段
字段名
类型
说明
示例
gen_ai.provider.name
string
模型服务提供商名称。
anthropic
gen_ai.request.model
string
请求时指定的模型名称。
claude-opus-5
gen_ai.response.model
string
实际返回结果所使用的模型名称。
claude-opus-5
gen_ai.response.finish_reasons
string[]
模型生成结束原因。
["stop"]
gen_ai.chat.duration_ms
integer
Chat 操作自身的耗时，单位为毫秒。
16010
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":[...]}]
gen_ai.response.id
string
模型服务返回的响应 ID。
msg_01HXYZ
gen_ai.response.time_to_first_token_ms
integer
从发起请求到收到首个 Token 的耗时，单位为毫秒。
820
gen_ai.request.temperature
number
控制模型输出随机性的 Temperature 参数。
0.7
gen_ai.request.top_p
number
控制核采样范围的 Top-P 参数。
0.9
gen_ai.request.max_tokens
integer
模型允许生成的最大 Token 数。
4096
gen_ai.request.frequency_penalty
number
频率惩罚参数。
0
gen_ai.request.presence_penalty
number
存在惩罚参数。
0
gen_ai.request.stop_sequences
string[]
用于停止生成的字符串数组。
["END"]
gen_ai.request.seed
integer
控制随机生成结果的种子。
42
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
成本字段
以下成本字段由采集端根据 Token 用量及适用的模型单价计算。无法确定模型单价或未启用成本计算时，不采集对应字段。
字段名
类型
说明
示例
gen_ai.usage.input_cost
number
输入 Token 成本。
0.0025
gen_ai.usage.output_cost
number
输出 Token 成本。
0.012
gen_ai.usage.cache_read.input_cost
number
缓存命中输入 Token 成本。
0.0003
gen_ai.usage.cache_creation.input_cost
number
缓存写入输入 Token 成本。
0.0008
gen_ai.usage.total_cost
number
本次模型调用的总成本。
0.0156
Agent 字段
字段名
类型
说明
示例
gen_ai.agent.message_count
integer
Agent Span 内包含的消息数量。
13
gen_ai.agent.tool_call_count
integer
Agent Span 内发起的工具调用次数。
10
gen_ai.agent.name
string
Agent 名称。
main
gen_ai.agent.id
string
与当前模型或工具调用关联的 Agent 标识。
<agent-id>
Tool 字段
以下字段主要出现在 gen_ai.span.kind=tool、gen_ai.operation.name=execute_tool 的 Span 中。
字段名
类型
说明
示例
gen_ai.tool.call.id
string
一次工具调用的唯一标识。
call_<id>
gen_ai.tool.name
string
被调用的工具名称。
Bash、execute_command
gen_ai.tool.type
string
工具类型。
function
gen_ai.tool.call.arguments
JSON object / string
工具调用的输入参数。
{"command":"<masked>"}
gen_ai.tool.call.result
JSON object / string
工具调用的返回结果。
{"status":"success"}
gen_ai.tool.call.duration_ms
integer
工具调用耗时，单位为毫秒。
44
gen_ai.tool.error.type
string
工具调用失败时的错误类型。
tool_error
error.type
string
当前 Span 或操作的错误类型。
tool_error
gen_ai.tool.call.exec.id
string
工具执行 ID，用于区分同一调用的多次执行。
exec_01HXYZ123456
gen_ai.tool.call.image.count
integer
图片生成工具产生的图片数量。
1
gen_ai.tool.call.image.paths
string[]
图片生成工具产生的图片路径数组。
["/tmp/generated-image.png"]
gen_ai.tool.call.image.duration
number
图片生成耗时，单位为毫秒。
1250
gen_ai.tool.error.message
string
工具调用失败时的错误信息。
Tool execution failed: command timed out
exception.message
string
当前 Span 对应的异常信息。
Connection timeout after 30s
说明：
gen_ai.tool.call.arguments 和 gen_ai.tool.call.result 可能以 JSON 对象或 JSON 字符串形式出现，使用时请兼容两种形式。
ReAct Step 字段
字段名
类型
说明
示例
gen_ai.react.round
integer
ReAct 迭代轮次，通常从 1 开始递增。
8
gen_ai.react.finish_reason
string
ReAct 或模型调用的结束原因。
tool_calls、stop
gen_ai.step.id
string
当前推理与行动步骤的唯一标识。
<session-id>:t73:s4
gen_ai.react.thought
string
当前 ReAct 轮次的思考文本。
用户想查询订单状态，我应先调用订单查询工具。
gen_ai.react.observation
string
当前 ReAct 轮次的观察结果。
订单查询工具返回：订单 12345 状态为已发货。
Chain 字段
以下字段主要出现在 gen_ai.span.kind=chain、gen_ai.operation.name=chain 的 Span 中。
字段名
类型
说明
示例
gen_ai.chain.name
string
Runnable 或 Chain 名称。
RunnableSequence
gen_ai.chain.input
JSON object / string
编排节点的输入数据。
{"question":"今天天气如何？"}
gen_ai.chain.output
JSON object / string
编排节点的输出数据。
{"answer":"今天晴，25℃。"}
gen_ai.chain.metadata
JSON object
用户自定义的编排元数据。
{"ls_provider":"openai","ls_model_name":"gpt-4o"}
Retriever 字段
以下字段主要出现在 gen_ai.span.kind=retriever、gen_ai.operation.name=retrieval 的 Span 中。
字段名
类型
说明
示例
gen_ai.retrieval.query_text
string
文档检索使用的查询文本。
如何配置 CLS 日志采集？
gen_ai.retrieval.documents.count
integer
检索返回的文档数量。
5
gen_ai.retrieval.documents
JSON array
检索返回的文档列表，可包含内容、相关性分数和元数据。
[{"content":"CLS 采集配置...","score":0.92}]
gen_ai.retrieval.duration_ms
number
文档检索耗时，单位为毫秒。
128.5
Rerank 字段
以下字段主要出现在 gen_ai.span.kind=rerank、gen_ai.operation.name=rerank_documents 的 Span 中。
字段名
类型
说明
示例
gen_ai.rerank.query_text
string
文档重排使用的查询文本。
如何配置 CLS 日志采集？
gen_ai.rerank.input_documents.count
integer
参与重排的输入文档数量。
20
gen_ai.rerank.output_documents.count
integer
重排后输出的文档数量。
5
gen_ai.request.top_k
integer
请求返回的前 K 个文档数量。
5
gen_ai.rerank.input_documents
JSON array
参与重排的输入文档列表。
[{"content":"文档 A","index":0}]
gen_ai.rerank.output_documents
JSON array
重排后的文档列表，可包含相关性分数和原始索引。
[{"content":"文档 A","score":0.95,"original_index":3}]
gen_ai.rerank.duration_ms
number
文档重排耗时，单位为毫秒。
45.2
内容采集说明：
Chain 的输入和输出、Retriever 的文档内容以及 Rerank 的输入和输出文档可能包含用户数据，默认不采集。仅在业务确认数据合规并显式开启内容采集后上报。
Agent 扩展与代码上下文字段
字段名
类型
说明
示例
agent.codebuddy.cwd
string
CodeBuddy 会话的当前工作目录。
/workspace/project
agent.workbuddy.cwd
string
WorkBuddy 会话的当前工作目录。
/workspace/project
git.domain
string
当前代码仓库所在 Git 服务域名。
git.example.com
git.repo
string
当前代码仓库标识。
team/project
git.branch
string
当前代码分支。
main
observed_time_unix_nano
string
数据被观测或处理的时间，单位为纳秒。
1787197097104000000
通用 Agent 扩展字段
字段名
类型
说明
示例
agent.file_path
string
当前操作的文件路径。
src/main.py
agent.action_type
string
当前执行的操作类型。
edit_file
agent.content
string
当前操作对应的内容。
def hello(): print("hi")
agent.inline_diff_message
string
行内代码差异信息。
新增 3 行，删除 1 行
agent.request_id
string
Agent 内部请求 ID，可用于关联 Token 或调用记录。
req-8f3a2c1d
宿主 Agent 扩展字段
字段名
类型
说明
示例
适用 Agent
agent.codex.transcript_turn_id
string
Codex 会话轮次 ID。
turn-abc123
Codex
agent.codex.turn_status
string
Codex 轮次状态，例如 completed、aborted。
completed
Codex
agent.codex.cwd
string
Codex 当前工作目录。
/home/user/project
Codex
agent.cursor.cursor_version
string
Cursor 版本。
0.42.3
Cursor
agent.qoder.version
string
Qoder CLI 版本。
1.2.0
Qoder CLI
agent.qoderwork.version
string
Qoder Work 版本。
1.5.2
Qoder Work
agent.qoderwork.cwd
string
Qoder Work 当前工作目录。
/workspace/demo
Qoder Work
补充代码上下文字段
字段名
类型
说明
示例
git.repo_root
string
Git 仓库的本地根目录。
/home/user/my-repo
workspace.current_root
string
当前工作区根目录。
/home/user/my-repo
自定义扩展字段
用户可通过 agent.custom.* 命名空间上报业务自定义属性，例如 agent.custom.project_id、agent.custom.tenant_id 和 agent.custom.biz_scene。自定义字段不得覆盖本文档定义的标准字段，且不应上报密码、密钥、Token 或个人敏感信息。
其他 GenAI 扩展字段
字段名
类型
说明
示例
gen_ai.request.id
string
宿主 Agent 内部的模型请求 ID。
chatcmpl-9xY2abc
gen_ai.skill.name
string
当前调用的 Skill 名称。
cls-doc-full
gen_ai.system_instructions
string
系统指令内容或摘要。
你是一个专业的编程助手，请遵循...
gen_ai.tool.definitions
JSON array
当前模型调用可使用的工具定义列表。
[{"name":"read_file","description":"读取文件"}]
Langfuse 兼容字段
通过 Langfuse 接入 Agent Trace 数据时，Agent 可观测按以下规则映射标签和元数据字段：
Langfuse 字段
Agent Trace Attribute 字段
langfuse.metadata.*
metadata.*
tags
trace.tags
兼容性说明
本文档定义的是 Agent 可观测 Trace 的统一语义。不同 Agent、模型和 Span 类型可能只适用其中一部分字段，具体适用范围请以对应字段章节的说明为准。由于 OpenTelemetry GenAI 语义规范仍在演进，后续字段定义和语义可能随规范版本调整，并在版本说明中同步更新。

接入方式	使用方式
通过 Onesuite-Pilot 采集器、官方 SDK 与插件等 AgentObs 官方方式接入	数据会自动按本文档规范上报。您可以根据此规范查阅字段含义，用于日志检索分析、自定义仪表盘等。
通过 Langfuse SDK 上报	Langfuse SDK 保留自身的字段语义，具体字段含义请参见 Langfuse SDK Trace 字段说明。
自行埋点，或通过 OpenTelemetry SDK 等第三方方式接入	请按本文档的字段名和数据类型上报。字段名或类型不一致时，AgentObs 可能无法正确识别数据内容。

`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	工具调用。
chain	chain	LangChain 或 LangGraph 编排管道节点，OpenTelemetry Span Kind 为 INTERNAL，常见父级为 agent、step、chain。
retriever	retrieval	文档检索操作，OpenTelemetry Span Kind 为 INTERNAL，常见父级为 step、chain。
rerank	rerank_documents	文档重排序操作，OpenTelemetry Span Kind 为 INTERNAL，常见父级为 step、chain、retriever。

字段名	类型	说明	示例
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 关联的日志或事件信息。	[]

Langfuse 字段	Agent Trace Attribute 字段
langfuse.metadata.*	metadata.*
tags	trace.tags

AgentObs Trace 规范字段定义说明

本页目录：

如何使用本文档

数据模型

Span 类型与操作类型

Trace 顶层字段

Resource 字段

公共身份与上下文字段

LLM Chat 字段

Token 使用量字段

成本字段

Agent 字段

Tool 字段

ReAct Step 字段

Chain 字段

Retriever 字段

Rerank 字段

Agent 扩展与代码上下文字段

通用 Agent 扩展字段

宿主 Agent 扩展字段

补充代码上下文字段

自定义扩展字段

其他 GenAI 扩展字段

Langfuse 兼容字段

兼容性说明