一、为什么需要端到端追踪

在复杂的 Agent 系统中，一个用户请求往往不是由一个 Skill 单独完成的。Agent 可能需要多次调用大模型进行推理，每次推理可能调用一个或多个 Skill，每个 Skill 内部可能又调用其他 Skill 或外部服务。这种多层调用形成了复杂的调用链。

当系统出现问题时，传统日志无法回答以下问题。一个慢请求到底慢在了哪里？是 Agent 推理慢了，还是某个Skill 执行慢了，还是网络传输慢了？一个失败请求的根因是什么？是 Agent 决策错误调用了错误的 Skill，还是Skill 内部出错了，还是下游服务超时了？调用之间的因果关系是什么？哪个调用触发了哪个调用？多个请求之间是否相互影响？

端到端追踪正是为了解决这些问题而设计。通过在请求的整个生命周期中传递一个唯一的追踪标识符，我们可以将所有相关的日志、指标、事件关联起来，还原完整的调用链。本章将探讨 MCP 体系中端到端追踪的实现，包括追踪标识符的传递、调用链的可视化与分析、以及基于调用链的瓶颈定位。

二、分布式追踪的核心概念

在深入 MCP 的实现之前，需要先理解分布式追踪的几个核心概念。

Trace 代表一个完整的用户请求从开始到结束的全部处理过程。一个 Trace 由多个 Span 组成，可以想象为一棵树。Span 代表 Trace 中的一个操作单元，例如一次 Agent 推理、一次 Skill 调用、一次数据库查询。每个 Span 有开始时间、结束时间、操作名称、状态、标签、日志等属性。Trace ID 是整个 Trace 的唯一标识符，在整个调用链中保持不变。Span ID 是当前 Span 的唯一标识符。Parent Span ID 是父 Span 的标识符，用于构建调用树。

这些概念在 OpenTelemetry、Jaeger、Zipkin 等分布式追踪系统中是通用的。MCP 的追踪设计与之兼容，可以无缝集成到现有的可观测性基础设施中。

三、MCP 体系中的追踪标识符传递

在 MCP 体系中，追踪标识符需要通过多个组件和多个协议层传递。

从用户请求到 Agent

追踪的起点通常是用户请求。如果用户请求已经携带了追踪头信息，Agent 应该提取并复用。如果没有，Agent 创建一个新的 Trace ID。Agent 将这个 Trace ID 保存在当前会话的 Context 中。

从 Agent 到 MCP 网关

当 Agent 构造 MCP Action 时，它将当前 Trace ID 和 Span ID 放入 Action 的 Context 字段中。具体来说，Context 中可以包含一个 tracing 对象，其中包含 trace_id、parent_span_id、sampled 标志等信息。

Peta 的 MCP 客户端 SDK 会自动完成这个注入过程。开发者不需要手动操作。

从 MCP 网关到 Skill

MCP 网关收到 Action 后，从 Context 中提取追踪信息。网关在评估策略、记录审计日志时，会将自己的操作作为子 Span 附加到调用链上。当网关转发 Action 到 Skill 时，它会将追踪信息放入请求头或 Action Context 中，传递给 Skill。

从 Skill 到下游服务

Skill 收到请求后，同样提取追踪信息。Skill 在执行自己的逻辑时，可以创建子 Span 记录内部操作。如果 Skill 需要调用下游服务（如数据库、第三方 API），它会将追踪信息传递给下游服务。下游服务需要支持标准的追踪头格式，如 W3C Trace Context。

响应路径的追踪

调用链的构建不仅需要请求方向的信息，还需要响应方向的信息。每个 Span 应该记录结束时间和状态。Skill 在返回 ActionResult 时，可以将执行过程中的 Span 信息通过响应头或 Context 返回。网关将这些信息合并到审计日志中。

四、Peta 的追踪实现

Peta 内置了完整的分布式追踪支持，与主流追踪系统兼容。

追踪采样

在大量请求中为每个请求都记录完整追踪是不现实的，因为存储和性能开销太大。Peta 支持多种采样策略。头部采样，根据请求头决定是否采样，用于调试特定请求。概率采样，以固定概率（如百分之一）随机采样。速率限制采样，每秒最多采样 N 个请求。自适应采样，根据系统负载动态调整采样率。

追踪存储

Peta 将追踪数据与审计日志关联存储。每个审计日志记录包含对应的 Trace ID 和 Span ID。这样可以通过审计日志查询追踪信息，也可以通过追踪信息查询审计日志。追踪数据本身可以存储在专用的追踪后端，如Jaeger、Tempo、Zipkin。

与 OpenTelemetry 集成

Peta 原生支持 OpenTelemetry 标准。Agent 和 Skill 可以使用 OpenTelemetry SDK 生成追踪数据，Peta 网关会自动识别和传递。Peta 可以配置将追踪数据导出到任何兼容 OpenTelemetry 的后端。

五、调用链的可视化与分析

有了追踪数据，还需要工具来可视化和分析。

调用链视图

典型的调用链视图是一棵倒置的树，根节点是用户请求，向下展开为各个 Span。每个 Span 显示操作名称、耗时、状态。可以通过颜色区分不同类型的操作，例如蓝色表示 Agent 推理，绿色表示 Skill 调用，黄色表示策略评估，红色表示错误。

Peta 集成了 Jaeger UI，可以直接查看调用链。管理员从审计日志中点击 Trace ID 即可跳转到对应的调用链视图。

火焰图和甘特图

火焰图按时间顺序展示 Span 的堆叠，适合分析调用深度和并行关系。甘特图按时间轴展示 Span 的起止时间，适合分析每个操作的耗时分布。Peta 支持这两种可视化方式。

聚合分析

除了单条调用链的分析，还需要对大量调用链进行聚合分析。常见的聚合查询包括最慢调用链，找出耗时最长的请求，分析瓶颈。错误调用链，找出失败的请求，分析根因。高频率模式，找出最常见的调用模式，优化性能。异常模式，找出偏离正常模式的调用链，发现潜在问题。

六、基于调用链的瓶颈定位

端到端追踪最重要的价值之一是帮助定位性能瓶颈。

识别慢 Span

在一条慢调用链中，首先找出耗时最长的 Span。这个 Span 就是主要的瓶颈点。如果耗时分布在多个 Span 中，需要进一步分析。

区分串行和并行

检查 Span 之间的时间关系。如果子 Span 串行执行，总耗时是各子 Span 耗时之和。如果子 Span 并行执行，总耗时是耗时最长的子 Span。通过分析可以判断是否有优化空间。

识别等待时间

Span 的耗时可能包含实际工作时间和等待时间。等待时间可能来自锁竞争、I/O 等待、下游服务延迟。通过分析 Span 的日志和事件，可以区分工作时间和等待时间。

Peta 的瓶颈分析工具

Peta 提供了自动瓶颈分析功能。对于一条调用链，系统自动识别耗时最长的 Span。系统可以推荐优化方向，例如将串行改为并行、增加缓存、调整超时设置。

七、典型场景示例

场景一：慢查询诊断

用户反馈订单查询很慢。管理员在审计日志中找到该请求，点击 Trace ID 查看调用链。调用链显示，Agent 推理耗时 50 毫秒，调用 query_order Skill 耗时 2 秒。进一步查看 query_order Span，发现其中 1.8 秒花在了数据库查询上。继续查看数据库 Span，发现执行的 SQL 没有使用索引。DBA 添加索引后，查询时间降到 50 毫秒。

场景二：错误根因分析

用户报告订单取消失败。管理员查看调用链，发现 Agent 正确调用了 cancel_order Skill，但 Skill 返回了错误。进入 Skill 的内部 Span，发现 Skill 调用了库存服务。库存服务返回了 500 错误。进一步分析发现，库存服务的证书当天过期。运维团队更新证书后问题解决。

场景三：调用链过长的优化

一个用户请求触发了 20 次 Skill 调用，总耗时 15 秒。分析调用链发现，Agent 在循环中重复调用了同一个只读Skill 20 次，每次传入不同的参数。优化方案是：修改 Skill 支持批量查询，一次调用传入 20 个订单 ID。优化后，调用次数从 20 次减少到 1 次，总耗时从 15 秒降到 500 毫秒。

八、追踪的开销与权衡

分布式追踪不是没有代价的。生成、传递、存储追踪数据都会消耗资源。

性能开销

生成 Span 需要获取时间戳、记录属性、序列化数据，通常每次操作增加几十微秒到几百微秒的开销。传递追踪头增加了网络包的大小，通常很小。存储追踪数据的开销取决于采样率。

对于大多数场景，追踪开销可以接受。对于超高性能要求场景，可以降低采样率或关闭追踪。

存储开销

每个 Span 可能记录操作名称、开始时间、结束时间、属性、事件、状态等。存储开销可能显著。Peta 的追踪数据压缩存储，压缩比可达 10 到 20 倍。

隐私与安全

追踪数据可能包含敏感信息，如用户 ID、订单号、查询参数。Peta 支持对追踪数据进行脱敏。敏感字段可以被过滤或替换为哈希值。追踪数据可以单独设置保留期，通常短于审计日志。

九、小结

本章的核心结论可以总结为以下几点。

第一，端到端追踪解决了复杂 Agent 系统中无法回答慢请求定位、错误根因分析、调用因果关系等问题。

第二，分布式追踪的核心概念包括 Trace、Span、Trace ID、Span ID、Parent Span ID。

第三，MCP 体系中追踪标识符从用户请求传递到 Agent、MCP 网关、Skill、下游服务。Peta 的 SDK 自动完成注入和提取。

第四，Peta 内置分布式追踪支持，包括多种采样策略、与 OpenTelemetry 集成、与审计日志关联。

第五，调用链可视化包括调用链视图、火焰图、甘特图。聚合分析包括最慢调用链、错误调用链、高频模式、异常模式。

第六，基于调用链的瓶颈定位包括识别慢 Span、区分串行并行、识别等待时间。Peta 提供自动瓶颈分析工具。

第七，追踪有性能、存储、隐私开销，需要合理配置采样率和脱敏规则。

在下一章，我们将讨论 LangChain 与 MCP 的深度集成。