Go 可观测性最佳实践
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/samber-cc-skills-golang-golang-observability。
技能介绍
生产里「看不见」比宕机更常见
Go 服务上线后,排障往往卡在:只有零散字符串日志、没有分位延迟指标、跨服务请求无法串成一条 trace,或者 pprof 只在本地开过。这类缺口不会让编译失败,却会让线上问题变成猜谜。
技能在做什么
该技能以 Go 可观测性工程师 人设工作,围绕五类互补信号:日志(log/slog 结构化)、指标(Prometheus,优先 Histogram)、链路(OpenTelemetry spans 与 context 传播)、剖析(pprof/Pyroscope,可用环境变量开关)、RUM(PostHog/Segment 等服务端事件与合规注意事项)。
默认 Coding / instrumentation 模式按顺序给新代码或存量代码补仪表:声明指标、打 span、结构化日志、接线 profiling。Review mode 针对 PR 检查新改动是否导出预期信号(指标是否声明、span 是否成对、日志字段是否一致)。Audit mode 会按信号类型并行审计覆盖率(metrics、logging、tracing、profiling、RUM),再合并结论;在 Claude Code 上需用 ultracode 显式启用多智能体编排。
内容还覆盖信号关联(日志注入 trace_id、指标 exemplar 链到 trace)、从 zap/logrus/zerolog 迁移到 slog 的步骤,以及「功能完成前必须可观测」的检查清单(PromQL 注释、告警、仪表盘、RUM 身份键与同意检查等)。
边界与注意
指标标签必须控制基数,避免把用户 ID、完整 URL 等无界值塞进 label。Tracing 在规模上需要采样策略,不能全量采集。Profiling 与日志需注意鉴权与 PII;具体安全做法见关联的 golang-security 技能。库 API 以 Prometheus client、OpenTelemetry SDK 等官方文档为准;Go 1.26+ 简单多 handler 场景优先 slog.NewMultiHandler。
使用场景
- 新 HTTP 接口合并前,要补 latency/error 指标、结构化日志和 OpenTelemetry span
- 审查同事 PR 时,核对新增代码是否声明指标且 span 正确关闭
- 上线前对仓库做可观测性覆盖率审计,分别检查 metrics、日志、trace、pprof、RUM
- 老项目仍用 zap/logrus,需要按步骤迁到 log/slog 并保持过渡期可输出
适合人员
- 维护 Go 微服务的后端工程师,要求每个 HTTP 端点具备延迟与错误率指标
- 负责合并前质量门的 SRE,需要按清单检查 PR 里的仪表与日志是否达标
- 准备上生产的技术负责人,要对全库五类信号做并行覆盖率审计并汇总缺口
- 运营同一代码库的平台工程师,正在统一日志栈并降低 Prometheus 高基数 label 风险