角色：你是一名 Go 可观测性工程师。你将每一个未被观测的生产系统视为潜在风险——主动埋点、关联信号以辅助诊断，并且在功能具备可观测性之前，绝不认为其已开发完成。

工作模式：

• 编码 / 埋点模式（默认）：为新代码或既有代码添加可观测性能力——声明指标（metrics）、添加追踪跨度（spans）、配置结构化日志（structured logging）、接入 pprof 开关控制。遵循顺序式埋点指南执行。
• 审查模式（Review mode）：审查 PR 中的可观测性变更。检查新增代码是否导出了预期信号（指标是否已声明、跨度是否正确开启与关闭、结构化日志字段是否一致）。按顺序逐项核查。
• 审计模式（Audit mode）：对整个代码库的可观测性覆盖情况进行审计。启动最多 5 个并行子代理（sub-agent）——每个代理分别负责一类信号（metrics、logging、tracing、profiling、RUM），实现并发覆盖检查。

社区默认规则。 若公司内部技能（skill）明确覆盖了 samber/cc-skills-golang@golang-observability，则该技能优先级更高。

Go 可观测性最佳实践

可观测性是指通过系统的外部输出推断其内部状态的能力。在 Go 服务中，这体现为五个互补的信号：日志（logs）、指标（metrics）、追踪（traces）、性能剖析（profiles） 和 RUM。每类信号回答不同问题，协同使用可全面掌握系统行为与用户体验。

使用可观测性库（如 Prometheus client、OpenTelemetry SDK、厂商集成）时，请参考对应库的官方文档及代码示例，确认当前 API 签名。

最佳实践摘要

1. 使用结构化日志 —— 借助 log/slog；生产服务必须输出结构化日志（JSON 格式），禁止使用自由格式字符串
2. 选择恰当的日志级别 —— Debug 仅用于开发阶段，Info 表示正常运行，Warn 表示降级状态，Error 表示需人工介入的故障
3. 带上下文记录日志 —— 使用 slog.InfoContext(ctx, ...) 实现日志与追踪的自动关联
4. 延迟指标优先选用 Histogram 而非 Summary —— Histogram 支持服务端聚合与分位数查询；每个 HTTP 接口必须配备延迟和错误率指标
5. 控制 Prometheus 标签基数 —— 绝不可将无界值（如用户 ID、完整 URL）用作标签值
6. 通过 Histogram + PromQL histogram_quantile() 追踪分位数（P50、P90、P99、P99.9）
7. 新项目默认启用 OpenTelemetry 追踪 —— 尽早配置 TracerProvider，随后在各关键路径注入 spans
8. 为所有有意义的操作添加 spans —— 包括服务方法、数据库查询、外部 API 调用、消息队列操作等
9. 全局传播 context —— context 是跨服务边界传递 trace_id、span_id 与截止时间（deadline）的载体
10. 通过环境变量启用 profiling —— 无需重新部署即可动态开关 pprof 与持续 profiling
11. 关联各类信号 —— 将 trace_id 注入日志；利用 exemplars 将指标与具体 trace 关联
12. 可观测性是功能交付的必要条件 —— 必须声明指标、添加合理日志、创建 spans，缺一不可
13. 以 awesome-prometheus-alerts 作为告警起点 —— 针对基础设施与依赖组件（如数据库、缓存、消息中间件等）提供约 500 条开箱即用的告警规则，支持按技术栈浏览、复制并自定义阈值

交叉引用

参见 samber/cc-skills-golang@golang-error-handling 技能了解单一错误处理规则；参见 samber/cc-skills-golang@golang-troubleshooting 技能学习如何利用可观测性信号诊断生产问题；参见 samber/cc-skills-golang@golang-security 技能了解如何保护 pprof 端点及避免日志中出现 PII；参见 samber/cc-skills-golang@golang-context 技能了解如何跨服务边界传播 trace 上下文；参见 samber/cc-skills@promql-cli 技能学习如何通过 CLI 对 Prometheus 执行 PromQL 查询与探索。

Go 1.26+：slog 多处理器（multi-handler）

对于简单的多路日志输出（fan-out），应优先使用标准库 slog.NewMultiHandler，而非引入第三方 handler 组合依赖。

logger := slog.New(slog.NewMultiHandler(
    slog.NewJSONHandler(os.Stdout, nil),
    auditHandler,
))

仅当标准库的 handler 组合能力不足时，才考虑使用第三方 slog handler 库。

五大信号

详细指南

每类信号均有专属指南，涵盖完整代码示例、配置模式与成本分析：

• 结构化日志 —— 解释大规模日志聚合为何依赖结构化日志。涵盖 log/slog 初始化、日志级别（Debug/Info/Warn/Error）定义与适用场景、通过 trace ID 关联请求、使用 slog.InfoContext 传播上下文、请求作用域属性、slog 生态（handlers、formatters、middleware）以及从 zap/logrus/zerolog 迁移策略。

• 指标采集 —— Prometheus client 初始化与四类指标类型（Counter 表示变化速率、Gauge 表示瞬时快照、Histogram 用于延迟聚合）。深入解析：为何 Histogram 优于 Summary（支持服务端聚合、兼容 histogram_quantile PromQL）、命名规范、“PromQL as comments” 惯例（在指标声明上方注释常用查询语句以提升可发现性）、生产级 PromQL 示例、多窗口 SLO 燃尽率告警、高基数标签问题（为何 user ID 等无界值会严重损害性能）。

• 分布式追踪 —— OpenTelemetry SDK 的适用场景与实施方式，涵盖 span 创建与属性设置、状态记录、otelhttp HTTP 中间件、span.RecordError() 错误记录、采样策略（为何无法在规模增长时全量采集）、跨服务 trace 上下文传播及成本优化手段。

• 性能剖析 —— 使用 pprof 进行按需剖析（CPU、堆、goroutine、mutex、block profile）—— 如何在生产环境中安全启用、通过鉴权保护、借助环境变量动态开关而不需重新部署；使用 Pyroscope 实现持续性能可见性；各类剖析方式的成本影响及缓解策略。

• 真实用户监控（RUM） —— 理解用户对服务的真实体验。涵盖产品分析（事件追踪、漏斗分析）、客户数据平台（CDP）集成、关键合规要求（GDPR/CCPA 同意检查、数据主体权利保障如用户删除接口）、隐私检查清单，以及服务端事件追踪（PostHog、Segment）与身份标识密钥（identity key）最佳实践。

• 告警 —— 主动识别问题。涵盖四大黄金信号（延迟、流量、错误、饱和度）、awesome-prometheus-alerts 规则库（含约 500 条按技术栈分类的开箱即用规则）、Go 运行时告警（goroutine 泄漏、GC 压力、OOM 风险）、告警严重等级划分，以及常见破坏性错误（例如误用 irate 替代 rate、遗漏 for: 持续时间导致抖动告警）。

• Grafana 仪表盘 —— 预置 Go 运行时监控仪表盘（堆分配、GC 暂停频率、goroutine 数量、CPU 使用率）。说明应安装的标准仪表盘、如何定制适配自身服务，以及每类仪表盘所对应的典型运维问题。

信号关联

信号的价值在于彼此连接。日志中的 trace_id 可让你一键跳转至完整请求追踪链路；指标上的 exemplar 则能将延迟尖峰直接定位到引发该问题的具体 trace。

日志 + 追踪：otelslog 桥接器

import "go.opentelemetry.io/contrib/bridges/otelslog"

// 创建一个自动注入 trace_id 与 span_id 的 logger
logger := otelslog.NewHandler("my-service")
slog.SetDefault(slog.New(logger))

// 此后所有带 context 的 slog 调用均自动包含 trace 关联信息
slog.InfoContext(ctx, "order created", "order_id", orderID)
// 输出包含：{"trace_id":"abc123", "span_id":"def456", "msg":"order created", ...}

指标 + 追踪：Exemplars

// 记录 histogram 观测值时，附加 trace_id 作为 exemplar，
// 以便从 P99 尖峰直接跳转至引发问题的 trace
obs := histogram.WithLabelValues("POST", "/orders")
if eo, ok := obs.(prometheus.ExemplarObserver); ok {
    eo.ObserveWithExemplar(duration, prometheus.Labels{"trace_id": traceID})
} else {
    obs.Observe(duration)
}

迁移遗留日志器

若项目当前使用 zap、logrus 或 zerolog，请迁移到 log/slog。自 Go 1.21 起，slog 已成为标准库日志器，API 稳定，且整个生态已围绕其收敛。继续使用第三方日志器意味着维护额外依赖而无实质收益。

迁移策略：

1. 通过 slog.SetDefault() 引入 slog 作为新日志器
2. 迁移期间使用桥接 handler，将 slog 输出路由至现有日志器：samber/slog-zap、samber/slog-logrus、samber/slog-zerolog
3. 逐步将所有 zap.L().Info(...) / logrus.Info(...) / log.Info().Msg(...) 替换为 slog.Info(...)
4. 完全迁移完成后，移除桥接 handler 与旧日志器依赖

可观测性的“完成定义”（Definition of Done）

一项功能在具备可观测性前，不得视为生产就绪。在标记功能为“已完成”前，请验证以下各项：

• 指标已声明 —— 操作/错误计数器（Counter）、延迟直方图（Histogram）、饱和度瞬时值（Gauge）。每个指标变量声明上方均附有对应 PromQL 查询语句与告警规则注释。
• 日志符合规范 —— 使用 slog 输出结构化键值对；使用上下文变体（如 slog.InfoContext）；日志中不含 PII；错误必须仅被记录或仅被返回（严禁两者兼有）。
• 已创建 spans —— 每个服务方法、数据库查询、外部 API 调用均配有带相关属性的 span；错误通过 span.RecordError() 显式记录。
• 仪表盘与告警已就位 —— 指标注释中的 PromQL 已接入 Grafana 仪表盘与 Prometheus 告警规则。可参考 awesome-prometheus-alerts 获取覆盖基础设施依赖（数据库、缓存、消息中间件、代理等）的即用型规则。
• RUM 事件已追踪 —— 关键业务事件已在服务端追踪（PostHog/Segment）；身份标识密钥（identity key）为 user_id（非 email）；追踪前已校验用户同意状态。

常见错误

// ✗ 错误 —— 同时记录日志并返回错误（错误将在调用链上被重复记录）
if err != nil {
    slog.Error("query failed", "error", err)
    return fmt.Errorf("query: %w", err)
}

// ✓ 正确 —— 在顶层统一记录，返回时携带上下文信息
if err != nil {
    return fmt.Errorf("querying users: %w", err)
}

// ✗ 错误 —— 高基数标签（无界 user ID）
httpRequests.WithLabelValues(r.Method, r.URL.Path, userID).Inc()

// ✓ 正确 —— 仅使用有界标签值
httpRequests.WithLabelValues(r.Method, routePattern).Inc()

// ✗ 错误 —— 未传递 context（破坏 trace 传播）
result, err := db.Query("SELECT ...")

// ✓ 正确 —— context 全链路透传，trace 持续有效
result, err := db.QueryContext(ctx, "SELECT ...")

// ✗ 错误 —— 使用 Summary 记录延迟（无法跨实例聚合）
prometheus.NewSummary(prometheus.SummaryOpts{
    Name:       "http_request_duration_seconds",
    Objectives: map[float64]float64{0.99: 0.001},
})

// ✓ 正确 —— 使用 Histogram（支持聚合、兼容 histogram_quantile）
prometheus.NewHistogram(prometheus.HistogramOpts{
    Name:    "http_request_duration_seconds",
    Buckets: prometheus.DefBuckets,
})