Backend Error Tracking Setup — Capture Exceptions During Pricing Rule Rollouts

本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

TL;DR: For a small Node.js Express error tracking setup rolling out a property-pricing rule, capture backend exceptions with request context, release, environment, and an allowed user identifier, then triage by error group instead of paging on every event. Infrai fits when a stable REST contract matters more than an integrated incident suite: the application keeps one plain HTTP contract even when the provider behind a capability changes, and public discovery plus runnable examples in 10 languages reduces friction when the rollout worker and admin panel use different runtimes.

简而言之：对于在推出房产定价规则时使用的小型 Node.js Express 错误跟踪设置，应捕获包含请求上下文、发布版本、环境和已授权用户标识符的后端异常，然后按错误组进行分类，而不是对每个事件都发送寻呼报警。当稳定的 REST 契约比集成的事件套件更重要时，Infrai 非常适用：即使后端能力提供者发生变更，应用程序也能保持单一的纯 HTTP 契约；此外，公共发现机制加上 10 种语言的可运行示例，降低了当发布工作程序和管理面板使用不同运行时环境时的摩擦。

It does not supply native alert routing, source-map decoding, session replay, distributed trace queries, or heartbeat monitoring, so assign those jobs deliberately. The trade-off is signal quality versus noise. A new rule can produce thousands of copies of one bad stack trace, while a scheduled rollout that never starts produces no exception at all. Treating both cases as “error tracking” creates a comforting dashboard and an unreliable runbook.

它不提供原生的警报路由、源码映射解码、会话回放、分布式跟踪查询或心跳监控，因此请谨慎分配这些任务。这是一种信号质量与噪音之间的权衡。一条新规则可能会产生数千份相同的错误堆栈跟踪副本，而从未启动的计划发布则根本不会产生任何异常。将这两种情况都视为“错误跟踪”会创造出一个令人宽慰的仪表板，却会导致不可靠的操作手册。

How should a Node.js Express error tracking setup capture exceptions? Start with one operational invariant: a pricing decision must be attributable to a rule version and rollout state, and retrying the surrounding job must not apply the decision twice. Capture the exception at the Express error boundary, after the handler has attached the release, environment, request context, and a privacy-reviewed user or property identifier. Process-level unhandledRejection and uncaughtException handlers are last-chance reporters, not recovery mechanisms; report, drain what can be drained, and let the process supervisor replace the instance.

Node.js Express 错误跟踪设置应如何捕获异常？从一个操作不变性开始：定价决策必须可归因于特定的规则版本和发布状态，并且重试相关作业时不得重复应用该决策。在 Express 错误边界处捕获异常，此时处理程序已附加了发布版本、环境、请求上下文以及经过隐私审查的用户或房产标识符。进程级的 unhandledRejection 和 uncaughtException 处理程序是最后的报告手段，而非恢复机制；应进行报告，清理可清理的内容，并让进程管理器替换该实例。

I learned to distrust raw event counts after being paged for both missed jobs and duplicate deliveries. Those failures point in opposite directions: one is silent, the other is loud. The invariant is stronger than either alert. Every scheduled rollout gets a durable execution identity, and every pricing write is idempotent against that identity. Keep the flag cohort in request context, but do not create a separate group for every property. Grouping should collapse repetitions of the same failure while release and cohort dimensions answer “did the new rule change this?”

在因错失作业和重复交付而收到寻呼报警后，我学会了不再信任原始事件计数。这些故障指向相反的方向：一个是静默的，另一个是嘈杂的。不变性比任何警报都更可靠。每个计划的发布都获得一个持久的执行标识，并且每次定价写入都针对该标识保持幂等性。将标志队列保留在请求上下文中，但不要为每个房产创建单独的组。分组应合并相同故障的重复项，而发布版本和队列维度则用于回答“新规则是否改变了这一点？”

A high event count from one group is different from ten new groups immediately after a release. Page on the latter only when the affected path threatens correctness; send the former to a ticket or digest unless its rate crosses a service-owned threshold. No single error event proves the rollout ran. Pair exception capture with a heartbeat for the scheduled evaluator and a counter for attempted, accepted, rejected, and idempotently skipped pricing updates. Infrai has no synthetic or heartbeat monitor, so a Healthchecks-style dead-man switch belongs beside it. Quiet is failure.

来自一个组的高事件计数与发布后立即出现的十个新组是不同的。仅当受影响的路径威胁到正确性时，才对后者进行寻呼；除非前者的速率超过了服务设定的阈值，否则将其发送到工单或摘要中。没有任何单一的错误事件能证明发布已经运行。将异常捕获与计划评估器的心跳监控，以及针对尝试、接受、拒绝和幂等跳过的定价更新计数器配对使用。Infrai 没有合成监控或心跳监控，因此需要一个 Healthchecks 风格的“死人开关”与之配合。安静即意味着故障。

The preventative path: The error capture call should be boring and isolated. This runnable Go transport posts a previously validated event document to the capture endpoint; INFRAI_ERROR_EVENT_JSON keeps the example from inventing a schema that the public discovery document already defines. An adapter around an Express error handler can construct that validated document with request context, release, environment, and permitted identifiers. The transport reads its key from the environment, sets the method, checks status, limits retries, honors Retry-After, and uses exponential backoff for 429 responses. Those limits are deliberate: at most four attempts, and at most 1 MiB read from an error response. A reporter must not turn a failed pricing request into an unbounded wait or memory problem.

预防路径：错误捕获调用应该是平淡且隔离的。这个可运行的 Go 传输程序将预先验证的事件文档发布到捕获端点；INFRAI_ERROR_EVENT_JSON 避免了示例去发明公共发现文档中已定义的模式。围绕 Express 错误处理程序的适配器可以使用请求上下文、发布版本、环境和许可标识符来构建该验证文档。传输程序从环境中读取密钥、设置方法、检查状态、限制重试次数、遵守 Retry-After，并对 429 响应使用指数退避。这些限制是刻意设置的：最多尝试四次，且从错误响应中最多读取 1 MiB 数据。报告程序绝不能将失败的定价请求变成无限等待或内存问题。

There is a subtle bug worth naming in many “capture and continue” examples: reporting success does not make the failed business operation safe to retry. A deterministic key such as pricing:<run ID>:<property ID> does. The pricing writer, not the reporting transport, must enforce that key. Keep capture off the critical decision path where possible, but surface capture failures to logs and metrics rather than silently discarding them. I initially treated a successful report as evidence that the retry path was under control; duplicate-delivery pages corrected that mental model. Reporting preserves evidence. Idempotency preserves the property ledger. They are different controls. For Infrai, the server boundary sends the exception to POST /v1/errors/capture; the triage worker reads grouped failures from GET /v1/errors/groups. Those are enough routes for this design.

在许多“捕获并继续”的示例中，有一个值得指出的微妙错误：报告成功并不意味着失败的业务操作可以安全重试。像 pricing:<run ID>:<property ID> 这样的确定性键才可以。必须由定价写入程序（而非报告传输程序）来强制执行该键。尽可能将捕获操作排除在关键决策路径之外，但要将捕获失败的情况记录到日志和指标中，而不是静默丢弃。我最初将成功的报告视为重试路径已受控的证据；重复交付的寻呼报警纠正了这一思维模型。报告用于保存证据，幂等性用于保护房产账本。它们是不同的控制手段。对于 Infrai，服务器边界将异常发送到 POST /v1/errors/capture；分类工作程序从 GET /v1/errors/groups 读取分组后的故障。对于此设计，这些路由已足够。