跳到主要内容

GenAI 领域模型 — 约定了哪些字段

本章是「字典内容」本身:做 LLM/agent 可观测时你最常查的字段都在这。每节先说这字段回答什么问题,再给真实定义位置和坑。所有引用都在 model/gen-ai/deprecated/ 与 model/{mcp,openai}/deprecated/(此 commit 下它们带 deprecated 标记,但定义内容就是约定本身,见第 4 章)。

字段定义 vs 信号组,两个文件: 单个字段(provider.name、token、messages、tool.* 等)的定义都在 registry-deprecated.yaml;span 组(span.gen_ai.*、必填级别、span 名 note)在 spans-deprecated.yaml。本章引用按此区分。

2.1 两个判别器:provider.name 与 operation.name​

整套 GenAI 约定围着两个字段转,先吃透它们。

gen_ai.provider.name —— 「这是哪家的遥测格式」。 它是枚举,值含 openai / anthropic / aws.bedrock / gcp.gemini / azure.ai.openai / mistral_ai / deepseek 等(model/gen-ai/deprecated/registry-deprecated.yaml:274-351,gen_ai.provider.name)。

关键不是「谁造的模型」,而是**「遥测长成谁家的样子」**。定义里的 note 把这点说死了:

它是一个判别器,标识该 provider 在 GenAI 约定里的遥测格式 flavor;AWS Bedrock 的 span 应设 aws.bedrock 并带 aws.bedrock.*,不应带 openai.*(registry-deprecated.yaml:366-373)。

所以一个用 OpenAI 兼容 API 代理的服务,provider.name 取决于它模仿谁的格式,而非真实模型来源。

gen_ai.operation.name —— 「这是哪种操作」。 它的枚举值直接对应不同的 span 类型(成员定义在 registry-deprecated.yaml:914 起):

值含义对应 span
chat聊天补全span.gen_ai.inference.client
text_completion旧式文本补全同上
generate_content多模态生成(Gemini)同上
embeddings向量化span.gen_ai.embeddings.client
retrieval检索span.gen_ai.retrieval.client
create_agent创建 agentspan.gen_ai.create_agent.client
invoke_agent调用 agentspan.gen_ai.invoke_agent.{client,internal}
execute_tool执行工具span.gen_ai.execute_tool.internal
invoke_workflow编排多 agentspan.gen_ai.invoke_workflow.internal

span 名约定几乎都是 {operation.name} {request.model}(如 span.gen_ai.inference.client 的 note,spans-deprecated.yaml:150-152),agent/tool span 则用 {operation} {agent.name|tool.name}。

2.2 Token 用量:四个细分,不是一个数​

「这次花了多少 token」在约定里不是一个字段,而是一组,因为缓存和推理改变了成本结构(以下字段定义均在 registry-deprecated.yaml):

字段含义
gen_ai.usage.input_tokens输入总数,含缓存命中的 token(registry-deprecated.yaml:577-593)
gen_ai.usage.output_tokens输出总数(:622-633)
gen_ai.usage.cache_read.input_tokens从 provider 缓存读到的(应包含在 input 内,:594-607)
gen_ai.usage.cache_creation.input_tokens写入 provider 缓存的(:608-621)
gen_ai.usage.reasoning.output_tokens用于推理/思维链的输出(应包含在 output 内,:634-647)

最容易踩的坑——provider 口径不一致。 Anthropic 的 input_tokens 不含缓存 token,所以约定明文要求 instrumentation 自己加回去:

gen_ai.usage.input_tokens = input_tokens
                          + cache_read_input_tokens
                          + cache_creation_input_tokens

这条规则写在 span.anthropic.inference.client 的 note 里(model/gen-ai/deprecated/spans-deprecated.yaml:690-701)。OpenAI 则相反——它的 usage.input_tokens 已含缓存,缓存数另从 input_tokens_details.cached_tokens 取(spans-deprecated.yaml:235-240)。同一个语义字段,各家映射规则不同,这正是约定要统一口径的价值。

聚合侧还有专门的 metric gen_ai.client.token.usage(histogram,单位 {token}),用 gen_ai.token.type(input/output)区分两类(metrics-deprecated.yaml:54-73)。

2.3 会话内容:system_instructions / input.messages / output.messages​

要记「模型到底看到/回了什么」,约定给了三个 any 类型字段(定义在 registry-deprecated.yaml),且都默认 opt_in(因为含敏感内容):

  • gen_ai.system_instructions —— 与对话历史分开传的系统指令(registry-deprecated.yaml:1069-1120)。
  • gen_ai.input.messages —— 输入的对话历史,必须按发送顺序(:1121-1183)。
  • gen_ai.output.messages —— 模型输出,一条 message = 一个 choice/candidate,不可拆分或合并(:1184-1229)。

两个工程约束值得记:

  1. 结构化优先:这些字段必须遵守对应的 JSON Schema;记在 event 上必须结构化,记在 span 上可以退化为 JSON 字符串(:1133-1137)。
  2. 敏感数据:定义里反复用 > [!Warning] 标注可能含 PII(:1143-1144),并指向「Recording content on attributes」章节——这也是它们默认 opt_in 的原因。

早期版本曾用独立 event(gen_ai.system.message、gen_ai.user.message、gen_ai.choice 等)来记每条消息(events-deprecated.yaml:10-355)。现在这些 event 已弃用,内容统一收进上面的 *.messages 属性或 gen_ai.client.inference.operation.details event(见各 event 的 deprecated.note)。这是约定演进的一个真实缩影。

2.4 工具调用:execute_tool span + 三个 tool 字段​

Agent 时代的核心是「模型让你调工具」。约定为此设了一个 internal span span.gen_ai.execute_tool.internal(spans-deprecated.yaml:597-648),关键字段(字段本身定义在 registry-deprecated.yaml):

字段必填级别说明
gen_ai.tool.namerequired工具名,如 "Flights"
gen_ai.tool.call.idrecommended工具调用 id
gen_ai.tool.typerecommendedfunction/extension/datastore(registry-deprecated.yaml:773-790)
gen_ai.tool.call.argumentsopt_in入参(any,可能敏感)
gen_ai.tool.call.resultopt_in结果(any,可能敏感)

gen_ai.tool.type 在模型里是 type: string,不是封闭枚举——它给的是 examples: ['function','extension','datastore'] 加一段 note 描述三类(registry-deprecated.yaml:782-790),而非 type.members。三类语义:function=客户端执行(模型给参数、你的代码跑逻辑);extension=agent 侧直接调外部 API;datastore=供 RAG 取数据。

还有 gen_ai.tool.definitions(any)记「有哪些工具可用」,默认 opt_in 且因为可能很大,不建议默认填充非必需属性(registry-deprecated.yaml:846-895)。

2.5 Agent 与 Workflow:远程 vs 进程内​

约定把「agent」拆成创建和调用,并区分跨进程(client)与同进程(internal),以下均为 spans-deprecated.yaml 里的 span 组:

  • span.gen_ai.create_agent.client —— 创建远程 agent(如 OpenAI Assistants),带 gen_ai.agent.{id,name,description,version}(spans-deprecated.yaml:370-416)。
  • span.gen_ai.invoke_agent.client —— 远程调用 agent(OpenAI Assistants、Bedrock Agents,:531-564)。
  • span.gen_ai.invoke_agent.internal —— 进程内调用(LangChain、CrewAI agents,:566-595)。
  • span.gen_ai.invoke_workflow.internal —— 编排多个 agent 的工作流(:703-747)。

一个微妙的边界规则(invoke_workflow 的 note,:717-728):只有当 instrumentation 能可靠区分「工作流」和「单个 agent」时才发 invoke_workflow。例如 ADK 的 workflow agent 本身就报 invoke_agent,就不该再报 invoke_workflow;而 CrewAI 有独立的 crew 概念,应该报。这种「宁可不报也别报错」的克制,是约定里反复出现的成熟度信号。

2.6 检索(RAG)与评估(Eval)​

检索 span.gen_ai.retrieval.client(spans-deprecated.yaml:331-368):span 名 retrieval {gen_ai.data_source.id},带 gen_ai.retrieval.query.text(opt_in,敏感)和 gen_ai.retrieval.documents(opt_in,any,每个文档至少含 id+score,字段定义 registry-deprecated.yaml:1019-1053)。gen_ai.data_source.id 是 RAG 的 grounding 数据源标识,可配合 db.* 进一步描述(registry-deprecated.yaml:897-913)。

评估 走 event event.gen_ai.evaluation.result(events-deprecated.yaml:376-415),字段直接对应「LLM-as-judge」打分(字段定义在 registry-deprecated.yaml):

字段说明
gen_ai.evaluation.name评估指标名,如 "Relevance"(registry-deprecated.yaml:1230-1241)
gen_ai.evaluation.score.value数值分(double)
gen_ai.evaluation.score.label低基数人读标签,如 relevant/pass/fail(:1254-1270)
gen_ai.evaluation.explanation自由文本解释

这一组正是本 shelf「evals-observability」area 的落点:把模型质量评估也纳入标准遥测,而不仅是性能。

2.7 MCP:工具协议的专属 span​

Model Context Protocol(MCP)有自己的一套 span,且和 GenAI 工具 span 互通。MCP 定义 client/server 两个 span(model/mcp/deprecated/spans-deprecated.yaml),核心字段:

  • mcp.method.name(required,枚举:tools/call、resources/read、prompts/get、elicitation/create 等,model/mcp/deprecated/registry-deprecated.yaml:13-150)。
  • mcp.session.id、mcp.resource.uri、mcp.protocol.version(registry-deprecated.yaml:151-183)。
  • span 名 {mcp.method.name} {target},target 复用 gen_ai.tool.name 或 gen_ai.prompt.name(spans-deprecated.yaml:37-44)。

精妙的去重规则(span.mcp.client 的 note,model/mcp/deprecated/spans-deprecated.yaml:52-59):如果外层 GenAI instrumentation 已经在追踪这次工具执行,MCP instrumentation 不应再开一个 span,而应把 mcp.* 属性贴到已有的 execute_tool span 上。避免同一次工具调用产生两条重复 span——这是跨约定协作的典型设计。

2.8 代码地图​

主题文件符号名
provider 判别器(字段)model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.provider.name
operation 判别器(字段)model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.operation.name
token 四细分(字段)model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.usage.input_tokens 等
tool / messages / eval 字段model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.tool.*, gen_ai.*.messages, gen_ai.evaluation.*
Anthropic token 加和规则(span 组)model/gen-ai/deprecated/spans-deprecated.yamlspan.anthropic.inference.client
工具执行 spanmodel/gen-ai/deprecated/spans-deprecated.yamlspan.gen_ai.execute_tool.internal
agent / workflow spanmodel/gen-ai/deprecated/spans-deprecated.yamlspan.gen_ai.invoke_agent.internal, span.gen_ai.invoke_workflow.internal
评估 eventmodel/gen-ai/deprecated/events-deprecated.yamlevent.gen_ai.evaluation.result
token 用量 metricmodel/gen-ai/deprecated/metrics-deprecated.yamlmetric.gen_ai.client.token.usage
MCP span 与去重model/mcp/deprecated/spans-deprecated.yamlspan.mcp.client, span.mcp.server