00 - 专题索引
前置：知道「日志」和「监控」大概是干什么的。用过 Datadog、SkyWalking 之类的工具会更快，但不是必须。
本专题回答：一次执行该记下哪些东西才够复盘，怎么记才不用把业务代码改一遍，以及这笔钱最后怎么算到具体的人头上。
有人反馈说 Agent 昨天答错了。你打开日志，看到一行：
2026-08-20 14:32:07 POST /agent/chat 200 18.4s
十八秒里发生了什么，这行字一个字都没说。它调了几次模型？中间去查了哪张表？是查回来的数据就是错的，还 是数据对、模型自己编了一句？如果第三步查库返回了空，它有没有换个方式重试？——这些你全都不知道，而且事后再想知道也来不及了，因为当时没记。
传统的监控工具帮不上忙，它们的世界观是「一次请求 = 一条记录」。Agent 的一次请求里套着几十次子操作，还会自己分叉出子 Agent。这个专题要解决的就是：把那十八秒拆开，拆成一棵事后可以逐层展开的树。
拆开之后顺带能回答另一个问题 —— 财务问「这个月哪个部门花了多少钱」的时候，你有地方去查。
先约定几个词，本专题全程使用：
| 词 | 意思 |
|---|---|
| APM | Application Performance Monitoring，应用性能监控。传统那套「记请求耗时、错误率、吞吐」的工具，Datadog、SkyWalking 都属于这一类 |
| span（跨度） | 一次有起止时间的操作记录，比如「调用了一次模型」「执行了一次工具」 |
| trace（追踪） | 一次完整请求里所有 span 组成的树。Agent 的 trace 是树不是链，因为主 Agent 会调子 Agent、子 Agent 再调工具 |
| 语义约定 | 规定 span 该叫什么名字、带哪些属性的标准。有了它，不同厂商的工具才能读懂同一份数据 |
| 埋点（instrumentation） | 在代码里插入产生 span 的那些调用。埋点决定了你事后能查到什么，是最难改的一层 |
| 侵入性 | 装上埋点要改多少东西。从「每个调用点加两行」到「一行代码都不动」是一条连续的谱系，02 篇专门讲它 |
| Collector | OpenTelemetry 的数据管道进程。收 → 处理 → 转发，归一、脱敏、采样都发生在这里 |
| 成本归因 | 把每一次模型调用的花费算到具体 的团队、项目或用户头上。账单只有一张总的，拆开它就是 06 篇的主题 |
一、这一层要解决的五个问题
二、这一层的数据面长 什么样
上面五个问题分别落在系统的不同位置。把它们摆到同一张图上，才看得出为什么顺序不能颠倒：
图里有三条容易被忽略的约束，每一条被违反都会让整层数据失去意义：
spanmetrics必须排在尾采样前面。 它和尾采样都挂在第二层 Collector 上，顺序反了指标就变成采样后的抽样值，报表数字会随采样率漂移，而没人会想到去怀疑采样配置。- 第一层 Collector 只做哈希路由，不做任何处理。 尾采样要等一棵树的 span 齐了才能决策，同一个 trace 的 span 必须落到同一个第二层实例上。少了这一层，尾采样看到的永远是半棵树。
- 网关记账那条虚线是绕开管道的。 它不经过采样，所以是唯一能对得上供应商账单的口径。埋点算出来的成本只能当参考，06 篇会展开为什么。
图里也能看出①为什么是天花板：管道能改字段名、能脱敏、能补采样，但产生侧没埋的东西，后面任何一层都变不出来。
三、七篇正文
| # | 标题 | 读完能回答的问题 |
|---|---|---|
| 01 | Agent 的 Trace 长什么样 | 那十八秒该拆成哪几段？每段记哪些字段？最 少埋几个点就够用了 |
| 02 | 埋点的四种做法 | 要改多少业务代码？从「每个调用点加两行」到「一行都不改」有四档，各自会在什么情况下悄悄不工作 |
| 03 | eBPF 旁路采集 | 真能一行代码不改就把数据抓出来吗？它是怎么在加密之前截到明文的，又有哪四件事它永远做不到 |
| 04 | 语义约定与内容治理 | 字段该叫什么名字才能被各家工具读懂？用户的原始对话到底要不要存下来，存了之后手机号怎么办 |
| 05 | 采样与数据管道 | 数据量大到存不起怎么办？为什么「只留出错的那些」这个想法在 Agent 上会失效，存储费用怎么估 |
| 06 | 成本归因 | 一张总账单怎么拆到部门和项目？为什么算出来的数总和供应商对不上，该以哪个为准 |
| 07 | 平台选型与落地 | 自建还是买？五个开源平台各自要拖多少组件、协议能不能商用，以及先做哪一步 |
只读两篇的话：02 篇（埋点做法）和 06 篇（成本归因）。前者决定你能看到什么，后者决定账能不能拆开。
四、两个需要先知道的前提
4.1 规范尚未稳定，且 2026 年搬过家
截至 2026-08-21，model/gen-ai/registry.yaml 里 118 个 gen_ai.* 属性，stability 全部是 development，标记为 stable 的一个都没有。changelog.d/ 目录下带 .breaking.md 后缀的条目有六个。
它在 2026 年还搬过一次家：v1.42.0（2026-06-12）把全部 gen_ai.* 从 semantic-conventions 主仓库拆出，成立独立的 semantic-conventions-genai 仓库（创建于 2026-05-05）。写脚本从规范仓库取数的人要注意这个断点。
应对方式在 04 篇 —— 简短版本是：不要在业务代码里选边，把归一做在 Collector 配置里。
4.2 埋点生态正在向 OTel 官方收拢
2026 年出现了两个新的官方仓库，它们的存在改变了选型判断：
| 仓库 | 建仓时间 | 作用 |
|---|---|---|
open-telemetry/semantic-conventions-genai | 2026-05-05 | gen_ai.* 的唯一定义源 |
open-telemetry/opentelemetry-python-genai | 2026-05-12 | 官方 GenAI 埋点库的新家，opentelemetry-python-contrib 里的对应包正在往这里迁 |
两者的 star 数都不高（267 / 31），但这类基础设施仓库不能用 star 判断重要性 —— 使用者 star 的是 SDK 和平台，不是上游。
五、本专题拆解的对象
下面每一行的许可证都是打开仓库里的许可证文件读出来的，不是照抄首页标签 —— 后面会看到几处两者对不上，其中一处直接决定你能不能把它做成对外服务。
5.1 两份规范
| 仓库 | ★ | 出身 | 角色 |
|---|---|---|---|
open-telemetry/semantic-conventions-genai | 267 | OpenTelemetry 官方 | gen_ai.* 命名空间的定义者，含 18 种操作、118 个属性、一份 1,332 行的 MCP 约定 |
Arize-ai/openinference | 1,159 | Arize（Phoenix 的开发方） | llm.* document.* embedding.* 命名空间。把评测与检索质量当成追踪的一等公民，但没有 MCP 约定 |
逐条对比在 04 篇。
5.2 三类埋点方案
| 项目 | ★ | 许可证 | 类型 |
|---|---|---|---|
Arize-ai/openinference | 1,159 | Apache-2.0 | 库内自动埋点，37 个 Python instrumentor，Agent 框架覆盖最全 |
traceloop/openllmetry | 7,387 | Apache-2.0 | 库内自动埋点，32 个包，向量库覆盖最全 |
open-telemetry/opentelemetry-python-genai | 31 | Apache-2.0 | OTel 官方，12 个 instrumentor |
open-telemetry/opentelemetry-operator | 1,747 | Apache-2.0 | K8s 侧零代码注入 |
open-telemetry/opentelemetry-ebpf-instrumentation | 542 | Apache-2.0 | eBPF 旁路，Beyla 的继任者，已支持 11 类 GenAI 载荷解析 |
5.3 管道与后端
| 项目 | ★ | 许可证（实读） | 角色 |
|---|---|---|---|
open-telemetry/opentelemetry-collector-contrib | 4,868 | Apache-2.0 | 归一（genainormalizerprocessor）、脱敏（redactionprocessor）、采样（tailsamplingprocessor）都在这里 |
langfuse/langfuse | 33,466 | 核心 MIT，ee/ 商业许可 | 全功能 LLM 工程平台。2026-01-16 被 ClickHouse 收购 |
SigNoz/signoz | 31,890 | 核心 MIT，ee/ 商业许可 | 通用可观测栈，GenAI 是其中一块 |
comet-ml/opik | 21,500 | Apache-2.0 | 追踪 ＋ 评测 ＋ 护栏 |
Arize-ai/phoenix | 11,128 | Elastic License 2.0，非 OSI 开源 | 本地优先的调试与评测，单进程起步 |
BerriAI/litellm | 56,842 | 核心 MIT，enterprise/ 商业许可 | LLM 网关，成本归因最省事的口径来源 |
选型判据在 07 篇。注意 Phoenix 那一行 —— gh api 返回 NOASSERTION，实际是 ELv2，禁止作为托管服务转售。
六、与其他专题的关系
- Agent 网关： 网关是可观测数据的主要产生点，也是成本归因唯一不可伪造的口径来源
- Agent 安全：trace 库里存着完整的对话内容，而它的权限模型通常比业务数据库松得多 —— 这是同一类外泄面
- Agent 持久化执行：重放机制会让同一步在 trace 里出现多次，采样规则和存储估算都要专门处理
- EvalHub 项目沉淀：评测平台对"过程证据"的记录需求与本专题同源
← 回到 Agent Infra 板块总览