AI可观测调用链Span协议说明

一、Span 类型总览

通过 gen_ai.span.kind 字段区分 不同AI Agent语义类型，枚举值如下：

枚举值	含义
AGENT	智能体调用
LLM	大语言模型调用
CHAIN	调用链 / 流水线
EMBEDDING	向量嵌入
TOOL	工具调用
TASK	任务单元
RETRIEVER	检索器
RERANKER	重排序器
MCP_CLIENT	MCP 客户端调用
UNKNOWN	未知类型

---

二、通用属性

所有 Span 类型均应携带以下字段（来自 CommonAttributes + SpanAttributes）。

2.1 核心标识

字段 Key	类型	说明
gen_ai.span.kind	string	Span 类型，取值见上表
gen_ai.operation.name	string	操作类型，取值见 §三
gen_ai.framework	string	使用的 AI 框架名称
gen_ai.span.sub_kind	string	Span 子类型，用于进一步细分

2.2 会话与用户

字段 Key	类型	说明
gen_ai.conversation.id	string	对话/会话唯一 ID，用于关联同一次交互中的多个 Span
gen_ai.user.id	string	用户唯一标识
gen_ai.user.name	string	用户名称

2.3 输入 / 输出

字段 Key	类型	说明
input.value	string	传入该 Span 的原始输入内容（文本或 JSON 字符串）
output.value	string	该 Span 产生的原始输出内容
input.mime_type	string	input.value 的 MIME 类型，默认 text/plain
output.mime_type	string	output.value 的 MIME 类型，默认 text/plain

2.4 时间

字段 Key	类型	说明
gen_ai.user.time_to_first_token	integer	用户视角的首 Token 响应时间（纳秒）
gen_ai.response.reasoning_time	integer	推理模型的推理过程耗时（毫秒）

2.5 扩展

字段 Key	类型	说明
metadata	JSON	自定义键值对元数据
tag.tags	string[]	用于过滤与分组的标签列表
content	string	通用内容字段

---

三、gen_ai.operation.name 枚举值

枚举值	含义	适用 Span 类型
chat	对话补全	LLM
text_completion	文本补全（旧版）	LLM
generate_content	多模态内容生成	LLM
create_agent	创建 Agent	AGENT
invoke_agent	调用 Agent	AGENT
execute_tool	执行工具	TOOL
embeddings	向量嵌入	EMBEDDING
retrieve	检索	RETRIEVER

---

四、各 Span 类型专属字段

4.1 LLM Span

适用操作名： chat / text_completion / generate_content

模型标识

字段 Key	类型	说明
gen_ai.provider.name	string	AI 提供商，如 openai、anthropic、gcp.gemini 等
gen_ai.request.model	string	请求指定的模型名称
gen_ai.response.model	string	响应实际使用的模型名称（可能与请求不同）
gen_ai.output.type	string	输出类型，取值：text / json / image / speech
gen_ai.model_name	string	⚠️ 已废弃，请使用 gen_ai.request.model

请求参数

字段 Key	类型	说明
gen_ai.request.temperature	float	采样温度，控制生成随机性
gen_ai.request.top_p	float	核采样参数
gen_ai.request.top_k	float	Top-K 采样参数
gen_ai.request.max_tokens	integer	最大生成 Token 数
gen_ai.request.stop_sequences	string[]	停止生成的特殊序列列表
gen_ai.request.frequency_penalty	float	频率惩罚系数
gen_ai.request.presence_penalty	float	存在惩罚系数
gen_ai.request.seed	integer	随机种子（用于确定性生成）
gen_ai.request.choice.count	integer	请求的候选补全数量（不为 1 时记录）
gen_ai.request.is_stream	boolean	是否为流式响应
gen_ai.request.tool_calls	string	请求中携带的工具调用信息
gen_ai.request.parameters	string	⚠️ 已废弃

响应

字段 Key	类型	说明
gen_ai.response.id	string	模型响应唯一标识符
gen_ai.response.finish_reasons	string[]	各候选的停止原因，如 stop / length / tool_call / content_filter / error
gen_ai.response.time_to_first_token	integer	模型自身首 Token 延迟（纳秒，流式场景）
gen_ai.response.time_per_output_token	integer	平均每个输出 Token 耗时
gen_ai.response.reasoning_content	string	⚠️ 已废弃，推理模型推理内容

Token 用量

字段 Key	类型	说明
gen_ai.usage.input_tokens	integer	输入 Token 数
gen_ai.usage.output_tokens	integer	输出 Token 数
gen_ai.usage.total_tokens	integer	总 Token 数（input + output）

延迟（自托管模型）

字段 Key	类型	说明
gen_ai.latency.time_in_model_prefill	integer	模型 Prefill 阶段耗时
gen_ai.latency.time_in_model_decode	integer	模型 Decode 阶段耗时
gen_ai.latency.time_in_model_inference	integer	模型推理总耗时

消息内容（默认不采集，需主动开启）

字段 Key	类型	说明
gen_ai.input.messages	JSON	发送给模型的完整消息列表
gen_ai.output.messages	JSON	模型返回的完整消息列表
gen_ai.system_instructions	JSON	系统提示词（独立于聊天历史）
gen_ai.tool.definitions	JSON	传递给模型的工具定义 Schema
gen_ai.input.messages_ref	string	输入消息的外部引用地址
gen_ai.output.messages_ref	string	输出消息的外部引用地址
gen_ai.system_instructions_ref	string	系统指令的外部引用地址

消息结构字段（gen_ai.input.messages / gen_ai.output.messages 内部字段）

字段 Key	类型	说明
message.role	string	消息角色：user / assistant / system / tool
message.content	string	消息文本内容
message.name	string	消息名称（通常用于标识函数名）
message.tool_calls	JSON	模型生成的工具调用列表
message.function_call_name	string	Function Call 的函数名
message.function_call_arguments_json	string	Function Call 的参数 JSON 字符串

---

4.2 AGENT Span

适用操作名： create_agent / invoke_agent

AGENT Span 无独立专属属性类，继承 LLMAttributes 的全部字段。以下为 AGENT 场景下重点关注字段：

字段 Key	类型	说明
gen_ai.operation.name	string	create_agent（创建远程 Agent）或 invoke_agent（调用 Agent）
gen_ai.conversation.id	string	对话/线程 ID，用于跨 Span 关联同一次 Agent 运行
gen_ai.data_source.id	string	Agent 使用的数据源 ID（RAG 场景）
gen_ai.retrieval.query.text	string	Agent 发起检索时的查询文本
gen_ai.provider.name	string	提供 Agent 服务的 AI 厂商
gen_ai.request.model	string	Agent 调用的基础模型名称
gen_ai.usage.input_tokens	integer	本次 Agent 调用的输入 Token 总数
gen_ai.usage.output_tokens	integer	本次 Agent 调用的输出 Token 总数
gen_ai.input.messages	JSON	传入 Agent 的完整消息历史（默认不采集）
gen_ai.output.messages	JSON	Agent 返回的完整消息（默认不采集）
gen_ai.tool.definitions	JSON	Agent 可用的工具定义列表（默认不采集）
gen_ai.system_instructions	JSON	Agent 的系统指令（默认不采集）

---

4.3 TOOL Span

适用操作名： execute_tool

OTEL 工具标识字段（来自 ToolAttributes）

字段 Key	类型	说明
gen_ai.tool.name	string	工具名称
gen_ai.tool.description	string	工具能力描述
gen_ai.tool.call.id	string	本次工具调用的唯一 ID
gen_ai.tool.type	string	工具类型：function（本地函数）/ custom（自定义）/ unknown

OpenInference 工具字段（来自 SpanAttributes / ToolCallAttributes）

字段 Key	类型	说明
tool.parameters	JSON	工具输入参数的 JSON Schema
tool_call.function.arguments	string	工具调用时传入的参数（JSON 序列化字符串）
tool_call.function.thoughts	string	模型调用工具前的思考内容

---

4.4 EMBEDDING Span

适用操作名： embeddings

字段 Key	类型	说明
gen_ai.request.model	string	嵌入模型名称
gen_ai.request.encoding_formats	string[]	请求的向量编码格式，如 float、base64
gen_ai.request.temperature	float	采样温度（部分模型支持）
gen_ai.usage.input_tokens	integer	嵌入请求消耗的输入 Token 数
gen_ai.embeddings.dimension.count	integer	嵌入向量的维度数
embedding.embeddings	JSON	嵌入结果列表，每项含原始文本与向量
embedding.model_name	string	⚠️ 已废弃，使用 gen_ai.request.model 替代
embedding.embedding_output	string	⚠️ 已废弃

---

4.5 RETRIEVER Span

适用操作名： retrieve

字段 Key	类型	说明
retrieval.documents	JSON	检索返回的文档列表，每项包含 id / score / content / metadata
retrieval.documents.list.length	integer	检索返回的文档数量

文档子结构字段（来自 DocumentAttributes）

字段 Key	类型	说明
document.id	string	文档唯一标识符
document.score	float	文档与查询的相关性评分（0.0 ~ 1.0）
document.content	string	文档块的文本内容
document.metadata	JSON	文档来源元数据（如文件名、页码、URL 等）

---

4.6 RERANKER Span

字段 Key	类型	说明
gen_ai.span.kind	string	固定为 RERANKER
gen_ai.operation.name	string	建议填写 rerank
input.value	string	传入重排序器的查询内容
output.value	string	重排序后输出的文档列表（JSON 序列化）
gen_ai.conversation.id	string	关联的对话 ID
metadata	JSON	自定义元数据

---

4.7 CHAIN Span

CHAIN Span 无专属属性类，通过 gen_ai.span.kind = CHAIN 标识，全部属性来自通用字段。

字段 Key	类型	说明
gen_ai.span.kind	string	固定为 CHAIN
gen_ai.operation.name	string	链式流水线的操作名称（自定义）
gen_ai.span.sub_kind	string	链的子类型，用于区分不同类型的 Chain
input.value	string	进入 Chain 的原始输入
output.value	string	Chain 产生的最终输出
gen_ai.conversation.id	string	关联的对话 ID
gen_ai.framework	string	使用的 AI 框架（如 LangChain、LlamaIndex）
metadata	JSON	自定义元数据

---

4.8 TASK Span

TASK Span 无专属属性类，通过 gen_ai.span.kind = TASK 标识，语义上表示 Agent 分解的一个独立工作单元。

字段 Key	类型	说明
gen_ai.span.kind	string	固定为 TASK
gen_ai.operation.name	string	任务操作名称（自定义）
gen_ai.span.sub_kind	string	任务子类型或状态标识
input.value	string	任务输入内容
output.value	string	任务输出内容
gen_ai.conversation.id	string	关联的对话 ID
gen_ai.user.id	string	关联的用户 ID
metadata	JSON	任务的自定义元数据

---

4.9 MCP_CLIENT Span

基于 OTEL MCP 规范

字段 Key	类型	说明
gen_ai.span.kind	string	固定为 MCP_CLIENT
mcp.method.name	string	必填 MCP 调用的方法名称
error.type	string	错误类型（操作失败时填写）
gen_ai.prompt.name	string	MCP Prompt 名称
gen_ai.tool.name	string	MCP 调用的工具名称
gen_ai.operation.name	string	操作类型
rpc.response.status_code	string	MCP 响应状态码
jsonrpc.protocol.version	string	JSON-RPC 协议版本
mcp.protocol.version	string	MCP 协议版本
network.protocol.name	string	网络协议名称
network.protocol.version	string	网络协议版本
network.transport	string	传输层协议
server.address	string	MCP Server 地址
server.port	integer	MCP Server 端口
mcp.resource.uri	string	MCP Resource 的 URI

---

五、枚举值速查

gen_ai.response.finish_reasons 枚举值

枚举值	含义
stop	正常停止
length	达到最大 Token 数限制
content_filter	内容过滤触发
tool_call	模型请求调用工具
error	发生错误

gen_ai.output.type 枚举值

枚举值	含义
text	纯文本
json	JSON 对象
image	图像
speech	语音