日志服务 Agent 可观测 Trace 规范字段定义说明

注意：说明：

注意：本语义规范在 OpenTelemetry GenAI 语义规范的基础上进行扩展，OpenTelemetry GenAI 语义规范仍在修改和完善中，后续维护过程中可能发生调整。

一、如何使用这篇档

不同接入方式对这篇档的使用方式不同，请参见下表。各接入方式的详细说明请参见 选择接入方式。

二、数据模型

AgentObs Trace 数据写入 AgentObs 应用关联的 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 字段。

如需了解产品整体能力，请访问 AgentObs 产品页，或参见 选择接入方式。

在 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 的框架时出现。

四、Trace 顶层字段

五、Resource 字段

六、公共身份与上下文字段

七、LLM Chat 字段

八、Token 使用量字段

九、成本字段

以下成本字段由采集端根据 Token 用量及适用的模型单价计算。无法确定模型单价或未启用成本计算时，不采集对应字段。

十、Agent 字段

十一、Tool 字段

以下字段主要出现在 gen_ai.span.kind=tool、gen_ai.operation.name=execute_tool 的 Span 中。

注意：说明：

注意：gen_ai.tool.call.arguments 和 gen_ai.tool.call.result 可能以 JSON 对象或 JSON 字符串形式出现，使用时请兼容两种形式。

十二、ReAct Step 字段

十三、Chain 字段

以下字段主要出现在 gen_ai.span.kind=chain、gen_ai.operation.name=chain 的 Span 中。

十四、Retriever 字段

以下字段主要出现在 gen_ai.span.kind=retriever、gen_ai.operation.name=retrieval 的 Span 中。

十五、Rerank 字段

以下字段主要出现在 gen_ai.span.kind=rerank、gen_ai.operation.name=rerank_documents 的 Span 中。

注意：内容采集说明：

注意：Chain 的输入和输出、Retriever 的文档内容以及 Rerank 的输入和输出文档可能包含用户数据，默认不采集。仅在业务确认数据合规并显式开启内容采集后上报。

十六、Agent 扩展与代码上下文字段

十七、通用 Agent 扩展字段

十八、宿主 Agent 扩展字段

十九、补充代码上下文字段

20、自定义扩展字段

用户可通过 agent.custom.* 命名空间上报业务自定义属性，例如 agent.custom.project_id、agent.custom.tenant_id 和 agent.custom.biz_scene。自定义字段不得覆盖这篇档定义的标准字段，且不应上报密码、密钥、Token 或个人敏感信息。

21、其他 GenAI 扩展字段

22、Langfuse 兼容字段

通过 Langfuse 接入 Agent Trace 数据时，AgentObs 按以下规则映射标签和元数据字段：

23、兼容性说明

这篇档定义的是 AgentObs Trace 的统一语义。不同 Agent、模型和 Span 类型可能只适用其中一部分字段，具体适用范围请以对应字段章节的说明为准。由于 OpenTelemetry GenAI 语义规范仍在演进，后续字段定义和语义可能随规范版本调整，并在版本说明中同步更新。