observability-guidelines

可观测性指南

应用以下可观测性原则，确保全面了解分布式系统和微服务。

可观测性核心原则

• 通过内置可观测性，指导开发符合惯例、易于维护且高性能的代码
• 通过整洁架构贯彻模块化设计和关注点分离
• 从一开始就推广测试驱动开发和完善的可观测性

OpenTelemetry 集成

• 使用 OpenTelemetry 进行分布式追踪、指标采集和结构化日志记录
• 在所有服务边界启动追踪 Span 并传播它们
• 使用 otel.Tracer 创建 Span，使用 otel.Meter 收集指标
• 将数据导出到 OpenTelemetry Collector、Jaeger 或 Prometheus
• 为生产环境配置适当的采样率

分布式追踪

• 追踪所有传入请求，并在内部调用中传播上下文
• 使用中间件自动为 HTTP 和 gRPC 端点添加监测
• 在所有下游服务调用中包含追踪上下文
• 为服务中的重要操作创建子 Span
• 为 Span 添加相关属性，以便调试和分析

指标采集

监控所有服务中的以下关键指标：

• 请求延迟：跟踪 p50、p90、p95 和 p99 百分位数
• 吞吐量：按端点衡量每秒请求数
• 错误率：分别跟踪 4xx 和 5xx 响应
• 资源使用情况：监控 CPU、内存、磁盘和网络利用率
• 自定义业务指标：跟踪特定领域的 KPI

结构化日志记录

• 在所有日志中包含唯一请求 ID 和追踪上下文，以便关联
• 使用结构化日志格式（JSON），便于机器解析
• 包含相关上下文：时间戳、服务名称、追踪 ID、Span ID
• 使用适当的级别记录日志：DEBUG、INFO、WARN、ERROR
• 避免记录敏感信息（PII、凭据）

架构模式

• 采用整洁架构，包含处理程序、服务、存储库和领域模型
• 运用领域驱动设计原则，明确划分边界
• 优先采用接口驱动开发，并显式注入依赖
• 优先使用组合而非继承；采用小型、用途明确的接口

关联与上下文

• 在整个请求生命周期中传播上下文
• 使用关联 ID 跨服务跟踪请求
• 在遥测数据中包含服务版本和部署信息
• 为追踪添加相关业务上下文标签，以便筛选
• 启用追踪与日志之间的双向关联

告警与仪表板

• 创建用于监控服务健康状况和业务指标的仪表板
• 根据 SLO 和错误预算设置告警
• 使用异常检测主动识别问题
• 为常见告警场景编写操作手册
• 定期审查和调整告警，减少噪声

监测最佳实践

• 在服务边界（入口和出口）添加监测
• 为数据库操作和外部调用添加自定义 Span
• 包含相关属性（用户 ID、请求类型等）
• 避免过度监测，以免产生噪声
• 使用语义约定，确保属性命名一致

生产环境注意事项

• 配置适当的采样率，在可见性和成本之间取得平衡
• 使用基于头部的采样，确保持续捕获追踪数据
• 实施基于尾部的采样，以捕获错误
• 根据调试需求设置保留策略
• 监控可观测性基础设施的健康状况