183-java-observability-tracing-opentelemetry

使用 OpenTelemetry 实现 Java 分布式追踪

通过建模有意义的 Span、保留上下文传播，并以低开销、保护隐私的遥测数据为关键业务和基础设施路径添加埋点，使用 OpenTelemetry 在 Java 中实现可靠的分布式追踪。

此技能涵盖哪些内容？

• Java 服务的 OpenTelemetry 追踪基础
• Span 设计：边界、父子关系和操作命名
• 跨 HTTP、消息传递、异步任务和线程边界的上下文传播
• 语义约定和稳定的属性命名
• 错误、状态和事件记录最佳实践
• 采样策略及性能/成本权衡
• Span 属性的隐私和安全控制
• 追踪传播和 Span 正确性的测试与验证

**范围：**应用和集成层的分布式追踪质量，重点关注可诊断性、一致性和运行安全。

约束

追踪埋点必须正确保留上下文，并避免泄露敏感数据。过度埋点和高基数属性可能会增加成本并降低信号质量。

• 传播优先：在添加额外的 Span 详细信息之前，确保所有同步/异步边界的上下文传播正常
• 禁止敏感数据：绝不在 Span 属性/事件中存储机密、凭据、令牌、原始负载或 PII
• 低基数属性：避免在用于聚合/搜索的属性中使用无界值
• 验证：应用追踪变更后，运行 ./mvnw clean verify 或 mvn clean verify

何时使用此技能

• 改进追踪
• 使用 OpenTelemetry 实现追踪
• 添加分布式追踪
• 重构追踪埋点
• 使用 OpenTelemetry Span 为 Java 服务添加埋点

工作流

1. 定义追踪模型和关键流程

识别高价值的请求和异步流程，定义操作边界，并选择符合语义约定的 Span 名称/属性。

2. 添加埋点并传播上下文

在关键边界添加 OpenTelemetry Span，并确保追踪上下文能够跨 HTTP 客户端/服务端、消息传递和基于执行器的异步工作进行传播。

3. 强化 Span 数据和采样

一致地记录状态/错误/事件，移除敏感数据，控制属性基数，并根据环境需求配置采样和导出器。

4. 端到端验证追踪

通过测试和运行时检查，验证父子关系、传播连续性以及后端可见性。

参考

如需详细指南、示例和约束，请参阅 references/183-java-observability-tracing-opentelemetry.md。