integration-error-observability

集成错误可观测性

你正在设计一套可见性界面和通知机制，让外部开发者无需提交支持工单，就能了解自己的集成出了什么问题。交付内容包括：范围限定为单个集成方的日志和仪表板、可用于支持排查的关联标识符、按集成聚合错误，以及平台主动联系集成方的规则。

问题的核心在于双方掌握的信息不对称。合作伙伴的集成发生故障时，平台通常先发现问题，掌握的信息也更多——平台保留了请求、状态码、投递尝试和时间戳；合作伙伴手里却只有一个静默的队列和一位愤怒的客户。以下每项设计决策，要么缩小这一差距，要么让合作伙伴只能从外部逆向分析你的平台。

记忆（建议）： 如果记忆存储在文件中，可以考虑使用 developer-platform-context.md；如果使用其他记忆系统，则依赖该系统即可。此文件仅供参考，并非强制要求。请将不同任务的信息放在不同章节中。任务完成后将其移除。为任务添加日期；一般项目背景则无需添加日期。不同任务的部分访谈回答可能有所不同。

澄清问题

开始设计前先询问以下问题。每个回答都会影响后续的优先级排序。将问题打包询问——这是一个战术设计任务，而非战略访谈。

1. 集成方目前无需联系你，就能看到什么？如果存在任何可见界面，请提供 URL。“什么也看不到”是合理且常见的回答。
2. 哪类人会遇到问题：为自己使用而集成的单个客户的工程师、应用运行在大量安装实例上的商业合作伙伴、无代码工具和 Agent 构建者，还是以上几类都有？（见下一节）
3. 对最近 20 个集成支持工单进行分类：找不到请求、Webhook 从未送达、数据不匹配但没有提示、身份验证或凭证失败、对速率限制感到困惑。这批工单的分布决定了应先构建哪种可见界面。
4. 每个入站请求在接收时是否都已标记集成身份——API 密钥、应用 ID 或客户端 ID？聚合粒度始终取决于作为键的标记粒度。
5. 是否使用 Webhook，投递机制是否已记录每次尝试的结果？（这决定了第 2 步的默认级别）
6. 集成发生故障时，合作伙伴会在几小时内蒙受经济损失，还是要到下次对账时才会发现？（这决定了第 5 步的通知策略）
7. 法律允许你展示哪些内容？请求和响应正文是否包含个人身份信息、密钥或属于其他租户的数据？谁负责批准向第三方公开这些内容？
8. 截止日期、收益形态和投入上限分别是什么：必须在何时上线？这是糟糕的支持季度之后的一次性修复，还是要持续多年运行、不断产生收益的平台界面？你能投入多少——工程师周数、日志存储空间，以及负责响应你开始发送的告警的值班轮班？

问题 8 很重要，因为以下各项选择在投入和收益持续时间上差异很大。紧迫的截止日期会优先考虑那些已经记录、只需公开的内容；而要打造长期产生复利的平台界面，则会优先考虑需要新增存储、新状态或新外发渠道的级别。

问题 7 可能会直接排除某些级别，而不仅仅是改变排序——如果法律规定“这些正文绝不能离开你们的租户边界”，那么载荷级日志就应从选项中移除，而不是仅仅降低优先级。

如果你的执行环境具备持久记忆，请保存该界面的核心决策——公开哪些日志、保留期限、聚合所使用的身份标识、告警阈值和冷却时间，以及脱敏规则——这样后续运行要添加事件类型或调整告警时，就能以既定设计为基础，而不必重新推导。

集成归属

发生故障的集成背后有多少终端用户，决定了一个仪表板是否足够：

• 单账户集成方 - 客户自己的工程师将你的 API 接入他们的系统。一个账户、一个仪表板、一组凭据。优质的自助式日志界面确实能解决他们的问题：一旦出现故障，他们就会主动查看，因为他们自己的用户已经在抱怨了。
• 拥有大量安装实例的合作伙伴和 ISV - 他们的应用运行在数十个或数千个客户账户中，每个安装实例都可能独立发生故障。按账户划分的仪表板对他们来说从结构上就毫无用处：没人会盯着一千个仪表板看，因此他们需要跨安装实例的汇总信息和推送通知；否则，他们只能从自己的客户那里得知故障。正是这一群体让第 5 步和第 6 步成为必需，而非可选项。
• 无代码和 Agent 构建者 - 他们能组装工作流，却看不懂堆栈跟踪，也不会关联分析。他们需要一个按工作流划分、使用通俗语言的故障列表，并在每条记录旁附上一句“我该怎么处理”。对另外两类人有帮助的细节，在这里却只会造成干扰。

为问题 2 中提到的每一类群体提供支持。只为第一类群体设计界面，是有记录可查的常见失败模式：平台提供日志，宣称集成可见性问题已解决，但其合作伙伴仍然要从终端用户那里得知服务中断。

工作流

1. 审查集成方目前能看到什么。
2. 展示每个集成的故障详情。
3. 确保关联 ID 能传递给支持团队。
4. 按集成身份汇总错误率。
5. 确定通知策略。
6. 构建提供商端的集成实例总览。

下面按顺序逐步介绍。

1. 审查集成方目前能看到什么

从支持工单堆积处入手（问题 3），而不是从架构图入手。对于最近 20 张集成工单，逐一回答一个问题：集成方能否通过你可以合理推出的界面自行解决这个问题？回答“能”的占比就是你的基线，也是后续每一步都要努力提升的数字。

• 分别检查每类故障：同步 API 错误、未送达的 Webhook、身份验证或凭据过期、速率限制拒绝，以及无提示的数据不匹配。平台通常会为其中一类提供界面，然后误以为其他问题也都覆盖了。
• 检查不会产生任何错误的故障：某个集成完全停止调用你的服务。错误日志无法显示缺失情况，因此流量下降信号需要单独设计，不能视为错误日志的附带效果。
• 如实记录保留期限。集成方无法回溯到事件发生时的日志，最终仍会提交支持工单。
• 记录谁有权查看。只有账户所有者才能打开的界面，会让不属于该账户的合作伙伴工程师无法使用——这是访问权限模型的缺口，而非日志记录的缺口。

将审查结果整理成一张表，列出故障类别及其当前可见性，并在下面的每一步中持续使用。缺口就是构建顺序。

2. 展示每个集成的故障详情

这里有三种不同的界面，将它们混为一谈是常见的设计错误。Stripe 的开发者仪表板是值得借鉴的设计参考，它将三者分开（来源：Stripe 文档）：

• 请求日志 - 每次 API 调用及其结果。回答“我的调用成功了吗”。
• 事件日志 - 这些调用产生的业务层事件。回答“它改变了什么”。
• Webhook 投递日志 - 每个端点的每次投递尝试及失败原因。回答“你通知我了吗”。

在黑暗中排查问题的集成方，需要查看与其故障类别相对应的日志。

以下按从最容易提供到构建成本最高的顺序列出各级方案：

• 价值（减少的支持工单）：逐请求详细日志 > 发送尝试日志 > 重放 > 仅失败次数
• 工作量：重放 > 逐请求详细日志 > 发送尝试日志 > 仅失败次数
• 合规成本：逐请求详细日志 > 发送尝试日志 > 重放 == 仅失败次数——向第三方公开请求和响应正文会触发数据分类与脱敏审查，而且几乎无法撤回：一旦集成方围绕一组字段构建工具，你就无法悄无声息地将其撤下。
• 效率：发送尝试日志 > 逐请求详细日志 > 仅失败次数 > 重放

默认层级：公开你已经记录的发送尝试日志，适用于平台发送 Webhook 的情况。无论如何，发送机制都会记录每次尝试及其失败原因。公开这些日志主要是访问控制和接口方面的工作，而且能解决 Webhook 平台中最耗费支持资源的问题（“你的 Webhook 从未送达”）。

没有 Webhook 的情况下，默认选择请求日志。

当审计发现工单中有同步 API 失败问题时，升级到完整请求日志——逐次调用记录：时间戳、端点、状态码、错误代码、请求 ID，以及问题 7 允许记录的尽可能多的有效负载信息。这个层级覆盖所有集成方群体，而不只是 Webhook 消费方。

仅记录失败次数是最低层级：每个集成记录一个数字，不提供任何详细信息。实现成本低；如果目前还没有任何记录功能，值得在一两天内上线。但要明白它能带来什么：它会告诉合作方出了问题，却不给他们任何解决问题的方法，因此只是把无声的失败变成支持工单，而不是变成修复。

被冷落的选项：重放。 允许集成方重新发送失败事件或重新运行请求，能挽回其他层级都无法衡量的价值——上面的减少工单维度没有计算这一点。但它也是所有选项中工作量最大的：需要保证幂等性、设定有限的时间窗口，并明确其与你自身重试计划之间的关系。因此，它在效率比较中总是落后。

当审计发现集成方经常在自身停机期间丢失事件时，应提高它的优先级；这恰恰是那种只有损失说明、却无法恢复数据的仪表板最让人无所适从的时候。

应将其设计为独立于自动重试的功能。在 Stripe 中，失败事件最多可在创建后的 15 天内手动重新发送，而且这样做不会取消平台自身的重试计划（来源：Stripe 文档）。因此，合作方手动重放永远不会与平台的机制冲突。

这个排序是默认方案，不是铁律。根据你已经掌握的信息重新排序：

• 没有 Webhook 的平台无发送日志可公开，因此从请求日志开始。
• 已经为自身调试存储完整请求／响应正文的团队，只需提供受访问范围控制的视图，就能实现请求日志层级。
• 如果对问题 7 的回答是“任何正文都不会离开我们的边界”，则应从选项中删除有效负载详细信息；此时元数据日志记录就是上限，而非折中方案。

请参阅 references/visibility-surfaces.md，其中扩展说明了三种表面的分类、日志行必须包含的字段、良好与不良日志行示例、重放语义，以及租户隔离和脱敏规则。

3. 让关联 ID 能够用于支持查询

请在术语中区分以下两个标识符：

• 请求 ID - 标识一次 HTTP 调用及其响应。
• 关联 ID - 标识一个完整的多次调用事务，该事务可能跨越许多请求 ID。

大多数平台两者都需要，却只提供了前者。

惯例是使用 X-Request-Id 携带不透明的随机值 - 默认采用 UUIDv4，因为它在高负载下也能避免冲突，且不会泄露信息；顺序递增或基于时间戳生成的标识符则不同。也存在以平台命名的变体（GitHub 的 request-id、Vercel 的 X-Vercel-Id、Cloudflare 的 Cf-Ray），这些是参考示例，并非要求。W3C 的 traceparent 标头是处于标准化流程中的替代方案，它携带跨度层级和采样标记，而不是单纯的字符串。

• 价值（通过一次查询解决支持工单）：可在面向开发者的日志中搜索 > 在响应标头中回传 > 出现在错误正文中 > 传递给子处理器
• 实施成本：传递给子处理器 > 可在面向开发者的日志中搜索 > 在响应标头中回传 == 出现在错误正文中 - 这种并列确实存在，并非回避问题：两者都是在同一代码路径中，把一个你已经持有的标识符写入你本来就在序列化的响应，无须在任何一方新增存储。
• 效率：在响应标头中回传 > 出现在错误正文中 > 可在面向开发者的日志中搜索 > 传递给子处理器

默认步骤：在每个响应的标头中回传 ID，无论成功还是失败。如果集成方从未收到某个标识符，就无法将它贴到支持工单中；而这一步通常只需修改中间件，耗时以小时计。成功响应也很重要 - 很多工单涉及返回了 200、却执行错误的调用。

步骤 2 上线后，立即提升到可在日志中搜索。 这两个步骤配合起来才能真正闭环：标头将字符串交给集成方，日志则让他们在联系你之前自行查找。只上线标头会导致一种很典型的失败情况 - 集成方尽职尽责地提供了 ID，但平台之外无人能查询。

错误正文这一步确实存在，但应由相关项目负责：samber/developer-platform-skills@api-error-design 负责错误载荷的结构，包括是否在其中携带 ID。请协调，而不是在此处重新设计。

容易被忽视的选项：传递给子处理器。 当你的平台调用支付处理器、承运商或其他下游服务商时，将同一个标识符继续传递给它们，并在重试时保留该标识符，实施成本很高，而且只有在关键时刻才看得出价值。当你当前给出的支持答复是“该故障来自我们的服务商，我们看不到详情”时，就该提升这一步 - 此时，一次查询就能涵盖整条调用链，这正是解决工单与移交工单之间的区别。

此排序只是默认方案，并非铁律。请根据你的技术栈重新排序：

• 已在内部输出 W3C 跟踪上下文的平台，几乎可以不费成本地实现传递，因此会改变成本排序。
• 故障绝大多数都出自自身代码的平台，无论成本如何，实现传递的收益都不大。

请参阅 references/correlation-id-conventions.md，了解标头惯例、请求 ID 与关联 ID 的建模、传递规则、支持查询工作流以及一个反面示例。

4. 按集成身份聚合错误率

平台整体错误率看起来可能很健康，但某个特定集成的所有调用都可能失败。按身份聚合才能让这种情况显现出来，而且这种架构在 API 监控实践者的资料中是一致的（来源：Zuplo、Last9、dotcom-monitor、Odown）：

1. 在数据接入时打标签，而不是事后补上 - API 密钥、应用或客户端 ID，应在请求到达时附加到请求上。之后再补标签，意味着你恰好无法查询想要调查的那段历史数据。
2. 按状态码类别拆分，而不是混为一个整体比率 - 将 4xx（集成方的请求负载或身份验证）、5xx（你方的问题）和 429 单独统计，因为速率限制拒绝不属于任何一方的错误，而且需要不同的补救措施。将它们混在一起会得到一个无人能据此采取行动的数字：你不能只告诉合作伙伴“你的错误率是 8%”，却不说明这 8% 是谁的责任。
3. 按身份计算滚动错误率，并将每个集成与其自身近期基线比较，而不是使用全局阈值 - 各集成的流量形态差异很大，因此平台统一的百分比要么会让小流量集成产生过多噪声，要么会对大流量集成的问题视而不见。Moesif 的 API 监控文档涵盖了这两方面：实时记录每个端点和每个客户的状态码分布，以及“Dynamic Alert”，它会先根据几天的数据建立历史基线，再对偏离基线的情况发出警报（来源：Moesif 文档）。
4. 在得出结论前，与你自己的部署时间线进行关联。如果错误激增恰好与上次发布同步，那就是你的回归问题；否则怪到合作伙伴头上，会让你付出一次信任代价。这并非假设，而是一种已有明确名称并已投入使用的实践 - Datadog 的 Deployment Tracking 会在错误率图表上叠加部署和版本标记，专门用于判断新版本是否引入了错误（来源：Datadog 文档）。
5. 查看分布，而不只是数量 - 如果错误集中在某个时间段或某种操作模式，通常指向逻辑错误或批量操作；如果错误均匀分布，则更可能是基础设施问题。这会改变你通知的对象以及通知内容。

429 的处理会交给 samber/developer-platform-skills@api-rate-limit-policy：错误的呈现由你负责，配额设计和标头则由该技能负责。

有关聚合架构、状态码分桶定义和错误率消耗检测窗口，请参阅 references/alerting-and-notification.md。

5. 确定通知策略

只有聚合而不通知，只能帮助那些想到要去查看的集成方——这会把整个舰队细分群体排除在受众之外。但推送通知最容易让这套设计自毁：每次失败都触发的警报流会被静音，而静音的渠道则什么也送达不了。

• 价值（合作伙伴能赶在自己的客户之前获知）：带冷却时间的阈值警报 > 摘要 > 状态变更时立即警报 > 仅提供拉取式仪表板
• 工作量：带冷却时间的阈值警报 > 摘要 > 状态变更时立即警报 > 仅提供拉取式仪表板
• 效率：摘要 > 带冷却时间的阈值警报 > 状态变更时立即警报 > 仅提供拉取式仪表板

默认档位：每个集成定期发送摘要——按计划汇总各类别的故障，并附上指向第 2 步日志的链接。它只需要一个聚合时间窗口和一个调度器，而且默认就能尊重合作伙伴的注意力，无须调整设置。

最容易被忽略的档位是带冷却时间的阈值警报——它在价值排序和工作量排序中都居首，而摘要在效率排序中每次都胜过它。当问题 6 表明合作伙伴会在几小时内蒙受损失时，就应启用这一档位。可以借鉴的具体机制来自 Salesforce 的 Agentforce 健康监控（来源：Salesforce）：错误率飙升或延迟持续攀升时立即通知，然后进入冷却期——该机制的默认冷却时间为 30 分钟——在此期间同一集成不会再次触发警报。

冷却时间让即时通知变得可持续。没有冷却时间，同一事件会持续触发警报，直到有人永久静音该渠道。

集成状态变更时立即发送警报——凭据被撤销、集成被禁用、订阅过期——是一个独立且范围有限的档位，可以与其他档位并用。这些都是单次的离散事件，而不是持续不断的信息流；对于这类事件，摘要延迟一小时确实太久。

按每次失败立即发送关于错误_数量_的警报，不在此列。这本身就是警报疲劳的成因，而不是一个档位；把它放在列表底部，之后就会悄然重新出现在范围之中。

先发布日志功能，但别误以为这就完成了。这不是假设中的问题，而是有据可查的现实缺口：Shopify 的合作伙伴仪表板会显示函数错误计数和可计费事件错误，但针对这些错误的基于阈值的电子邮件警报仍只是开发者的需求，并未作为功能发布（来源：Shopify 开发者文档和开发者社区）。平台在第 2 步完成日志记录后便止步不前，这种情况很常见。

这一排序是默认方案，而非铁律。应根据用户重新排序：

• 已经有面向合作伙伴的外发通知渠道的平台，启用任何推送档位的成本都会更低，因此工作量排序也会相应缩小。
• 如果合作伙伴群体是密切监控自身系统的单账户集成方，那么只提供摘要也完全合理。
• 问题 8 中的工作量上限决定了你能投入多少精力来调整阈值，因为负担不起调整的警报，最终就会变成没人阅读的警报。

通知模板和防疲劳规则见 references/alerting-and-notification.md。

6. 构建服务提供方的全局视图

从你自己的视角查看第 4 步中的同一份聚合数据，可以回答另一个问题：目前哪些集成出了故障，我们应该联系哪位合作伙伴？这是合作伙伴团队和支持团队使用的界面，也是实现主动联络、而非被动响应的关键。

• 按影响范围而非原始错误数对集成排序——合作伙伴应用在 200 次安装中都出现故障，比单个账户报出更多错误更重要，而单纯按数量排列的排行榜会颠倒这一优先级。
• 区分“自上次部署以来就已故障”和“自对方上次发布以来就已故障”。前者完全由你负责；后者才需要主动联系合作伙伴。
• 纳入第 1 步中的无声故障信号：调用量降至零的集成不会出现在任何错误排行榜中。
• 按合作伙伴计算加权健康分数，是已有实际应用的做法，并非凭空发明。专为 Salesforce 上的 ISV 打造的第三方工具会针对每个托管软件包计算这类分数（来源：ISVapp 产品文档）。具体权重应由你自行设定并说明依据，而不是照搬他人的设置。

在这里借鉴 SLO 框架时要谨慎。已发布的错误预算和 SLO 文献面向消费者侧团队，用于衡量自身对他人 API 的依赖，不能原封不动地移植到服务提供方为合作伙伴发布可靠性数据的场景。反过来的表述——平台是关于集成健康状况的可信实时信息来源，让合作伙伴无需自行监控你——是本指南提出的设计理念，并非有来源支持的实践。

将其作为设计意图。不要把它作为行业标准介绍给合作伙伴，也不要在尚无法为计算方式提供依据之前发布针对单个合作伙伴的可靠性数据。

完整的全局视图布局、健康分数构建方式以及 SLO 适配差距，请参阅 references/fleet-view-and-health-scoring.md。

故障模式

以下每一项都是直接审计发现：

• 日志记录已上线，告警却被列为范围之外，而平台仍要靠终端用户才得知合作伙伴服务中断。
• 告警疲劳：每次故障都触发一条告警，没有冷却时间，合作伙伴已将频道静音——之后平台实际上又退回到仅被动响应，却仍以为自己会通知对方。
• 请求 ID 虽通过标头回传，但没有任何外部界面可以查询它，导致集成方引用一串只有你的工程师才能查到的字符串。
• 下游调用或重试调用丢失关联 ID，恰好在合作伙伴看不到的环节中断了调用链。
• 每个集成只有一个混合错误率，4xx、5xx 和 429 混在一起，因此通知无法说明问题出在哪一方。
• 全局错误率看似健康，却掩盖了某个集成的每次调用都失败的情况。
• 将消费者侧 SRE 错误预算框架原封不动地套用到面向合作伙伴的可靠性承诺上，而平台设计之初并未打算兑现这种承诺。
• 仪表板仅限账户所有者查看，而实际维护集成的合作伙伴工程师无法访问。
• 日志保留时间短于合作伙伴察觉问题所需的时间，导致调查开始前证据就已过期。
• 未对暴露的载荷进行脱敏，导致 PII、机密信息或其他租户的数据泄露到第三方控制台。
• 重放机制与平台自身的重试计划冲突，产生重复副作用，之后还要由合作伙伴进行协调处理。
• 某个集成彻底停止调用，却没有出现在任何视图中，因为没有调用就不会产生错误。

衡量指标

• 故障类别覆盖率 - 集成方现在能够独立诊断的第 1 步审计中故障类别所占比例。这是门槛：持续迭代，直到工单堆积中每个类别都有对应的可见界面，或者有书面说明解释为何没有。
• 请求 ID 可解析性 - 每个错误响应都带有一个标识符，集成方可以通过自己能够访问的界面查询到它。这是一个二元指标，测试成本很低：从真实响应中取一个 ID，像外部用户那样查找即可。
• 自助解决率 - 发布后，从新一批工单中重新进行第 1 步分类并比较。变化方向才是信号，具体数值则不是，因此应基于自身发布前后的数据建立基线，而不是使用任何已发布的数据（自行设定：这方面没有行业基准）。
• 从故障发生到合作伙伴知晓所需时间 - 从首次故障开始计时，直到合作伙伴采取行动，而不是直到告警发出。按通知级别分别跟踪，因为这个数字决定了是否有理由提升通知级别。
• 告警处理率 - 合作伙伴采取行动的告警所占比例。比率下降意味着告警疲劳问题开始显现。若持续下降，应将阈值调宽或延长冷却时间（自行设定：阈值由你根据自身基线确定）。

前两个是门槛。后三个是需要关注的趋势，绝不是达标阈值——这些指标都没有可靠的行业数据作为依据。

调用示例

• “合作伙伴总是等客户投诉后才发现集成出了问题——设计一下我们应该向他们展示什么。”
• “为我们的 API 构建面向开发者的请求日志；我们已经在内部存储了每个请求。”
• “每次 Webhook 失败我们都会向合作伙伴发送告警，他们全都把通知静音了。改进通知设计。”
• “审查外部集成方今天在我们的平台上实际上能看到哪些与自身故障有关的信息。”
• “设计一个应用全局视图，让我们的合作伙伴团队了解哪些 ISV 应用在不同安装中出现故障。”

参考资料

• references/visibility-surfaces.md - 请求／事件／投递三类界面的分类法、必需的日志行字段、优劣日志行示例、重放语义、保留期限和访问范围、脱敏规则。
• references/correlation-id-conventions.md - 请求 ID 与关联 ID 的区别、标头约定和平台变体、回显与传播规则、支持查询工作流、反面示例。
• references/alerting-and-notification.md - 按标识聚合的架构、状态码分组、阈值与冷却机制、多窗口燃尽率检测、通知模板、防疲劳规则。
• references/fleet-view-and-health-scoring.md - 提供方全局视图布局、影响范围排序、按合作伙伴构建健康评分、消费方调整 SLO 时的差距。

另请参阅同一合集中的内容：

• samber/developer-platform-skills@webhook-platform-design - 投递日志背后的投递语义、重试计划和死信处理。此技能是在这些机制之上的可见性层。
• samber/developer-platform-skills@developer-portal-design - 这些日志和仪表板在门户信息架构与访问模型中的位置。
• samber/developer-platform-skills@partner-app-onboarding - 决定最初由谁关注这些界面的合作伙伴生命周期。
• samber/developer-platform-skills@integration-health-monitoring - 当前正常运行、但会在已知日期发生故障的集成（版本漂移、已弃用调用、凭证过期）；此技能涵盖已经发生的故障。