Appearance
如何把一次 Run 串成完整链路：Correlation、Distributed Trace 与 Redaction
前置：如何看见 Agent 在做什么：Logs、Metrics 与 Trace
核心问题：Run 跨 API、Worker、MCP 多进程后怎样仍保持一条 Trace，同时避免敏感内容随着 Trace Context 到处扩散？
审批两小时后 resume，新进程继续沿原 run_id 并创建新 span；仍能从 UI 看到前后完整链路。Tool 经 MCP Gateway 调远程服务时，traceparent 向下传播，服务端 child span 能归入原 Agent Run。
Mental Model
Correlation 解决同一次 Run 的事件怎么串起来；Distributed Trace 解决跨进程、跨服务时如何延续 trace identity；Redaction 决定哪些 payload 和 attribute 根本不应该进入观测系统。
Trace Correlation
Trace Correlation 是把应用内部 run_id、node id、tool_call_id 等业务标识关联到标准 trace id/span id，使日志、指标和领域记录能够回到同一次执行。它解决“不同数据源如何互相定位”。
Distributed Trace
Distributed Trace 是同一个因果请求跨 API、Worker、MCP/HTTP 等服务边界传播 Trace Context 后形成的完整 span 图。它依赖标准传播机制，而不是仅靠业务 run_id 字符串拼接。
需要处理异步队列和 fan-out 的 link/parent 语义。
Sensitive Data / Redaction
system instructions、retrieval query、tool definitions/input/output 可能含敏感信息。默认采最少字段并支持 redaction/采样/retention policy。
Trace 往往包含 prompt、tool args、文件路径、用户数据和 token，必须定义采集级别、字段 allow/deny list、脱敏、保留期和访问权限。Observability 不应成为秘密数据旁路。
一条 Run 怎么跨进程串起来
用户报告“r-42 卡了 40 秒”。如果 API、Queue Worker、Model Client、Tool Gateway 各有自己的日志但没有 correlation，就很难判断时间花在哪里。一个可追踪链路至少保留：
text
run_id=r-42
trace_id=t-9
API span
└─ enqueue span
Worker span
└─ model span
└─ tool span异步 Queue 场景下，producer 应把可传播的 trace/correlation metadata 放进消息；consumer 创建新的 processing span，并通过 link/parent 关系把两侧串起来。
Redaction 必须发生在 exporter/recording policy 上，而不是要求开发者“记得别打日志”。Prompt、Tool arguments、HTTP headers、credential、用户文档都可能含敏感信息；真正有用的 trace 往往保留结构化 metadata 和 hash/reference，而不是无条件保存原文。
Failure Modes
Trace 采集完整 Prompt/Tool Payload 泄露敏感信息
症状： 默认记录用户输入、secret、PII 与 Tool 原始返回。
为什么危险： Observability backend 变成高权限数据副本。
处理： 默认最小采集，对敏感字段 redaction/hash/reference，payload 采样需显式策略。
如何验证
| Case | 断言 |
|---|---|
| Trace 采集完整 Prompt/Tool Payload 泄露敏感信息 | 注入 secret/PII，exporter 输出不存在原文且保留可诊断 metadata。 |
自测
- 同一个 Run 跨 API、Queue、Worker、Tool。哪些 correlation id 需要贯穿，才能把异步链路重新串起来？
- Trace attribute 中含 prompt 和 token，怎样决定哪些字段保留、hash、redact 或完全不采集？