OpenTelemetry 从 CNCF 毕业（5月21日）。在 240 多个云原生项目中，项目活跃度仅次于 Kubernetes，拥有来自 2800 多家公司的 12000 多名贡献者。

目前最活跃的子规范是 GenAI：从 v1.37 到 v1.41 的每个版本都有涉及。完整遍历六个层级（客户端 Span、Agent Span、MCP、事件、指标、提供商约定）：

https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions…

#OpenTelemetry #GenAI #可观测性

OpenTelemetry 如何追踪 LLM 调用、Agent 推理和 MCP 工具

来源：https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions LLM 应用的可观测性与传统微服务不同。一次 LLM 调用产生的遥测数据远比一次 HTTP 请求多，但更难的问题是数据的形状。提示和补全是大量文本块。工具调用参数每次的结构都不同。Agent 的多步推理无法用固定模式捕获。除了通常的“调用了哪个模型以及耗时多久”，你还需要知道消耗了多少 token、调用成本是多少，以及答案是否令人满意。

传统的 OTel 语义约定并不涵盖这些。http.request.method 和 db.system.name 对 LLM 调用毫无意义。社区需要一个专门的规范。

2024 年 4 月，OpenTelemetry 在语义约定 SIG 下成立了 GenAI 特别兴趣小组 (GenAI SIG)[1]。最初的范围是 LLM 客户端调用追踪。此后已扩展到涵盖 Agent 编排、MCP 工具调用、内容捕获和质量评估：总共六个层级。截至撰写本文时，OTel 文档站点显示的语义约定版本为 v1.41.0[2]，最新的 GitHub 版本为 v1.41.1（仅修复了 k8s 代码生成，无 GenAI 更改）[3]。

下面的每个层级涵盖了规范定义了哪些内容、为何如此设计以及其成熟度如何。如果你读过我们之前的文章《Agent 可观测性》(https://greptime.com/blogs/2025-12-11-agent-observability)，那么本文是其规范配套：社区如何针对那篇文章中描述的挑战进行标准化。

OTel GenAI 语义约定 — 六层结构

规范的演变：从早期到 v1.41 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#how-the-spec-evolved-from-early-days-to-v1-41)

当 GenAI SIG 于 2024 年 4 月启动时，目标很简单：为 LLM 客户端调用（模型名称、token 用量、延迟）定义一组标准属性，以便不同的检测库生成一致的遥测数据。早期版本引入了 gen_ai.system、gen_ai.request.model 和一对直方图指标。

v1.37 是转折点。它彻底改了记录聊天历史的方式[4]。旧的每条消息一个事件（每条消息一个事件）被三个聚合属性（gen_ai.system_instructions、gen_ai.input.messages、gen_ai.output.messages）取代，这些属性存储在 span 上或新的 gen_ai.client.inference.operation.details 事件中。原因是实际的：每条消息一个事件会用细粒度的事件淹没多轮对话，导致查询和关联非常痛苦。

随后的每个版本都包含 GenAI 更改：

版本GenAI 更改v1.37[4:1]聊天历史改造；gen_ai.system 被 gen_ai.provider.name 取代v1.38[5]评估事件；工具定义和调用详情；invoke_agent 类型指导；嵌入维度；多模态 JSON 模式v1.39[6]MCP 语义约定v1.40[7]检索 span；缓存 token 属性；Anthropic 输入 token 计算指南v1.41[8]execute_tool span 命名需要工具名称；推理 token；invoke_workflow；流式指标；将 invoke_agent 拆分为 CLIENT/INTERNALOTel GenAI 语义约定 — 演变时间线

截至 2026 年 5 月，GenAI 和 MCP 语义约定仍处于开发状态[2:1]。文档说得很清楚：“此过渡计划将在 GenAI 约定被标记为稳定之前更新以包含稳定版本。” 没有公开的稳定时间表。2026 年语义约定路线图[9]正在收集来自各个子 SIG 的提案，但尚未确定任何内容。

属性名称和结构可能仍会变化。不过核心概念已经确定，规范提供了 OTEL_SEMCONV_STABILITY_OPT_IN 来管理版本过渡。今天基于该规范构建是一个合理的选择。

第一层：客户端 Span — 标准化模型调用 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#layer-1-client-spans-%E2%80%94-standardizing-model-calls)

这是规范的基础层。它定义了当应用程序代码调用 GenAI 模型时产生的 span[10]。

推理 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#inference)

每次 LLM 调用都会生成一个 span，其 gen_ai.operation.name 设置为 chat、text_completion 或 generate_content（用于多模态）。Span 类型为 CLIENT，因为模型通常在远程服务上运行。

核心属性：

属性含义示例gen_ai.provider.name提供商标识openai、anthropic、aws.bedrock``gen_ai.request.model请求的模型gpt-4o-mini``gen_ai.response.model实际响应的模型gpt-4o-mini-2024-07-18``gen_ai.usage.input_tokens输入 token 数量142``gen_ai.usage.output_tokens输出 token 数量87``gen_ai.response.finish_reasons完成原因["stop"]、["tool_calls"]这是它在追踪查看器（Jaeger、Grafana Tempo 等）中的样子：

json

{ "operationName": "chat gpt-4o-mini", "spanKind": "CLIENT", "duration": "1.23s", "attributes": { "gen_ai.operation.name": "chat", "gen_ai.provider.name": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.response.model": "gpt-4o-mini-2024-07-18", "gen_ai.usage.input_tokens": 142, "gen_ai.usage.output_tokens": 87, "gen_ai.response.finish_reasons": ["stop"], "server.address": "api.openai.com", "server.port": 443 } }

注意：这是一个为便于阅读而设计的逻辑视图。实际的 OTLP 有线格式使用带有类型值（stringValue、intValue 等）和纳秒级 Unix 时间戳的 KeyValue 数组。

server.address 和 server.port 是一般网络属性。它们不属于 GenAI 规范，但检测通常仍会发出它们。

provider.name 和 request.model 是故意分开的。相同的模型名称可以通过不同的提供商访问（Azure OpenAI 和直接 OpenAI 都提供服务 GPT-4o），而 provider.name 决定了哪些提供商特定属性适用。

request.model 与 response.model 在实践中也很重要：你请求 gpt-4o，但响应可能来自 gpt-4o-2024-08-06。对于微调模型，response.model 应比基本名称更具体。

嵌入和检索 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#embeddings-and-retrievals)

嵌入（gen_ai.operation.name=embeddings）涵盖向量嵌入操作，gen_ai.embeddings.dimension.count 记录向量维度。检索涵盖 RAG 管道中的检索步骤。

一行集成 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#one-line-integration)

使用 Python + OpenAI SDK，检测只需一行[11]：

python

`` from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

OpenAI SDK 调用将发出符合 semconv 的 span 和指标。

提示/补全事件需要显式启用内容捕获。

client.chat.completions.create(model=“gpt-4o-mini”, messages=[…]) ``

opentelemetry-instrumentation-openai-v2 是最成熟的 GenAI 检测。Anthropic、AWS Bedrock 等其他内容由社区库覆盖。

第二层：Agent 和工作流 Span — 超越微服务 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#layer-2-agent-workflow-spans-%E2%80%94-beyond-microservices)

这是 GenAI 语义约定与传统 OTel 分歧最大的地方。分布式追踪有 HTTP span、RPC span 和 DB span，但没有“Agent 调用”的。GenAI 规范引入了一组新的操作类型[12]。

create_agent (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#create-agent)

描述 Agent 创建，通常用于远程 Agent 服务（OpenAI Assistants API、AWS Bedrock Agents）。Span 类型为 CLIENT。

Span: create_agent support-router Kind: CLIENT Attributes: gen_ai.operation.name = create_agent gen_ai.agent.name = support-router gen_ai.provider.name = openai

invoke_agent (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#invoke-agent)

调用 Agent 执行任务。v1.41 明确拆分为两种场景[8:1]：远程调用使用 CLIENT，本地框架执行（例如 LangGraph 在进程中运行 Agent 逻辑）使用 INTERNAL。

invoke_workflow (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#invoke-workflow)

描述预定义工作流的执行（在 v1.41 中新增[8:2]）。Agent 自主推理；工作流遵循预定路径。

execute_tool (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#execute-tool)

工具执行 span，类型为 INTERNAL。从 v1.41 开始，工具名称必须出现在 span 名称中（execute_tool {gen_ai.tool.name}）[8:3]。gen_ai.tool.call.arguments 和 gen_ai.tool.call.result 仅在隐私政策允许时才记录。

为什么这些 Span 类型很重要 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#why-these-span-types-matter)

我们之前的文章《Agent 可观测性》(https://greptime.com/blogs/2025-12-11-agent-observability) 讨论了一个核心挑战：Agent 的推理过程在追踪中显示为一个黑箱。Agent span 约定打破了这一点：

invoke_agent research-assistant (INTERNAL) ├── chat gpt-4o (CLIENT) ← 模型决定搜索 ├── execute_tool web_search (INTERNAL) ← 执行搜索 ├── chat gpt-4o (CLIENT) ← 用结果继续推理 ├── execute_tool summarize (INTERNAL) ← 总结 └── chat gpt-4o (CLIENT) ← 生成最终答案

每一步都带有标准化的属性，任何兼容的后端（Jaeger、Tempo、Datadog）都能正确渲染该结构。

第三层：MCP 语义约定 — 修复断开的追踪 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#layer-3-mcp-semantic-conventions-%E2%80%94-fixing-broken-traces)

模型上下文协议 (MCP) 在 2025 年迅速普及，但也带来了一个可观测性问题：来自 Agent 端和 MCP 服务器端的追踪是断开的。

Glama 的分析清晰地指出了这一点[13]：Agent 产生追踪 A，MCP 服务器产生追踪 B，两者之间没有上下文传播。在 v1.39[6:1] 中引入的 OTel MCP 语义约定解决了这个问题[14]。

核心设计 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#core-design)

MCP 运行在 JSON-RPC 之上，但规范建议使用 MCP 约定而非通用 RPC 语义约定。MCP span 携带通用 RPC 约定所遗漏的上下文，例如会话和工具调用详情。

客户端 span 示例（stdio 传输）：

Span: tools/call get-weather Kind: CLIENT Attributes: gen_ai.operation.name = execute_tool mcp.method.name = tools/call mcp.session.id = session-xyz mcp.protocol.version = 2025-03-26 gen_ai.tool.name = get-weather jsonrpc.request.id = 42 network.transport = pipe # stdio 映射到 pipe

对于 HTTP 传输，使用 network.transport = tcp（或 quic）配合 network.protocol.name = http[14:1]。

当双方都传播 W3C 追踪上下文时，服务器 span 嵌套在客户端 span 下，追踪连续性在协议边界上得以保持。

与 execute_tool 的兼容性 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#compatibility-with-execute-tool)

规范处理了去重：如果 MCP 检测检测到外部的 GenAI 检测已经在追踪工具执行，它会用 MCP 特定属性（mcp.method.name、mcp.session.id 等）丰富现有的 span，而不是创建重复 span。

一个完整的 Agent + MCP 调用链[14:2]：

invoke_agent weather-forecast-agent (INTERNAL) ├── chat {model} (CLIENT) ← GenAI 模型 ├── tools/call get-weather (CLIENT) ← MCP 客户端 │ └── tools/call get-weather (SERVER) ← MCP 服务器 └── chat {model} (CLIENT) ← GenAI 模型

MCP 特定指标 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#mcp-specific-metrics)

四个 MCP 指标：mcp.client.operation.duration / mcp.server.operation.duration（操作延迟）和 mcp.client.session.duration / mcp.server.session.duration（会话生命周期）。

第四层：事件和内容捕获 — 平衡隐私与可观测性 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#layer-4-events-and-content-capture-%E2%80%94-balancing-privacy-and-observability)

传统的 OTel HTTP span 很少需要担心“是否应该记录请求体？” LLM 应用则不同：提示和补全内容既是最有价值的调试数据，也是最敏感的数据。

两个核心事件 (https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions#two-core-events)

`gen_ai.