vtex-io-observability-and-ops

可观测性与运维就绪度

适用场景

当 VTEX IO 服务需要提升生产环境可见性、故障排查能力或运维安全性时，请使用此技能。

• 为重要的客户端调用或流程添加指标
• 改进路由、工作进程或集成的日志
• 清晰呈现故障，便于运维和支持人员处理
• 检查服务是否已准备好投入生产
• 监控对速率限制敏感的集成

以下场景不适用：

• 应用策略声明
• 信任边界建模
• 前端分析或浏览器监控
• 单独设计路由契约

决策规则

• 记录足够的结构化上下文以排查故障，但不要记录机密或敏感载荷。
• 使用 ctx.vtex.logger 和适当的日志级别（如 info、warn 和 error），而不是 console.log，以便在 VTEX 日志系统中正确收集和搜索日志。
• 将 ctx.vtex.logger 视为平台原生的日志机制。如果合作伙伴需要将日志转发到自己的日志系统，优先通过专用集成应用或客户端来实现，而不是在每个服务中替换 VTEX 日志模式。
• 对重要的下游调用使用客户端级指标，以便在处理程序层以下观察集成行为。
• 指标名称应体现集成和操作，例如 partner-get-order 或 partner-sync-catalog，以便持续跟踪调用次数、延迟和错误率。
• 在故障发生的位置使其可观测。不要在路由、事件或工作进程中静默吞掉错误。
• 对速率限制敏感的 API，结合较短的超时、考虑退避机制的重试，以及对频繁读取内容的缓存，以减轻突发请求压力并避免触及硬性限制。
• 发布之前，检查开销较大或脆弱的流程是否提供了足够的运维信号。

硬性约束

约束：重要故障必须在日志、指标或持久化状态中可见

路由、事件处理程序和工作进程绝不能向运维人员隐瞒重要故障。

原因

如果故障被静默忽略，服务在真实流量和重试情况下将无法诊断。

检测

如果捕获错误后未记录日志、发出指标或显式设置故障状态便将其忽略，请停止并呈现该故障。

正确

try {
  await ctx.clients.partnerApi.sendOrder(orderId)
} catch (error) {
  ctx.vtex.logger.error({
    message: 'Failed to send order to partner',
    orderId,
    account: ctx.vtex.account,
    routeId: ctx.vtex.route?.id,
  })
  throw error
}

错误

try {
  await ctx.clients.partnerApi.sendOrder(orderId)
} catch (_) {
  return
}

约束：重要的集成调用应附带指标

在运维上很重要的客户端调用应包含 metric，以便持续跟踪请求行为。

原因

没有指标时，很难从常规路由行为中区分集成故障和延迟模式。

检测

如果关键的下游集成调用没有 metric，且运维工作依赖该调用，请停止并添加有意义的指标名称。

正确

return this.http.get(`/orders/${id}`, {
  metric: 'partner-get-order',
})

错误

return this.http.get(`/orders/${id}`)

约束：日志必须实用且不泄露敏感数据

日志必须包含足够的上下文以排查生产环境中的问题，但绝不能包含机密、令牌或不必要的敏感载荷。

原因

只有在可以安全保留和查看的情况下，运维日志才有价值。记录敏感信息会带来安全风险，同时仍无法保证诊断有效。

检测

如果日志行包含令牌、身份验证标头、原始个人数据载荷或完整的下游响应，请停止并对日志内容进行脱敏。

正确

ctx.vtex.logger.info({
  message: 'Partner sync started',
  orderId,
  account: ctx.vtex.account,
})

错误

ctx.vtex.logger.info({
  message: 'Partner sync started',
  body: ctx.request.body,
  auth: ctx.request.header.authorization,
})

首选模式

运维状况良好的 VTEX IO 服务应：

• 为重要的客户端调用发出指标，以便查看调用次数、延迟和错误率
• 记录故障，并提供足够的结构化上下文，例如领域 ID、账户和 routeId
• 避免静默吞掉错误
• 在记录日志之前对敏感数据进行脱敏
• 结合速率限制情况检查重试、缓存和吞吐量

使用可观测性缩短诊断时间，而不只是增加日志。

常见故障模式

• 在异步流程中捕获并忽略错误。
• 记录的上下文过少，无法诊断生产环境事故。
• 记录过多敏感数据。
• 未记录重要集成调用的指标。
• 将速率限制故障视为孤立的错误，而不是运维信号。

审查清单

• 重要故障是否对运维人员可见？
• 关键集成是否会发出有用的指标？
• 日志是否采用结构化格式且安全？
• 是否综合考虑重试、缓存和速率限制行为？
• 值班人员能否根据现有信号诊断此流程？

参考资料

• 使用 Node 客户端 - 与指标和重试相关的客户端使用模式
• 避免速率限制错误的最佳实践 - 关于构建稳定集成的运维指南