在分布式系统中构建端到端可观测性时使用：用…

适用于微服务/分布式系统需要端到端追踪、指标采集、结构化日志、关联分析、告警与仪表盘时落地可观测性规范。

适用场景

解决思路

1. 将这些可观测性原则应用到分布式系统和微服务，确保具备全面的可见性。
2. 指导开发具备内建可观测性的惯用、可维护、高性能代码。
3. 通过 Clean Architecture 强制模块化设计和关注点分离。
4. 从一开始就推动测试驱动开发和稳健可观测性。
5. 使用 OpenTelemetry 实现分布式追踪、指标和结构化日志。
6. 在所有服务边界启动并传播 tracing span。
7. 使用 otel.Tracer 创建 span，使用 otel.Meter 收集指标。
8. 将数据导出到 OpenTelemetry Collector、Jaeger 或 Prometheus。
9. 为生产环境配置合适的采样率。
10. 追踪所有传入请求，并通过内部调用传播 context。
11. 使用 middleware 自动插桩 HTTP 和 gRPC 端点。
12. 在所有下游服务调用中包含 trace context。
13. 为服务内的重要操作创建 child span。
14. 向 span 添加相关 attributes，便于调试和分析。
15. 在所有服务中监控以下关键指标：
16. 请求延迟：跟踪 p50、p90、p95 和 p99 百分位。
17. 吞吐量：按端点测量每秒请求数。
18. 错误率：分别跟踪 4xx 和 5xx 响应。
19. 资源使用：监控 CPU、内存、磁盘和网络利用率。
20. 自定义业务指标：跟踪领域特定 KPI。
21. 在所有日志中包含唯一 request ID 和 trace context，以便关联。
22. 使用结构化日志格式（JSON）以便机器解析。
23. 包含相关 context：timestamp、service name、trace ID、span ID。
24. 以适当级别记录日志：DEBUG、INFO、WARN、ERROR。
25. 避免记录敏感信息（PII、凭据）。
26. 应用 Clean Architecture，包含 handlers、services、repositories 和 domain models。
27. 使用领域驱动设计原则建立清晰边界。
28. 优先采用接口驱动开发，并使用显式 dependency injection。
29. 优先使用组合而非继承；偏好小而专注于特定用途的接口。
30. 在整个请求生命周期中传播 context。
31. 使用 correlation ID 跨服务跟踪请求。
32. 在 telemetry 中包含服务版本和部署信息。
33. 用相关业务 context 标记 traces 以便过滤。
34. 启用 trace-to-log 和 log-to-trace 关联。
35. 为服务健康和业务指标创建 dashboards。
36. 基于 SLO 和 error budget 设置 alerts。
37. 使用异常检测主动识别问题。
38. 为常见 alert 场景记录 runbook。
39. 定期审查和调整 alerts 以减少噪音。
40. 在服务边界（入口/出口点）进行插桩。
41. 为数据库操作和外部调用添加 custom spans。
42. 包含相关 attributes（user ID、request type 等）。
43. 避免过度插桩造成噪音。
44. 使用 semantic conventions 保持 attribute 命名一致。
45. 配置合适的采样率，平衡可见性和成本。
46. 使用 head-based sampling 实现一致的 trace 捕获。
47. 实现 tail-based sampling 以捕获错误。
48. 根据调试需求设置 retention policies。
49. 监控可观测性基础设施的健康状况。

适用边界 · 注意事项

• 不适用于没有跨服务或分布式调用、也不需要长期排障的简单单体应用或一次性脚本。
• 当无法承担遥测数据存储、网络和采样复杂度成本，且没有明确可观测性目标时，不应照搬全量采集与复杂告警。
• 在尚未定义 SLO、error budget 或告警责任人及处理流程时，不宜直接套用基于 SLO 的告警策略。