Agent 可观测性中的 Metrics、Log、Trace 及工具运行机制是什么？

核心回答

Metrics、Log 和 Trace 是从不同角度观察 Agent 执行的信号：

• Metrics 是按时间和维度聚合的测量，例如任务成功率、工具超时率、延迟分位数和 token 用量，用来发现异常发生在哪个范围。
• Log 记录具体事件和上下文，例如某次参数校验失败或重试原因，用来解释细节。
• Trace 把同一次请求中的模型、检索和工具调用串起来；每个有意义的操作用一个 Span 记录时间、状态和父子关系，用来定位耗时及失败传播。

工具并不是模型自己执行的：模型提出工具名称和参数，Agent 运行时解析并校验请求，调用注册的实现或远端服务，再把结果交回模型。观测可以通过执行包装器、回调或 Hook 记录这一过程，并把同一个追踪上下文传下去；同时控制采集开销、字段数量和敏感信息。

从一次工具超时读懂三种信号

假设“查询订单并解释物流异常”变慢了：

信号	能回答的问题	示例
Metrics	是普遍变慢还是某个工具出问题？	物流工具超时率升高、任务 p95 延迟上升
Log	这次为什么失败？	工具名、错误类型、重试次数、脱敏后的订单标识
Trace	时间耗在哪里，上下游如何关联？	模型选工具很快，物流调用占用大部分时间，随后进入降级回答

Metrics 适合趋势和告警，通常不能还原某个用户的完整经过；Log 信息丰富，但没有关联标识会在并发请求中交错；Trace 能还原路径，却不意味着所有业务事件都会自动被采集。三者通过 trace_id 等标识关联，才能从总体异常下钻到具体请求。

一次工具调用究竟怎样运行

以常见的模型驱动工具循环为例：

1. 运行时向模型提供工具描述与参数约定，模型返回结构化调用请求。
2. 运行时按工具名找到注册实现，校验参数，并检查当前身份是否允许执行。模型选择了某个工具，不等于已经获得业务权限。
3. 执行器按依赖和并发限制启动调用，应用超时、有限重试或幂等策略。
4. 取得结果或错误，形成对应的工具响应交回模型，模型继续选择工具或生成最终回答。

在第 2～4 步外包一层观测逻辑，就可以在开始时建立工具 Span，成功或异常时记录耗时、状态与必要属性，并在清理路径中结束它。模型 Span 记录模型版本、调用耗时、用量等；工具 Span 则记录工具名、结果类别与尝试次数，不把两类耗时混成一个黑盒。

重试可以在一个逻辑工具操作下面建立各次尝试的子 Span，保留尝试编号；业务请求标识用于关联同一意图，尝试标识用于区分实际执行。异步任务、线程池或跨服务调用需要显式检查上下文传播，不能假设换一个执行线程后仍自动保留父子关系。

Trace 表达调用的因果与时间关系，不等同于完整的数据依赖图。并行任务的耗时也不能简单相加为总延迟，排查要看重叠区间和关键路径。

信号怎样进入观测平台

可以由应用的包装器、框架集成或 OpenTelemetry SDK 产生信号，再处理、采样和导出到后端。网关插件能观察经过它的模型请求，但看不到所有应用内部判断、数据库写入和未经过网关的工具；这些位置需要相应埋点。

业务日志应带上 trace_id，必要时还带 span_id，后端才能按同一个标识查询。单独生成 request_id 很有助于串起本服务日志，但跨服务追踪还要约定传播方式，并建立子操作关系，不能把一个普通字符串等同于完整分布式追踪。

常见观测项包括任务完成率、工具成功率与超时率、端到端及模型/工具延迟、首 token 延迟、token 用量和重试次数。统计前要定义分母：模型正常返回并不代表任务已经完成，HTTP 200 也可能携带业务拒绝或错误结果。

既要看得见，也要控制代价

• 标签数量：Metrics 使用工具名、模型版本、状态类别等受控维度。用户编号、会话编号和文档编号容易形成高基数序列，通常放在受权限控制的日志或追踪属性中，而不是直接做指标标签。
• 内容最小化：不默认保存全部提示词、工具参数和输出；使用字段白名单、脱敏、长度限制与访问控制，不记录密钥。需要原文排障时单独约定范围和保留期限。
• 采样与丢失：完整保留所有请求可能成本过高。可以按预算采样并优先保留错误、慢请求，但头部采样在请求开始时还不知道最终结果；尾部采样能结合结果判断，也需要额外缓存和处理。
• 埋点开销：异步批量导出可以减少前台等待，仍存在序列化、内存队列和网络成本。要观察队列溢出、导出失败，避免观测故障反过来拖垮主流程。

观测能解释“系统做了什么、在哪里出错”，不会自动证明答案正确。质量还需任务评测、人工校准或规则校验；涉及关键业务操作的审计记录，也不能只依赖可能被采样丢弃的调试 Trace。

对应教程

参考资料