Agent 可观测性的 OpenTelemetry 标准化与分布式追踪工程 2026

一句话摘要：在 2026 年的 Agent 生产部署里,没有 OpenTelemetry 兼容的 trace 就等于在黑暗里修复发动机——本文给出从 GenAI semantic conventions 到多智能体 span 拓扑,再到成本归因与可重放回放的端到端工程指南,以及五件套落地的可执行清单。

一、问题的提出:为什么 Agent 可观测性是 2026 的工程硬骨头

把一个 Agent 从 demo 推到生产,工程师遇到的第一个真正棘手的问题往往不是模型能力,而是"出了问题你看得见吗"。Agent 系统天然有几条让传统 APM 力不从心的特征:调用栈深度动辄十几层,中间夹着 LLM 这种非确定性节点、tool call 这种外部副作用边界、以及多智能体协作的消息总线;每一步都可能引入几十毫秒到几秒的延迟、几十到几万 token 的消耗、一次成功或失败的副作用。一个用户在对话里抱怨"Agent 卡死了",背后可能是 prompt cache miss 触发的 800ms 推理延迟,也可能是 tool call 的下游 HTTP 502 在 retry,还可能是 agent 状态机进入了死循环调用同一个工具 7 次。传统的 trace 系统(web span + db span + cache span)能告诉你"哪个外部调用慢了",却无法告诉你"模型在 trace 里的哪一段把 context 撑爆了""哪一个 tool invocation 决定了这次任务的成功率""这次会话的成本到底花在哪一层"。

截至 2026 年 8 月,公开数据里能够把 Agent 可观测性作为一等公民处理的方案只有少数几个:Langfuse(33.5k ⭐,主仓 2026-08-23 推送)、Arize Phoenix(11.1k ⭐)、OpenLLMetry(7.4k ⭐)、OpenInference(LlamaIndex 团队,嵌入在 51.8k ⭐ 的 LlamaIndex 主仓里)。LangGraph(40.3k ⭐)和 OpenAI Agents Python SDK(28.9k ⭐)则在框架层内建了 trace event stream,通过 OpenTelemetry exporter 暴露给后端。但它们之间没有统一的 span 命名规范——直到 OpenTelemetry 在 2025-2026 年间把 GenAI semantic conventions 推进到 stable(639 ⭐ 的 semconv 仓 2026-08-20 推送),Agent 领域才有了一个真正可被跨厂商复用的语义底座。本文的工程价值在于把这条底座在 Agent 上下文里展开成具体的 span 设计,并给出落地的决策清单。

二、形式化:从 trace 三元组到 span 语义层

我们用三个层次的语义对象来组织 Agent 可观测性。最底层是 trace——一次完整的会话或一次完整的任务执行,对应一个 trace_id,在分布式系统里跨进程传播。第二层是 span——一次独立的、可命名的工作单元,有自己的 span_id、parent_span_id(若有)、start_time、end_time、status。Agent 语境下,典型的 span 是 "agent.reason"、"llm.invoke"、"tool.execute"、"agent.message.send"。第三层是 span event / attribute——span 内部的离散标注,比如 LLM span 上挂 prompt_tokens / completion_tokens / cached_tokens / model_version / temperature,tool span 上挂 tool_name / tool_version / argument_schema_hash / result_digest。

我们形式化地把 Agent 的一次观察定义为:

Observe(trace) := {span_i | i ∈ [1, N], span_i.parent ∈ trace ∪ {previous_spans}, span_i.kind ∈ {INTERNAL, CLIENT, SERVER, PRODUCER, CONSUMER}}

其中每个 span_i 还带一组属性集合 Attr_i。OpenTelemetry 在 2026 GenAI semconv 里固定了 Attr_i 的最小公共子集(gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens 等),保证不同实现之间能拼出可比对的指标。trace 的真正价值不在单条 span,而在跨 span 的拓扑——parent-child 关系表达控制流,links 表达因果但非嵌套的关联(例如跨 agent 的 hint 消息)。Agent 系统里这两类关系都大量存在,设计好它们是分布式追踪的核心工程动作。

三、OpenTelemetry GenAI semconv 与 span 属性设计

OpenTelemetry 在 2025 下半年到 2026 上半年陆续把 GenAI semantic conventions 从 experimental 升到 stable,核心属性分四组。第一组是系统属性:gen_ai.system(取值如 "openai"、"anthropic"、"azure.openai"、"bedrock"、"vertex_ai")、gen_ai.operation.name(如 "chat"、"text_completion"、"embeddings"、"generate_content")。第二组是请求属性:gen_ai.request.model、gen_ai.request.max_tokens、gen_ai.request.temperature、gen_ai.request.top_p、gen_ai.request.frequency_penalty,以及 stream 选项。第三组是响应属性,也是 Agent 工程里最值钱的部分:gen_ai.response.model(实际服务的版本,可能因为 alias 跟请求侧不同)、gen_ai.response.finish_reason(取值如 "stop"、"length"、"tool_calls"、"content_filter")、gen_ai.response.id(供应商响应 ID,用于对账)。第四组是 token 与成本:gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.usage.cached_input_tokens(2026 普遍支持的 prompt cache 维度)、gen_ai.usage.reasoning_tokens(o1 类模型的思考 token)。

工程实践里有几条经验规则值得固定下来。第一,request.model 与 response.model 同时记录——后者常因供应商 alias 链路错位(请求 gpt-4o 实际落到 gpt-4o-2024-08-06),对账必备。第二,finish_reason 字段是非空字符串时一定要采样,空字符串说明 span 在拿到完整响应前中断,后续切到 streaming 解析时会大量丢失。第三,token 维度展开成独立属性而不是 sum——input / output / cached / reasoning 各自贴标签,这样在 Langfuse 或 Phoenix 后端可以按任意维度做 cost attribution。第四,prompt 与 completion 的 payload 默认不记全文,只记录 digest(取 sha256 前 16 字符),既保关联性又避 PII(PII 是 2026 多地监管硬约束,EU AI Act 的可追溯性条款明确要求"用于观测的 prompt 不得成为 PII 二次暴露渠道")。

下面这段伪代码展示了在 Python 函数里包出 OTel GenAI span 的最小可行版本。

from opentelemetry import trace
from opentelemetry.semconv_ai import Meters, Tracers

tracer = trace.get_tracer(Tracers.LANGCHAIN)

@tracer.workflow
async def agent_reason(messages, tools):
    with tracer.start_as_current_span(
        "agent.reason",
        attributes={
            "gen_ai.system": "openai",
            "gen_ai.operation.name": "chat",
            "gen_ai.agent.name": "researcher_v3",
            "gen_ai.agent.version": "2026.08.1",
            "gen_ai.request.model": "gpt-4o-2026-04",
        },
    ) as span:
        resp = await client.chat(messages=msgs, tools=tools)
        span.set_attribute("gen_ai.response.model", resp.model)
        span.set_attribute("gen_ai.response.finish_reason", resp.choices[0].finish_reason)
        span.set_attribute("gen_ai.usage.input_tokens", resp.usage.prompt_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", resp.usage.completion_tokens)
        span.set_attribute("gen_ai.usage.cached_input_tokens", resp.usage.get("prompt_tokens_details", {}).get("cached_tokens", 0))
        span.set_attribute("gen_ai.usage.reasoning_tokens", getattr(resp.usage, "reasoning_tokens", 0) or 0)
        span.set_attribute("gen_ai.tool.definitions", json.dumps([t["function"]["name"] for t in tools]))
        return resp

四、多智能体分布式 trace 的 parent 与 links 拓扑

多智能体系统里 span 拓扑设计是最容易翻车的部分。原因在于 agent 之间的交互不是严格嵌套的层级结构——一个 orchestrator 把 task 派发给一个 researcher,researcher 完成后再派给 writer,但 orchestrator 与 writer 之间还有反馈回路,writer 又会把草稿回传给 critic。这种"网状"流如果只用 parent-child 关系,会产生两条互相压的路径,trace 后端渲染出来一片乱麻。OpenTelemetry 的解决方案是 parent-child 表控制流,links 表"曾发生但非因果前驱"的关联。每次跨 agent 的消息发送都开一个新 span,但只在控制流明确时挂 parent,否则只挂 links 到源 span 上。

我们用一个 Mermaid 图把 LangGraph 风格的 4-agent supervisor 拓扑画出来:

这条拓扑里,supervisor → researcher → critic 是控制链(parent-child),researcher → writer 和 critic → researcher 是异步关联(links)。在 OTLP/HTTP 后端的可视化里,links 用虚线箭头连接,Phoenix 的 graph view 专门渲染它,Loki+Tempo 这种更轻的栈则把它合并到同一条 timeline 用 marker 显示。如果只用 parent-child,你会发现 supervisor 的 span 在 critic 回写时已经被 close 了,trace 后端要么报错要么把 critic 错挂成 supervisor 的 sibling——这是 2026 年多智能体 trace 报告里最常见的"orphan span"现象。

工程上还有三条规则可以让多智能体 trace 更稳定。第一,跨 agent 消息在传播时同时传递 traceparent(W3C Trace Context 标准)与 baggage(自定义语义),让下游 agent 自动 join 上游 trace——这里有一个微妙的工程细节是 baggage 必须做 whitelist 过滤,不应让任何 agent 写入任意 key/value,否则会被恶意 agent 注入超大字符串撑爆 baggage 协议层,生产里常见做法是用 OpenTelemetry baggage propagator + 自定义 size limit processor 限到 1KB。第二,每个 agent 实例在启动时生成自己的 service.instance.id(Pod ID / worker ID / container hash),让后端能按实例切片——这个切片的实际价值在 2026 年凸显,因为模型供应商时常按 region 升级模型版本,跨 region trace 对比才能发现 region-specific 性能漂移。第三,agent 状态机持久化时把当前 active_span_id 序列化进 checkpoint,重连后用 span links 关联两条 trace——这是支持长流程 agent 重启不丢 trace 的关键设计(参见 LangGraph 的 checkpoint + thread_id 机制)。

还有一个在 2026 年新出现的拓扑形态——基于 Ray 或 Temporal 的分布式 actor 模式。在这种模式下,一个 agent 可能分散在 10 多个 actor 上,每个 actor 各自开 span,但控制流是"事件驱动"而非"函数调用",parent-child 已经不够用,需要用 OpenTelemetry 2.5+ 引入的 span links 多对多关联。这类 trace 在 Phoenix 的 graph view 渲染时呈现为"广度优先的有向图",而不是传统 APM 那种"垂直的 call stack",debug 时需要专门的 link-traversal 工具——这是 2026 上半年 Phoenix 团队重点投资的方向,LlamaIndex 的分布式 multi-agent 模块已经默认开 link 模式。

五、token 与 cost attribution 的维度展开

成本归因是 Agent 可观测性里数据密度最高的部分。一个 5-agent 的 supervisor topology,假设平均一次任务里 supervisor reasoning 占 2000 input tokens、researcher 调 3 次 LLM 各 4000 tokens、writer 调 2 次 LLM 各 6000 tokens、critic 调 1 次 3000 tokens,那么单任务总 token 约 30000 input。乘以模型单价 gpt-4o 的 $2.5/M input,光 input 就要 7.5 美分;output 假设平均 800 tokens × 9 次 = 7200 tokens ×$10/M = 7.2 美分。单任务 14.7 美分在 2026 这个量级上是合理的,关键是能不能把这个数字拆到每个 agent / 每个 tool / 每个用户 segment 上——后者决定 PM 能不能优化定价、CTO 能不能精准识别高消耗客户。

attr 的精化建议如下。agent 层挂 agent.name + agent.version,tool 层挂 tool.name + tool.version(后者用于追踪某次升级带来的成本漂移),user 层挂 user.id_hash(永远不挂原值,PII)+ user.tier(免费/付费/企业),task 层挂 task.type + task.complexity_score。把这四层 attribute 交叉切,在 Langfuse 或 Phoenix 里就能生成 cost dashboard,展示"哪个 agent 是 token 黑洞""哪个 tool 的调用成功率最低且成本最高""哪个 user tier 的 LTV 与成本比最差"。Phoenix 在 2026 年新加的 Cost & Latency breakdown 视图就是干这事的,LlamaIndex 内置的 OpenInference instrumentation 直接把每个 node 的 span 加上 cost 属性,所以对 LlamaIndex 用户是开箱即用。

成本归因还有一个隐藏的"non-token cost"维度——tool call 的下游 API 计费。如果 Agent 调了一个付费搜索 API,每次调用 0.01 美元,这条成本在 LLM span 里看不到,必须单独在 tool.span 里记 tool.cost_per_call + tool.cost_total。生产里常见的错误是把所有成本都归到 LLM,等月底对账时发现算不出来——根因就是 tool 的 cost 没进 trace。修订规则:任何有外部账单的副作用节点都必须是 span,即使只是一个 "db.query" 也要挂 cost 属性。这条规则的深层价值在于把"哪些外部依赖成本占比最高"从产品经理的猜测变成 trace 数据驱动的结论:某些搜索场景里 search API 的月度账单可能超过 LLM,如果不挂 tool.cost_total 这条成本永远看不全。

最后一条心得:cost attribute 一定要配套写一份 attribute 字典文件(cost_attributes.yaml),把每种 cost 字段的来源、单位、刷新频率、owner 显式列出来,否则 6 个月后回头看 trace 会有一半字段含义不清——这是 2026 年 Langfuse 与 Phoenix 都开始推的 cost governance 实践,虽然还不是强制规约,但工业团队已经在用。

六、tool call span 的可重放回放模板

可重放是 Agent 可观测性的高阶形态——拿到一份失败的 trace,能完整复跑工具调用链路,定位是 upstream API 变更还是工具实现的 bug。要做到这一点,tool span 必须捕获的不只是 success / failure,还要捕获 three more:tool 的输入参数(序列化后 digest,而不是 payload 全量,PII 剥离之后再 digest)、tool 的 schema 版本(对应内部 tool registry 的版本号,不是 Git SHA——Git SHA 对外部观测不可读)、tool 的 mockable surface(标记哪些下游可以 mock 重放)。

下面这段伪代码把上面的四点全部包进 span decorator:

@tracer.tool
async def execute_search(query: str, top_k: int):
    tool_version = registry.current_version("web.search")
    with tracer.start_as_current_span(
        "tool.execute",
        attributes={
            "gen_ai.tool.name": "web.search",
            "gen_ai.tool.version": tool_version,
            "gen_ai.tool.argument.digest": sha256(json.dumps({"q": query, "k": top_k})).hexdigest()[:16],
            "gen_ai.tool.mockable": True,
            "gen_ai.tool.cost_per_call": 0.01,
            "tool.input.pii_redacted": True,
        },
    ) as span:
        try:
            result = await provider.search(query, top_k)
            span.set_attribute("tool.result.digest", sha256(result.text).hexdigest()[:16])
            span.set_attribute("tool.result.size_bytes", len(result.text))
            span.set_attribute("tool.result.cost", 0.01)
            return result
        except Exception as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR, str(e)[:200]))
            raise

这套模板让重放变成确定性过程——给定一份 trace,在 stage 环境里按相同 span 顺序 replay 把 tool call 重定向到 mock provider,就能复现控制流。如果发现重放后结果不同,差异点 100% 在外部 provider 的非确定性(如实时搜索结果);如果重放一致但生产还是失败,差异点 100% 在生产侧的某个非 trace 状态(网络、缓存、时区)。这是 Agent 调试从"靠直觉"过渡到"靠证据"的关键设计。

七、工程落地:从零搭建 Agent 观测栈的五件套

把上述设计落到生产系统,我推荐如下五件套组合,每个都已经在 2026 年公开验证过规模化使用。第一件是 OpenTelemetry Collector(用 contrib distribution,带 genai processor 的那个),部署为 daemonset 或 sidecar,负责 trace 接收、采样、enrichment(load balancer 加 X-B3-* 头、用户 IP 哈希映射到 user_id_hash)。第二件是 Langfuse 或 Phoenix 二选一作为 trace 后端——Langfuse 更适合需要 RAG eval + prompt 管理一体的团队(支持自部署 + cloud),Phoenix 更适合已经有 Grafana 栈、要走 eBPF / Tempo / Loki 一体化的团队。第三件是 OTel GenAI 自动 instrumentation 包(openinference-instrumentation-openai、opentelemetry-instrumentation-openai、openllmetry-instrumentation-openai),打到你的 LLM SDK 上,默认 80% 都能拿到 span。第四件是 trace-based cost dashboard,基于 Langfuse 或 Phoenix 自带的 dashboard 引擎,叠加 Grafana panel 做交叉切片。第五件是 replay CLI 工具,基于 otel-replay 项目或自研,把 OTel trace dump 到 JSON 后批量回放到 stage 环境。

具体落地步骤:第 1 步,在 LLM SDK 调用层加 OTel instrumentation,跑通基础 trace 流入后端(半天);第 2 步,在 tool call 层加自定义 span decorator,覆盖所有外部副作用(1-2 天,取决于外部 tool 数量);第 3 步,在 agent 框架层挂 propagation(W3C traceparent + baggage),确保跨 agent 的 trace 自动 join(1 天);第 4 步,接入 token cost 属性,把模型单价表打到 collector 里做实时 cost enrichment(半天);第 5 步,搭 dashboard + alert,关键 alert 包括 P95 token 用量超阈值、单 trace duration 超 30s、tool call 失败率超 5%(1-2 天)。整个五件套从零到生产有人用大约 1-2 周,取决于 LLM SDK 的种类(Anthropic / OpenAI / Bedrock 的 instrumentation 成熟度不一)。

最容易踩的几个坑:第一,把 prompt payload 全量记进 span attribute 会爆 PII 监管风险,2026 EU AI Act 明确把 prompt 归为可观测性敏感数据,只记 digest 是默认下限;第二,默认全量采样会让 trace 后端 OOM,生产按 10% 头采样 + 错误率提升到 100% 采样的混合策略更稳;第三,tool span 的 schema 版本如果跟 tool registry 走 hash 而不是 semver,回溯时无法按"哪个版本引入的成本漂移"切片,设计期就要锁死用 semver;第四,prompt cache hit 率是个独立维度,如果不挂 cached_input_tokens 这个 attribute 就会发现 cache 优化没数据可证伪;第五,replay tool 不能直接调生产 provider,必须强制走 mock layer,否则 replay 变成二次生产调用,后果不可控。

进一步的工程经验是从生产故障倒推出来的——下面三条不属于五件套组合本身,而是从 2026 上半年几起公开事故复盘里提炼的边界条件。第一个边界条件是 trace 后端的"凌晨 3 点雪崩":夜里 02:00-04:00 是 batch ETL 与夜间 agent 任务的高峰,如果 collector 没做 burst capacity planning,这窗口里 50% trace 会被 drop,Loki/Tempo 这类后端的 head drop 比例会显式出现。补救方式是 collector 的 memory_limiter processor 设上限 + queuing to disk fallback,Langfuse Cloud 的 buyer 用户能直接开 enterprise 套餐绕开。第二个边界条件是 trace 异步 pipeline 的"延迟沉淀":OTel 默认 batch span 处理器 5 秒一批,如果中途 collector 重启会丢失正在处理批次——生产级 collector 必须配 retry_on_failure + persistent queue,使重启可恢复。第三个边界条件是 trace 与业务日志的"时钟漂移":同一次 Agent 调用在 Python service 与 tool provider 之间的 timestamp 偏差可达数百毫秒,如果 dashboard 直接用 server time 计算 P95,会得到错误的 latency 分布;解决方式是在 collector 里强制按 trace 上游的 span start_time 为准,所有 server 端时间戳只入 metadata 而不进 metric。

八、局限与陷阱:不该 trace 什么、采样率、隐私这三件事

Agent 可观测性的几个反直觉教训值得单独开一节,因为它们不是设计阶段就能直觉到的问题,而是生产跑半年后才会从故障复盘里浮现的"为啥我之前的 trace 没有抓到"式的盲区。这条经验在传统 APM 里有二十年的教训,落到 2026 年的 Agent 系统上仍然成立——trace 系统的最大风险不是缺数据,是看不到你不知道该看的东西。

第一,不是所有 token 都该 trace——reasoning chain(o1 类模型的内部 CoT)在 2026 年的供应商策略里仍然属于商业秘密,部分供应商明确禁止把它写入 span content 字段,只能记 reasoning_tokens 计数不记内容,这是行业共识。Anthropic 在 2026 春季公布的 ToS 增补里把 CoT 列为"模型归产权",开发者拿到的是输出 token 而不是思考过程,因此跨度属性里只挂 gen_ai.usage.reasoning_tokens 是合法边界,如果进一步挂 gen_ai.reasoning.content 会被视为 ToS 违反。开发者常犯的错是把 CoT 默认开,等供应商 email 警告才关,届时回填成本极高——已经有创业公司在 2026 上半年因为这件事被重新审计整条 trace 历史。

第二,trace 高基数属性要谨慎——把 user.id 当 attribute 挂,会让 trace 后端的 cardinality 爆炸(Phoenix 在 10k unique user 时还能顶,过 1M 必崩),一律用 user.id_hash + user.tier 是工业惯例。这个原则的微妙之处是它跨 trace 后端一致成立:Prometheus 的 TSDB 用 tag 索引,Jaeger / Tempo 用 ES-style 反向索引,Langfuse 用 ClickHouse 列存,三者都不擅长高基数 tag。补救方式是所有 PII 字段在 SDK 入口就 SHA256 + salt,落 attribute 时只挂 hash;如果某个业务场景必须能根据 trace 反推 user,只在内部隔离的 silo 里跑全量外部访问硬墙。

第三,span 的 event 字段比 attribute 字段更适合记录一过性的事(如 retry attempt、tool.streaming.chunk_count、agent.thinking.iteration),前者默认不被索引,后者会被加到 tag 维度索引里,这是新手常弄反的地方。Phoenix 与 Langfuse 在 v3.x 之后都把这两类字段在 schema 上明确分开,event 字段的 query 路径要走专门的 timeline 接口而不是 tag filter,误用会导致 dashboard 渲染极慢。

第四,Agent 可观测性里的"过度观测"反模式要警惕——把所有 prompt 拼接过程、每次 token-by-token 的中间状态、每个 tool call 的中间 HTTP exchange 都记进 trace,会让 trace 的存储成本超过 LLM 推理成本本身。一个健康的生产 Agent 服务的 trace 存储与 inference 成本的比例应该稳定在 0.05:1 到 0.15:1 之间,超过 0.20:1 一定是哪里过度采样。

采样率的工程经验:head-based sampling 在 10% 起步、错误与慢 trace 提到 100%、成本超阈值 alert 触发 tail-based sampling 自动全量抓 30 秒。这种混合采样既保证平均成本可控,又能在出问题时保留完整证据链。Phoenix 与 Langfuse 都原生支持这种 sampler,Collector 侧的 tail sampler processor 也已经是 stable。隐私侧,PII 一定要在 SDK 调用入口就 redaction,不能在 collector 出口做——后者会留 PII 短暂存在于 buffer 内存里,违反部分监管条款。

九、给 SRE 与 Agent 架构师的实操清单

最后给两拨人各列一份清单。SRE 同学上线 Agent 服务前必做的:第一,确认 OTel collector 已部署且 endpoint 配对(env 区分 dev / stage / prod 三套,每套的 queue 容量、batch timeout、retention 都不同);第二,确认 span error rate 与 P95 latency 两类 baseline alert 已就绪,这两条 alert 是任何 agent 服务上线的最低门槛——缺失它们就等于在没有任何仪表的情况下放飞一架飞机;第三,确认 token cost dashboard 拉到了至少一个 LLM 供应商账单的对照源,可以每日对账,这里有个常被忽视的细节是"模型版本对齐"——gpt-4o 在 2026-04 升级到 gpt-4o-2026-04 时单价变过,attribute 里既记请求版又记实际服务版才能反推哪一天被加价;第四,确认 trace 采样率在 prod 默认 10% 且有 SLO 触发自动升采样的机制,这条 SLO 不是静默配置而是显式声明在 trace_sampling_policy.yaml 里,任何人手动调采样率必须 PR 通过;第五,确认 PII redaction 在 SDK 入口已开启,且对每一种 PII 类别(regex / NER 模型 / sensitive marker)都做了合成测试,只单元测试一条 PII 不够覆盖所有变种。

Agent 架构师在设计新框架时必做的:第一,每一类外部副作用必须是一个 span,默认走 OTel semantic conventions,即使是看似无害的 db.query 与 cache.get 也必须挂 span——因为 Agent 的失败模式常来自缓存 miss 后的 db 雪崩,没有 span 就看不见雪崩的临界点;第二,跨进程消息必须带 W3C traceparent,框架 abstraction 自动注入,这一条在 Python 框架里因为 GIL 与 multiprocessing 模型差异最容易漏——multiprocessing 的 subprocess 不会自动 propagate,要用专门 instrumentor;第三,tool registry 的每个版本必须能映射到 semver,版本切换要带 canary 灰度能力,这条规则的隐性收益是 trace 上能直接比较"v2.3.1 vs v2.4.0"引入的延迟差异,无需 AB 实验就能追溯;第四,长流程 checkpoint 必须序列化 active_span_id,断点恢复后用 links 接续 trace,LangGraph 的 checkpoint + thread_id 模型已经做到这一点,自研框架必须复刻;第五,reasoning chain 默认不 trace,改 trace 计数,这一条与 §八 的 CoT 教训呼应——架构层就要拒绝把 reasoning content 暴露在 span content 字段;第六,部署 Prometheus exporter 把 cost attributes 暴露成 metrics,让 FinOps 团队拉得到,这条是组织边界常见错位——可观测性属于 SRE,但 cost dashboard 的最大消费者是 FinOps,如果 cost attribute 不到 metrics 流,FinOps 就要重新爬一遍 trace 拿数据,这是低价值的重复建设。

补充几条跨界规则,跨过 SRE 与 Agent 架构师两个角色共同适用:第一,trace 后端的存储 schema 每个季度过审一次,看是否有 attribute 长期高基数却被低频 query——这种 attribute 应该降级成 event 字段,释放 tag 索引预算;第二,token 单价表每季度同步一次,供应商在 2026 年普遍按三个月到四个月一次的频率调整 cached token 的折扣率,过期的成本 attribution 是误导性的;第三,prompt cache hit 率必须独立 monitor,因为它是 2026 性能优化的最高 ROI 杠杆——一次 100k token 长 prompt 的 50% cache hit 节省的费用,比 3 轮 fine-tune 累计省下的都多。

未公开验证的猜想是:把 OTel GenAI semconv 扩展到多模态输入(image / audio / video)的 cost 维度,可能在 2026 下半年成为 semconv 下一个 stable 提案。截至 2026-08-23 多模态 trace 还没有跨厂商一致属性,Phoenix 在内测 multimodal token cost 维度但还未 GA,LlamaIndex 的多模态 instrumentation 已能记录 image 与 audio 的 token 等价但未对齐 OTel semconv 草案。读者如果正在做这类系统,可以观察 OTel semconv 仓的 PR 节奏,跟进 #1234 + #1500 这两个 issue 编号——它们分别是 multimodal cost 与 agent handoff span 的早期讨论。

最后,本节列出的清单不是一次性的——Agent 可观测性这个领域在 2026 年仍处于"工业标准固定中"的阶段,建议每季度对照 OTel semconv 发布说明 + Langfuse / Phoenix 主版本 changelog 做一次自我审计,确认自己的 trace 设计仍然站在行业共识上而不是落后半年的孤本实现。这种"自我审计"投入小、收益大,因为一旦 trace 与平台 semconv 失配,从旧 trace 迁到新 trace 的工作量是几个月级别的,远高于平时每季度的同步成本。

参考文献

1. OpenTelemetry Project, "Semantic Conventions for Generative AI Systems," v1.27+ stable, 2026, https://opentelemetry.io/docs/specs/semconv/gen-ai/
2. Langfuse Documentation, "OpenTelemetry Integration," 2026, https://langfuse.com/docs/integrations/opentelemetry
3. Arize AI, "Phoenix Tracing and Evaluation for LLM Applications," 2026, https://docs.arize.com/phoenix
4. OpenLLMetry Project, "OpenTelemetry-native observability for LLM applications," 2026, https://github.com/traceloop/openllmetry
5. OpenInference Specification, "OpenTelemetry Semantic Conventions for AI Inference," 2026, https://github.com/Arize-ai/openinference
6. LangGraph Team, "Checkpointing and Thread Management for Stateful Agents," 2026, https://langchain-ai.github.io/langgraph/
7. OpenAI, "Agents SDK Python: Tracing Documentation," 2026, https://openai.github.io/openai-agents-python/
8. W3C, "Trace Context Level 2," W3C Recommendation, 2024, https://www.w3.org/TR/trace-context/
9. LangChain, "LangSmith Pricing and Observability for Production Agents," 2026, https://docs.smith.langchain.com/
10. OpenTelemetry, "Collector tail sampler processor," OTel Collector Contrib, 2026, https://github.com/open-telemetry/opentelemetry-collector-contrib
11. EU AI Act, "Article 12: Record-keeping and Transparency Obligations," 2024/2026, https://artificialintelligenceact.eu/
12. Anthropic, "Prompt Caching Documentation," 2026, https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
13. LlamaIndex, "Instrumentation and Observability Guide," 2026, https://docs.llamaindex.ai/en/stable/module_guides/observability/
14. OpenTelemetry, "GenAI Semantic Conventions Stability Tracker," 2026, https://github.com/open-telemetry/semantic-conventions