用途
该技能面向 Spring Boot 4 应用的生产可观测性建设，指导如何对用户可见操作和运维边界进行埋点，而不是对每个方法都进行埋点。
主要能力
基线配置
- 添加 Boot 4 Actuator starter，并按平台选择一种指标注册表。
- 若通过 OTLP 使用 OpenTelemetry tracing，使用 spring-boot-starter-opentelemetry 以及 Boot 的 management.opentelemetry.tracing.export.otlp.* 属性。
- 使用 Micrometer Observation 处理应用指标与追踪。
- 在应用代码中优先使用 Micrometer API，而非直接使用 OpenTelemetry API。
- 当 OpenTelemetry collector 是平台边界时，通过 OTLP 导出指标与追踪。
- 仅暴露必需的 actuator 端点，并对非公开端点进行安全保护。
Observation 约定
- 以稳定的操作名称命名 observation，例如 orders.create。
- 指标使用低基数键值，高基数键值仅用于追踪。
- 切勿用用户 ID、实体 ID、含 ID 的 URL 或异常消息作为指标标签。
- 为异步执行器边界注册 ContextPropagatingTaskDecorator。
- 仅在有意为之并经过测试时才启用 Reactor 自动上下文传播。
- 避免对已具备埋点的 MVC controller 或 repository 使用 @Observed 注解。
健康与就绪
- 保持 liveness 独立于远程依赖。
- 将影响流量的关键依赖放入 readiness 分组。
- 为自定义健康检查设置严格超时和稳定的 detail key。
- 对未认证调用者隐藏敏感的健康详情。
日志与告警
- 输出与 trace 和 span ID 关联的结构化日志。
- 默认对凭据、令牌、个人数据、prompt 和请求体进行脱敏。
- 针对服务目标症状告警：错误率、延迟、饱和度或队列滞后。
- 每个可操作告警中包含 runbook 以及服务/依赖标识。
使用方式
资料提供了示例文件：examples/good-observation.java、examples/good-observability.yml 和 examples/bad-observation.java。
官方来源
- Boot observability: https://docs.spring.io/spring-boot/reference/actuator/observability.html
- Boot tracing: https://docs.spring.io/spring-boot/reference/actuator/tracing.html
- Boot structured logging: https://docs.spring.io/spring-boot/reference/features/logging.html#features.logging.structured
常见陷阱
- 将高基数 ID 用作指标标签——应保留给追踪或日志。
- 直接配置 OpenTelemetry SDK 并意外禁用 Boot 集成——应优先使用 Boot 与 Micrometer 支持。
- 暴露所有 actuator 端点——应暴露最小集合并加以保护。
- 将 liveness 绑定到数据库或 broker——依赖故障可能触发重启循环。
- 在 @Async 工作中丢失 trace 上下文——应显式注册上下文传播。