为 Go 生产服务接入日常可观测性时，用…

适用于给 Go 服务做生产监控插桩、搭建指标/告警/追踪、关联日志与 trace、迁移旧 logger，以及做合规 RUM 事件跟踪。

适用场景

解决思路

1. Coding/instrumentation 模式下，给新或旧代码添加可观测性：声明 metrics、添加 spans、设置结构化日志、接入 pprof 开关。
2. Review 模式下审查 PR 的插桩变更：确认新代码导出预期信号，包括已声明 metrics、span 正确开启和关闭、结构化日志字段一致。
3. Audit 模式下审计代码库可观测性覆盖率：并行启动最多 5 个子代理，分别检查 metrics、logging、tracing、profiling、RUM，并合并覆盖发现；在 Claude Code 可用 `ultracode` 显式启用多代理编排。
4. 生产服务使用 `log/slog` 输出结构化日志（JSON），不要输出自由格式字符串。
5. 按场景选择日志级别：Debug 用于开发，Info 用于正常操作，Warn 用于降级状态，Error 用于需要关注的失败。
6. 记录日志时传入上下文：使用 `slog.InfoContext(ctx, ...)` 关联日志与 traces。
7. 延迟指标优先使用 Histogram 而不是 Summary；每个 HTTP endpoint 必须有延迟和错误率指标。
8. Prometheus 标签保持低基数：绝不用无界值（user IDs、完整 URL）作为标签值。
9. 用 Histogram + `histogram_quantile()` 在 PromQL 中跟踪 P50、P90、P99、P99.9 百分位。
10. 新项目设置 OpenTelemetry tracing：尽早配置 TracerProvider，然后在各处添加 spans。
11. 给每个有意义的操作添加 spans：服务方法、DB 查询、外部 API 调用、消息队列操作。
12. 到处传播 context：用 context 跨服务边界携带 trace_id、span_id 和 deadlines。
13. 通过环境变量启用 profiling：无需重新部署即可开关 pprof 和连续 profiling。
14. 关联信号：将 trace_id 注入日志；用 exemplars 把 metrics 链接到 traces。
15. 功能未可观测就不算完成：声明 metrics、添加合适日志、创建 spans。
16. 使用 `awesome-prometheus-alerts` 的约 500 条现成告警规则，按技术组织，用于基础设施和依赖监控。
17. Go 1.26+ 简单 fan-out 到多个 slog handler 时，优先使用 stdlib `slog.NewMultiHandler`，再考虑第三方 handler-composition 依赖；仅在 stdlib 组合不足时使用第三方 slog handler 库。
18. 按五类信号选择工具：Logs 用 `log/slog`；Metrics 用 Prometheus client；Traces 用 OpenTelemetry；Profiles 用 pprof/Pyroscope；RUM 用 PostHog/Segment。
19. 结构化日志：设置 `log/slog`，用 Debug/Info/Warn/Error 级别，用 trace IDs 做请求关联，用 `slog.InfoContext` 传播 context，添加 request-scoped attributes，选用 slog 生态的 handlers/formatters/middleware，并从 zap/logrus/zerolog 迁移。
20. 指标：设置 Prometheus client，理解四种指标类型（Counter 用于变化率、Gauge 用于快照、Histogram 用于延迟聚合），优先 Histogram 而非 Summary，遵循命名约定，在指标声明上方以注释写 PromQL 查询，编写生产级 PromQL 示例，配置多窗口 SLO burn rate 告警，避免高基数标签问题。
21. 分布式追踪：使用 OpenTelemetry SDK 追踪跨服务请求流；创建 spans 并设置 attributes、记录 status；用 `otelhttp` middleware 做 HTTP instrumentation；用 `span.RecordError()` 记录错误；做 trace sampling；跨服务边界传播 trace context；做成本优化。
22. Profiling：用 pprof 做按需 profiling（CPU、heap、goroutine、mutex、block profiles）；在生产中启用并用认证保护；通过环境变量开关而不重新部署；用 Pyroscope 做连续 profiling；评估各 profiling 类型成本并缓解。
23. RUM：理解用户实际体验；做产品分析（事件跟踪、funnels）；集成 CDP；做 GDPR/CCPA consent checks；实现数据主体权利（用户删除 endpoints）；遵守隐私 checklist；服务端事件跟踪（PostHog、Segment）；identity key 最佳实践。
24. 告警：关注四个 golden signals（latency、traffic、errors、saturation）；使用 `awesome-prometheus-alerts` 按技术组织的约 500 条规则；设置 Go runtime alerts（goroutine leaks、GC pressure、OOM risk）；定义 severity levels；避免破坏告警的常见错误（用 `irate` 而不是 `rate`、缺少 `for:` duration 导致 flapping）。
25. Grafana dashboards：安装 Go runtime 监控预构建 dashboards（heap allocation、GC pause frequency、goroutine count、CPU）；按服务定制；按不同运维问题选择对应 dashboard。
26. Logs + Traces 关联：使用 `go.opentelemetry.io/contrib/bridges/otelslog` 创建自动注入 trace_id 和 span_id 的 logger，`slog.SetDefault(slog.New(logger))`，之后每个带 context 的 slog 调用都包含 trace 关联。
27. Metrics + Traces 关联：记录 histogram observation 时，将 trace_id 作为 exemplar 附加，使 P99 尖峰可直接跳到问题 trace；用 `prometheus.ExemplarObserver` 和 `ObserveWithExemplar`，否则退化为 `Observe`。
28. 迁移 legacy loggers 到 `log/slog` 第 1 步：添加 `slog` 作为新 logger，并用 `slog.SetDefault()`。
29. 迁移 legacy loggers 到 `log/slog` 第 2 步：迁移期间用 bridge handlers 把 slog 输出路由到旧 logger，可用 `samber/slog-zap`、`samber/slog-logrus`、`samber/slog-zerolog`。
30. 迁移 legacy loggers 到 `log/slog` 第 3 步：逐步把所有 `zap.L().Info(...)` / `logrus.Info(...)` / `log.Info().Msg(...)` 调用替换为 `slog.Info(...)`。
31. 迁移 legacy loggers 到 `log/slog` 第 4 步：完全迁移后移除 bridge handler 和旧 logger 依赖。
32. Definition of Done 检查 metrics：为操作/错误声明 counters，为延迟声明 histograms，为饱和度声明 gauges；每个 metric var 上方以注释写 PromQL 查询和 alert rules。
33. Definition of Done 检查 logging：使用 `slog` 的结构化 key-value pairs；使用 context 变体（如 `slog.InfoContext`）；日志中无 PII；错误必须要么记录要么返回，绝不能同时。
34. Definition of Done 检查 spans：每个服务方法、DB 查询、外部 API 调用都有 span 和相关 attributes；错误用 `span.RecordError()` 记录。
35. Definition of Done 检查 dashboards/alerts：把 metric comments 中的 PromQL 接入 Grafana dashboards 和 Prometheus alerting rules；常用基础设施依赖的告警规则可从 `awesome-prometheus-alerts` 获取。
36. Definition of Done 检查 RUM：服务端跟踪关键业务事件（PostHog/Segment）；identity key 用 `user_id` 而不是 email；跟踪前检查 consent。
37. 避免错误处理反模式：不要 log 后又 return 错误（错误会沿链多次记录）；应返回带上下文的错误，在顶层记录一次。
38. 避免 Prometheus 高基数标签：不要 `httpRequests.WithLabelValues(r.Method, r.URL.Path, userID).Inc()`；只用有界标签值，如 `httpRequests.WithLabelValues(r.Method, routePattern).Inc()`。
39. 避免破坏 trace propagation：不要 `db.Query(SELECT ...)`；应使用 `db.QueryContext(ctx, SELECT ...)` 让 context 流动，trace 继续。
40. 避免用 Summary 做延迟：不要 `prometheus.NewSummary(...)`；应使用 `prometheus.NewHistogram(...)`，因为可聚合并支持 `histogram_quantile`。
41. 需要错误处理单一规则时，参考 `samber/cc-skills-golang@golang-error-handling` skill。
42. 需要用可观测性信号诊断生产问题时，参考 `samber/cc-skills-golang@golang-troubleshooting` skill。
43. 需要保护 pprof endpoints 和避免日志 PII 时，参考 `samber/cc-skills-golang@golang-security` skill。
44. 需要跨服务边界传播 trace context 时，参考 `samber/cc-skills-golang@golang-context` skill。
45. 需要从 CLI 查询和探索 PromQL 时，参考 `samber/cc-skills@promql-cli` skill。

适用边界 · 注意事项

• 不适用于临时深度性能调查/基准测试；这类任务应使用 `samber/cc-skills-golang@golang-benchmark` 和 `samber/cc-skills-golang@golang-performance`。
• 当公司技能明确取代 `samber/cc-skills-golang@golang-observability` 时，优先使用公司技能。
• 不适用于非 Go 项目。