production-observability

生产环境可观测性

为用户可见的操作和运维边界添加埋点，而不是为每个方法都添加埋点。

基线

• 添加 Actuator 和一个根据部署平台选择的指标注册表。
• 使用 Micrometer Observation 采集应用指标和跟踪数据。
• 使用 Micrometer Tracing 和选定的桥接器；不要在业务代码中混用跟踪 API。
• 如果平台采用 OpenTelemetry 收集器作为标准，则通过 OTLP 导出数据。
• 仅公开必需的 actuator 端点，并保护所有非公开端点。

可观测性约定

• 使用稳定的操作名称，例如 orders.create。
• 指标标签保持低基数：方法、结果、区域或有限范围的状态。
• 请求 ID、用户 ID、订单 ID 和异常消息只放入跟踪数据或日志。
• 在 @Async、执行器和 Reactor 边界之间传播上下文。
• 记录每个外部依赖的延迟、吞吐量、故障和饱和度。

健康检查与就绪状态

• 保持存活检查不依赖远程系统，避免依赖项故障导致所有 Pod 重启。
• 将必需的依赖项加入就绪状态组。
• 仅为影响流量接入的依赖项编写自定义健康指示器。
• 为健康检查设置明确的超时时间。

日志与告警

• 输出带有跟踪和 Span 关联信息的结构化日志。
• 默认对凭据、令牌、个人数据、提示词和负载进行脱敏。
• 针对与服务目标相关的症状告警，而不是原始指标噪声。
• 包含运行手册链接，并提供足够的维度，以识别受影响的服务和依赖项。

示例

• 请参阅 examples/good-observation.java 和 examples/bad-observation.java。

注意事项

• Agent 使用用户或实体 ID 作为指标标签——这会造成无界基数。
• Agent 公开所有 actuator 端点——应仅公开最少的端点并加以保护。
• Agent 让存活检查依赖数据库——依赖项故障会导致重启循环。
• Agent 为调试记录请求正文和令牌——输出前应对敏感数据进行脱敏。
• Agent 创建 Span，却在异步工作中丢失上下文——应明确配置上下文传播。