Node.js Agent可观测性：错误追踪与结构化日志分工修正

```html

一个AI Agent回答一次问题，背后可能已经调了好几轮模型和工具。中间有超时、有重试，最后却成功了。如果把每一次失败尝试都塞进错误追踪系统，告警会多到没人看；如果只留最后一次异常，又说不清这次请求为什么又慢又贵。

面向Node.js的SaaS场景，一套可落地的分工是：错误追踪只接需要人工介入的失败，结构化日志记录完整的执行过程，两者共用一个关联ID。这样查延迟和token成本时，不用把每次重试都变成一条告警。

边界看的是可操作性，不是严重程度标签

把每一次不成功的模型调用或工具调用都叫“错误”，在笔记本里看着很全面，上了生产会带来失真：预期内的重试把失败计数抬高；同一次故障被拆成多条事件；团队开始忽略那些不再代表用户受影响的告警。把同样的尝试改标成warning，也解决不了数据模型的问题。

判断的起点应该是Agent运行的最终状态。一次瞬时超时被重试后运行成功，这次尝试记进结构化日志，带上耗时和token用量就够了。如果循环因为截止时间、重试预算或输出契约无法满足而停下，就把这个终止异常捕获一次，再关联到前面那些尝试记录。这样既能回答“这次运行为什么慢、为什么消耗了多次模型调用”，又不会声称每个内部分支都值得叫人起床。

有一种情况例外：中间失败本身就构成安全事件、数据完整性风险或已突破服务等级目标时，即使后面兜底成功，也要单独建一条可操作事件。反过来，高频审计历史、逐token计费、日常延迟分析，应该留在日志里，异常分组和分诊流程并不适合干这些活。

重试阈值没有通用答案。合适的失败预算取决于你的用户，日志库和错误追踪工具都决定不了。可行的办法是用一套覆盖真实工具组合的评测集去试，找到“再多试几次也不再明显提升任务成功率”的那个点。

事件契约要小到代码能一致地发出来

错误对象不该直接变成schema。在边界处做归一化：稳定的错误类型、安全的message、适当保留的stack、操作名和各类ID。OWASP的日志指引建议排除或掩码访问令牌、密码、敏感个人数据等机密信息。对AI应用尤其要小心，prompt和工具参数里可能夹着本不该进可观测性存储的用户文本。导出之前先脱敏。

Node.js的AsyncLocalStorage可以把请求级上下文带过异步操作。在入口初始化上下文，存在标准trace上下文时复制过来，队列消息里显式传递所需标识符。外部传入的关联值要当作不可信输入：校验格式、限制长度，必要时生成新的内部值。日志器和异常适配器应该读同一份上下文，而不是在每个调用点各自拼ID字段。

结构化日志的字段建议保持一致，例如event_name、correlation_id、trace_id、agent_run_id、attempt、duration_ms、input_tokens、output_tokens、outcome、error_type。重试通常是日志事件，撑过重试预算的异常才是错误追踪事件。

关联ID是跨HTTP处理、Agent运行器、队列任务和两个目的地之间的连接键。如果已经有分布式追踪，W3C的traceparent格式提供了标准trace上下文，别再另造一套无关的身份标识，指望凌晨两点有人手动对上。像agent_run_id这样的业务标识仍然有用，因为一次逻辑运行可能跨越多个传输层操作。关联ID连接记录，但它替代不了trace里的时序和父子关系。

改告警策略之前，先评估信号质量

从笔记本走向生产，第一步应该是导出脱敏后的事件并做评测，而不是先加一条告警规则。评测要回答：终止失败有没有被捕获，成功的重试有没有漏进分诊队列，日志里的运行是否保留了足够的成本和延迟字段。用有标注的评测用例放进持续集成里跑，部署后再和生产聚合数据对比。

值得盯的指标包括：终止失败捕获覆盖率、每次运行的重复异常事件数、被送进分诊的成功重试数、关联覆盖率、测量字段覆盖率。延迟和token分布要按操作和结果分开看，一个平均值会把慢重试路径藏起来。

成本分析需要成功和失败尝试都带用量字段，错误追踪则需要足够上下文定位到具体运行。把完整prompt同时灌进两个系统，增加的是暴露面和存储量，诊断效果未必更好。prompt模板版本、模型标识、token计数、工具名和脱敏哈希，往往已经能回答运维问题。

还要测基数和保留策略。用户ID、原始URL、prompt文本、任意异常消息都不适合做聚合维度，还可能带敏感数据。稳定的操作名和有界的错误类型更好推理。重复的成功日志可以采样，但要保留诚实估算延迟和token用量所需的字段，安全相关记录另定策略。

在评测回答两个问题之前，别急着照搬这套目的地划分：一条错误追踪事件是否可靠地意味着有人能行动，关联的日志能否在不暴露敏感内容的前提下还原出昂贵的那条路径。任何一个答案是否，先调事件契约和重试边界，工具选型放到后面。