VTEX IO 服务上线前后如何提升可观测性与运维就绪度

当 VTEX IO 后端服务需要更好的生产可见性、故障排查或运维安全性时使用。

适用场景

解决思路

1. 记录足够的结构化上下文以便调试失败，但不要记录密钥或敏感负载。
2. 使用 `ctx.vtex.logger` 并配合合适的日志级别（如 `info`、`warn`、`error`），而不是 `console.log`，以便日志能被 VTEX 日志栈正确收集和检索。
3. 将 `ctx.vtex.logger` 视为平台原生日志机制；如果合作方需要把日志转发到自己的日志系统，优先通过专门的集成应用或客户端实现，而不是在每个服务里替换 VTEX logger 模式。
4. 在重要的下游调用上使用客户端级 metrics，使集成行为在 handler 层之下也可见。
5. 选择能反映集成和操作的 metric 名称，例如 `partner-get-order` 或 `partner-sync-catalog`，以便随时间跟踪计数、延迟和错误率。
6. 让失败在发生点可观测；不要在路由、事件或 worker 中静默吞掉错误。
7. 对于对速率限制敏感的 API，结合短超时、感知退避的重试以及频繁读取的缓存，以减少突发压力并避免触及硬限制。
8. 在发布前审查昂贵或脆弱的流程是否暴露了足够的运维信号。
9. 重要失败必须在日志、metrics 或持久状态中可见：路由、事件处理器和 worker 不得对运维人员隐藏重要失败。
10. 如果错误被捕获并忽略，且没有日志、metric 发出或显式失败状态，应停止并暴露该失败。
11. 重要的集成调用应附加 metrics：对运维重要的客户端调用应包含 `metric`，以便一致地跟踪请求行为。
12. 如果关键下游集成调用没有 `metric` 且运维依赖它，应停止并添加有意义的 metric 名称。
13. 日志必须在不泄露敏感数据的前提下保持有用：日志必须包含足够上下文以调试生产行为，但不得包含密钥、token 或不必要的敏感负载。
14. 如果日志行包含 token、认证头、原始个人负载或完整下游响应，应停止并清理日志。
15. 运维健康的 VTEX IO 服务应：为重要客户端调用发出 metrics，使计数、延迟和错误率可见；记录失败时带上足够的结构化上下文，如 domain ID、account 和 `routeId`；避免静默吞错；记录前清理敏感数据；结合速率限制行为审查重试、缓存和吞吐量。
16. 使用可观测性来缩短诊断时间，而不仅仅是产生更多日志。

适用边界 · 注意事项

• app policy 声明
• 信任边界建模
• 前端分析或浏览器监控
• 单独的路由契约设计