Trace 与 Span（追踪与跨度）
追踪一次请求完整链路的两个基本单位：trace 是一条链路，span 是链路中的一个环节。
生产方式：人写签发：晓黎学习复核：2026年9月21日被 0 个词条引用
一句话定义
Trace = 一次完整请求的调用链路；Span = 链路中的一个环节，记录该环节的起止时间、属性与状态。
结构关系
trace: 一次 Agent Run
├── span: turn/1
│ ├── span: prompt-assembly 12 ms
│ ├── span: llm-request 840 ms
│ └── span: tool/call read_file 45 ms
└── span: turn/2
├── span: llm-request 620 ms
├── span: tool/call edit_file 30 ms
└── span: approval-request 12000 ms ← 瓶颈在这里
每个 span 通过 parentSpanId 构成树形结构。
为什么 Agent 系统特别需要它
Agent 的一次任务是多环节、多层的：Run → Turn → Step → Tool Call。只看总量指标无法定位问题。
| 只看指标 | 加上追踪 |
|---|---|
| 平均延迟 15 秒 | 其中 12 秒花在审批等待 |
| 失败率 8% | 集中在某类工具的某个参数错误 |
| 成本上升 30% | 某个环节的模型调用次数异常 |
关键字段
| 字段 | 作用 |
|---|---|
traceId | 关联同一请求的所有 span |
spanId / parentSpanId | 构成层级 |
| startTime / endTime | 计算耗时 |
| attributes | 关键标识（工具名、模型名、token 数） |
| status | ok / error |
设计要点
- 采样策略：全量记录成本高。常见做法是保留错误 trace 的全量数据，成功的按比例采样。
- 属性规范化：attributes 只放可聚合的标识，不放长文本。
- 跨进程传播：子 Agent 在别的进程或机器上时，traceId 需要显式传递。
- 与日志配合：追踪定位「慢在哪里」，日志回答「为什么慢」。
与日志、指标的区别
| 维度 | 日志 | 指标 | 追踪 |
|---|---|---|---|
| 粒度 | 单条事件 | 聚合数值 | 单次链路 |
| 回答 | 发生了什么 | 有多少 | 慢在哪里 |
| 存储成本 | 高 | 低 | 中 |
三者互补，缺一不可。
相关
- OpenTelemetry（OTel） — 追踪的标准实现与传输协议
- 第 17 讲 可观测性
- LogQL — 日志查询语言，与追踪配合定位问题
互链
链接来自概念卡正文里的双链，编译时能解到本期词条集的才成为站内链接。
- LogQL相关概念
- OpenTelemetry（OTel）相关概念
反链（0）
还没有其它词条引用这一页。
出现在哪些课时里（0）
判据与「课时正文里能不能点出来」是同一个：那一节确实提到了它。点课时走当前页跳转， 它是导航，不是词条链接。
还没有课时讲到这一条。它是词条跑在课程前面的那一部分，不是错链。
关联图
只画这一条与它直接相连的词条，边与上面两区同源。可拖拽、可缩放，点节点是新标签。
以列表方式看这 3 个节点
出处
路径是本地知识库（Obsidian 库）里的位置，正文与概念卡逐字对应。
- 概念卡原文Trace 与 Span（追踪与跨度）
03_RESOURCES/概念/tracing-span.md - 所属知识地图栏目概念页索引 · 可观测性与可靠性
03_RESOURCES/概念/Index.md - 正文引用的知识库笔记第 17 讲 可观测性
02_AREAS/AI开发/Harness Engineering/Agent Harness 课程/17-可观测性：如何知道系统正在发生什么.md
编译入库：2026年11月2日。词条由知识库编译而来， 修正要回到概念卡改，再重新编译。