go服务必须暴露/metrics端点，因prometheus采用拉模型，仅通过http get抓取数据；未暴露或格式不符则无法采集，导致targets显示down、指标缺失标签等故障。
Go语言集成Prometheus监控不是“学完再用”的环节，而是云原生开发中从第一天写 main() 就该嵌入的实践习惯。不提前暴露指标，后续排查 CPU 暴涨、Goroutine 泄漏、HTTP 超时等问题，基本靠猜。
为什么 Go 服务必须自己暴露 /metrics 端点
Prometheus 是拉模型（pull-based），它不会主动连接你的服务并“要求”你上报数据；它只会在配置好的时间点，向 /metrics 发起 HTTP GET 请求。如果 Go 服务没启动这个端点，或者返回格式不符合 OpenMetrics 规范，Prometheus 就收不到任何数据——连 up{job="myapp"} == 0 这种基础存活信号都没有。
常见错误现象：
- Prometheus UI 的 Targets 页面显示
DOWN，状态为context deadline exceeded或server returned HTTP status 404 - 日志里看到
http: superfluous response.WriteHeader call—— 通常是 handler 中手动写了 header 又调用了http.Error或重复WriteHeader - 指标在 Prometheus 查询界面能查到，但所有标签值都是空的，比如
http_requests_total{} 123（缺少method、status等 label）
实操建议：
- 用官方库
github.com/prometheus/client_golang/prometheus/promhttp，直接注册promhttp.Handler()，不要自己拼字符串响应 - 确保
http.Handle("/metrics", promhttp.Handler())在http.ListenAndServe之前执行 - 若服务已有路由框架（如 Gin、Echo），需显式挂载
promhttp.Handler()到对应路径，避免被中间件拦截或重写状态码
自定义指标注册时 label 数量与 cardinality 风险
给指标加 label 看似灵活，但 label 值来自请求路径、用户 ID、trace ID 等动态字段时，会快速引发高基数（high cardinality）问题：单个指标生成成千上万个时间序列，吃光 Prometheus 内存和磁盘，甚至触发 target failed: context canceled。
使用场景对比：
- 安全：用固定 label，如
env="prod"、service="auth"、version="v1.2.0" - 危险：用
user_id="123456789"、request_id="req_abcde"、path="/user/:id"（未做聚合）
实操建议：
- 用
prometheus.NewCounterVec或NewHistogramVec定义带 label 的指标时，label 名称必须是预设的、有限集合，不能动态生成 - 对 URL 路径类指标，先做归一化：把
/api/user/123→/api/user/{id}，再作为 label 值 - 上线前用
prometheus_tsdb_head_series和prometheus_target_metadata_cache_entries监控实际 series 数量，阈值建议控制在 10 万以内（视 Prometheus 实例资源配置而定）
Gin/Echo 等 Web 框架中自动采集 HTTP 指标的方法
手写中间件统计 http_request_duration_seconds 很容易漏掉 panic 恢复、流式响应、重定向等边界情况。官方 client_golang 不提供开箱即用的框架适配器，但社区方案已较稳定。
常见错误现象：
- 延迟直方图中
le="0.1"分位数始终为 0，因为中间件没正确记录结束时间 - 状态码统计缺失
500，因 panic 后未触发 defer 计数器 +1 - Gin 日志中间件和指标中间件顺序错乱，导致
status标签取不到真实响应码
实操建议：
- Gin 用户优先用
github.com/zsais/go-gin-prometheus，它自动处理 defer、recover、流响应，并支持 path 模板提取（需配合gin.Engine.Use()注册） - Echo 用户可用
github.com/labstack/echo-contrib/prometheus，注意初始化时传入Subsystem和Registerer，避免与默认注册器冲突 - 无论用哪个库，都应在
prometheus.MustRegister()后再启动服务，否则指标不会出现在/metrics输出中
真正容易被忽略的是：指标暴露本身不等于可观测。一个只有 go_goroutines 和 http_requests_total 的服务，在 K8s 里扩到 50 个 Pod 后，你根本分不清是某个实例卡死，还是整体流量突增。必须结合业务语义打标（比如 payment_status="failed"）、设置合理告警规则（而非只看 rate() 上升）、并在 Grafana 里按 pod + container + service 多维下钻——这些动作，比选对第一个 CounterVec 更决定监控是否有效。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
