Gin服务需手动集成Prometheus客户端，核心是用promhttp.HandlerFor包裹独立Registry并全局复用，通过ResponseWriter包装器准确捕获状态码与延迟，指标命名遵循规范、标签精简可控。
如何让Gin服务主动上报指标到Prometheus
Gin本身不内置指标暴露能力，必须手动集成Prometheus客户端。关键不是“加个中间件”，而是确保http.Handler被promhttp.Handler()包裹，并且所有业务路由都走同一套注册逻辑。
常见错误是只对/metrics路径挂载promhttp.Handler()，但忘了把Gin的Engine作为子路由嵌入——结果指标永远为空。
- 用
prometheus.NewRegistry()新建独立注册器，避免和全局冲突 - 调用
promauto.With(registry)创建指标，比直接NewCounter更安全（自动注册） - 在Gin启动前，用
http.Handle("/metrics", promhttp.HandlerFor(registry, promhttp.HandlerOpts{}))注册，不要用gin.Engine.GET - HTTP中间件里调用
counterVec.WithLabelValues(c.Request.Method, c.Request.URL.Path).Inc()，注意路径要标准化（如/user/:id统一为/user/{id}）
Gin中间件中采集延迟和状态码的正确姿势
延迟不能靠time.Since()粗略算，状态码不能依赖c.Writer.Status()在defer里读——因为Gin可能已提前写头、或panic导致状态未更新。
必须用gin.ResponseWriter包装器劫持WriteHeader调用，才能捕获最终状态码。
- 定义结构体嵌入
gin.ResponseWriter，重写WriteHeader(code int)方法，在其中记录code并调用原WriteHeader - 在中间件开头用
startTime := time.Now()，结尾用elapsed := time.Since(startTime).Seconds()，单位固定为秒（Prometheus直采） - 延迟直方图用
prometheus.NewHistogramVec，Buckets建议设为[]float64{0.01, 0.05, 0.1, 0.2, 0.5, 1, 2, 5}（单位秒） - 别把
c.Request.RemoteAddr当用户标识——它可能是反向代理IP；真要区分来源，得从X-Forwarded-For或认证头取
为什么Gin服务重启后Prometheus抓不到指标
根本原因不是配置错，而是registry生命周期没管好：每次热重载都新建Registry，旧指标还在内存但不再暴露，Prometheus抓到空响应。
更隐蔽的问题是，多个Gin实例（如多worker）共用一个Registry却没加锁，计数器会乱。
- 把
Registry声明为包级变量，初始化一次，所有HTTP handler复用它 - 避免在
init()里注册指标——Gin启动前可能还没加载完，改用var once sync.Once+once.Do(initMetrics) - 若用supervisord/systemd管理进程，确认
KillSignal=SIGTERM，让Gin有机会执行registry.Unregister()清理（虽然通常不必要） - Prometheus配置里的
scrape_timeout不能小于Gin服务响应/metrics的实际耗时，否则报context deadline exceeded
对接Grafana看板时，Gin指标命名和标签怎么设计才不踩坑
命名不是越详细越好，gin_http_request_duration_seconds_bucket这种是标准，但自己加的业务指标如user_login_total必须带_total后缀，否则Grafana的rate()函数会失效。
标签太多会导致cardinality爆炸，查起来慢甚至OOM；太少又没法下钻分析。
- 强制保留3个基础标签：
method（GET/POST）、path（模板化，非原始URL）、status_code（数字，非字符串） - 业务标签如
service_name、env必须从环境变量注入，禁止硬编码；用prometheus.Labels{"env": os.Getenv("ENV")}传给WithLabelValues - 避免用用户ID、订单号这类高基数字段做标签——改用
sum by (path) (rate(gin_http_requests_total[5m]))聚合后再关联日志查详情 - Grafana里写查询时，
rate(gin_http_requests_total[5m])比irate更稳，后者对瞬时抖动敏感，微服务里容易误告
最常被忽略的是指标生命周期——上线新路径后，旧path标签不会自动消失，Prometheus会一直存着零值样本，直到被TSDB压缩策略清理。如果看板里突然多出一堆/v1/old_api曲线，不是数据错了，是没人动过它。
