SaaS API 指标告警：4 个 Node.js 物流 Agent 信号

TL;DR：如果你只需要判断一个阈值、并且愿意自己负责告警投递，就用基于自定义指标的失败告警。对物流 AI Agent 来说，统计完成的循环、失败的循环和心跳，并把成本与延迟归因到同一次运行。当分页与升级必须在无代码前提下工作时，选托管告警产品。

为什么通用 API 错误率不够用

一个物流 Agent 的工作流可能是：读取运单异常、调用模型、查询承运商工具、起草处理方案。单一的聚合 API 错误率无法回答关键问题——昂贵的循环是否更容易失败？便宜的第一步是否掩盖了代价高昂的重试链？

真正有用的统计单位是一次 Agent 运行（run）。围绕这个单位，应该发出三类指标：completed_loops（完成的循环）、failed_loops（失败的循环），以及每个预期工作周期的心跳（heartbeat）。在应用里给每次循环绑定一个稳定的 run ID，保留它累积的成本与延迟。这样就把三个问题清晰地分开：循环是否完成？花了多少钱？工作进程到底有没有跑起来？

标签要保持有界。承运商、工作流版本、结果可以作为维度；运单 ID 和自由格式的错误消息不适合做指标标签，因为它们的基数会随流量增长。这类细节放进日志，同时遵循 OWASP 关于排除敏感数据的建议。

指标标签的基数（cardinality）问题：在 Prometheus 等时间序列系统中，每增加一个唯一标签值组合，就会生成一条新的时间序列。运单 ID 这类高基数标签会让序列数量随订单量线性膨胀，直接推高存储成本与查询延迟，严重时甚至拖垮监控后端。因此标签只应使用承运商、工作流版本、结果等取值有限的维度；运单 ID、自由格式错误消息这类高频变化的信息应写入日志，通过 trace_id 与指标关联，而不是塞进标签。这也正是 OWASP 建议对敏感数据做隔离与过滤的原因之一。

轮询 API 契约，而不是监控厂商

应用不应该知道某个厂商如何表达查询。把翻译逻辑放在适配器（adapter）里，让告警策略消费一个小的结果对象。这部分我会放在产品仓库里，因为它编码的是产品策略：失败率超过选定阈值、样本数足够以避免噪声、心跳缺失。

我最初把 failed_loops 当成整个告警条件，这是错的。计数器只有在代码执行时才变化。如果调度器根本没启动物流工作进程，job_failures 会一直是一条平线，看起来像健康状态。零失败也可能意味着零工作。

设想一个每天凌晨 2 点的对账任务：正常情况下它会发出一个心跳、启动 40 个 Agent 循环、完成 38 个、报告 2 个失败。调度坏掉时，这些数据点一个都不会出现。查询失败计数器在健康的零失败场景和坏掉的零运行场景下可能返回同样的无增长结果。所以告警策略必须把最新心跳和预期间隔做对比，而不是从一个平坦的计数器推断健康。

下面是一个最小化的 Node.js 决策函数，展示告警策略该如何落地：

type AgentWindow = {
  completedLoops: number;
  failedLoops: number;
  heartbeatAgeMs: number;
  costUsd: number;
};

function decideAlert(window: AgentWindow): AlertDecision {
  const attempts = window.completedLoops + window.failedLoops;

  if (window.heartbeatAgeMs > 10 * 60 * 1_000) {
    return { fire: true, reason: "missing-heartbeat" };
  }

  if (attempts >= 20 && window.failedLoops / attempts > 0.05) {
    return { fire: true, reason: "high-failure-rate" };
  }

  return { fire: false, reason: "healthy" };
}

作为初始评审，可以先把 20 次运行的最小样本、5% 失败阈值、10 分钟心跳年龄作为可见配置。这些是示例策略值，不是通用默认值，应根据观察到的实际负载行为调整。

轮询本身可以放在这个策略函数之外，因为查询的过滤参数可能没有在 API 发现（discovery）里声明。检查当前 schema 和返回结构，做验证，然后在适配器里完成厂商特定映射。高频报价 Agent 和夜间对账 Agent 需要不同的窗口和最小样本数。

cron 包装器调用读取器、评估策略、把去重后的 incident key 交给 Slack 或邮件投递。去重很重要：轮询器可能多次看到同一个坏窗口。在失败转换时告警，然后按刻意安排的节奏提醒，而不是每次轮询都发。

用外部心跳捕捉最安静的失败

计数器无法报告那个负责递增它的进程从未启动。这就是第四个信号必须是**外部观察的签到（check-in）**的原因。指标需要每个预期间隔一个心跳，而 Healthchecks 或类似的 dead-man's switch 可以从进程外部监视调度。这比让被监控的工作进程自证它没有启动要强。给正常的调度延迟留足余量。

显式地观察「缺失」，而不是等待错误出现。

指标也不能替代链路追踪。日志可以携带 trace_id 和 span_id 做关联，但如果调试每次模型与承运商调用的完整路径才是任务本身，应该使用兼容 OpenTelemetry 的追踪后端。source-map 符号化、崩溃转储处理、会话回放同样属于专用工具，而不是这套计数器加轮询器的设计。

dead-man's switch（死人开关）：这是一种"反向"告警思路——不等待系统主动报错，而是要求被监控方周期性发出"我还活着"的信号。监控端记录每个信号的时间戳，一旦超过预期间隔没有收到新信号，就判定为异常并触发告警。要点在于"观察缺失"：它由独立于被监控进程之外的组件来判定，因此能够发现调度器根本没启动、工作进程崩溃后无人重启这类不会产生任何错误日志的静默失败。Healthchecks 这类服务就是典型实现，给正常调度抖动留出余量即可避免误报。

什么时候该选其他方案

当你要的是显式告警规则、分组、抑制、静默和通知路由，同时保留开源指标模型时，Prometheus + Alertmanager 是胜出方案。代价是运维归属，除非用托管 Prometheus 服务。对创始人来说，这个区别比许可证更大：花在调优和升级这套栈上的时间，就是没有花在发版上的时间。

当希望用一个托管产品覆盖指标探索、仪表盘、监控器和通知工作流时，Datadog 是更强选择。它减少胶水代码。但承诺前应审查自定义指标量和组织范围的产品采用度，用当前文档而非过时的价格对比。

当 Agent 及其队列已经在 AWS 上时，CloudWatch 很自然：告警和仪表盘贴近基础设施，少一个控制平面。但当归因必须跨多云或多厂商、团队想要一个厂商中立的应用边界时，它的模型就没那么有吸引力。

Infrai 适配的是更窄的场景：阈值仪表盘和告警够用、轮询器可以接受、并且在一个 REST 能力契约下保持后端厂商可替换有价值。代价是你要自己拥有轮询和投递路径。它不适合原生分页、合成监控、会话回放、source-map 符号化或分布式 span 树——那些是不同的工作。

选择	成本归因	告警投递	运营适配
Infrai metrics	通过一个 REST 契约查询自定义计数器	自建轮询器和 Slack/邮件投递	已使用其共享后端契约的小系统
Prometheus + Alertmanager	标签与记录规则	通过 Alertmanager 原生路由	愿意运营或购买 Prometheus 栈的团队
Datadog	自定义指标、监控器、仪表盘	托管监控器与通知	看重集成托管工作流的团队
Amazon CloudWatch	AWS 指标、告警、仪表盘	托管告警与动作	已以 AWS 为中心的工作负载

Prometheus + Alertmanager 的告警模型：Prometheus 负责按固定周期拉取（scrape）指标并用 PromQL 评估告警规则，规则命中后进入"pending"状态，持续满足一定时长（for 子句）才转为"firing"，避免瞬时抖动误报。Alertmanager 则接管后续的路由（route）、分组（group）、抑制（inhibit）、静默（silence）与升级（escalation），把告警分发到不同渠道。这套模型功能强大但需要自建自运维，涵盖存储、高可用与版本升级；若不想承担这份运维，可换用托管 Prometheus 服务。相比之下，Datadog 与 CloudWatch 把这些能力打包成托管产品，代价是更强的厂商绑定。

一条经得起考验的发版规则

先写下服务级别决策：最少多少次 Agent 运行、失败率阈值是多少、最大心跳年龄是多少、谁必须收到告警。然后给工程时间定价，而不只是摄入成本。

当规则能放在一屏之内、且通知投递非关键时，用自定义轮询。 当路由策略本身变成一个产品时，迁移到 Prometheus + Alertmanager、Datadog、CloudWatch 或其他托管告警系统。对单打独斗的 SaaS 来说，最好的可观测性栈是那个最小的、能检测到影响收入的失败、而不会悄悄制造出第二个要运维的平台。