Prometheus Go 代码审查

审查清单

• - [ ] 指标类型与测量语义匹配（计数器/仪表盘/直方图）
• [ ] 标签具有低基数（无用户ID、时间戳、路径）
• [ ] 指标名称遵循约定（蛇形命名法、单位后缀）
• [ ] 直方图使用适当的桶边界
• [ ] 指标只注册一次，而非每次请求
• [ ] 采集器在竞态条件下不会崩溃
• [ ] /metrics 端点已暴露并可访问

指标类型选择

关键反模式

1. 高基数标签

go
// 错误 - 每个用户/请求唯一
counter := promauto.NewCounterVec(
prometheus.CounterOpts{Name: requests_total},
[]string{user_id, path}, // 数百万个序列！
)
counter.WithLabelValues(userID, request.URL.Path).Inc()

// 正确 - 有界的标签值
counter := promauto.NewCounterVec(
prometheus.CounterOpts{Name: requests_total},
[]string{method, status_code}, // <100个序列
)
counter.WithLabelValues(r.Method, statusCode).Inc()

2. 错误的指标类型

go
// 错误 - 对单调递增的值使用仪表盘
requestCount := promauto.NewGauge(prometheus.GaugeOpts{
Name: http_requests,
})
requestCount.Inc() // 应该使用计数器！

// 正确
requestCount := promauto.NewCounter(prometheus.CounterOpts{
Name: httprequeststotal,
})
requestCount.Inc()

3. 每次请求注册

go
// 错误 - 每次请求创建新指标
func handler(w http.ResponseWriter, r *http.Request) {
counter := prometheus.NewCounter(...) // 每次都创建新的！
prometheus.MustRegister(counter) // 重复时崩溃！
}

// 正确 - 只注册一次
var requestCounter = promauto.NewCounter(prometheus.CounterOpts{
Name: httprequeststotal,
})

func handler(w http.ResponseWriter, r *http.Request) {
requestCounter.Inc()
}

4. 缺少单位后缀

go
// 错误
duration := promauto.NewHistogram(prometheus.HistogramOpts{
Name: request_duration, // 没有单位！
})

// 正确
duration := promauto.NewHistogram(prometheus.HistogramOpts{
Name: requestdurationseconds, // 名称中包含单位
})

良好模式

指标定义

go
var (
httpRequests = promauto.NewCounterVec(
prometheus.CounterOpts{
Namespace: myapp,
Subsystem: http,
Name: requests_total,
Help: 处理的HTTP请求总数,
},
[]string{method, status},
)

httpDuration = promauto.NewHistogramVec(
prometheus.HistogramOpts{
Namespace: myapp,
Subsystem: http,
Name: requestdurationseconds,
Help: HTTP请求延迟,
Buckets: []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10},
},
[]string{method},
)
)

中间件模式

go
func metricsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
timer := prometheus.NewTimer(httpDuration.WithLabelValues(r.Method))
defer timer.ObserveDuration()

wrapped := &responseWriter{ResponseWriter: w, status: 200}
next.ServeHTTP(wrapped, r)

httpRequests.WithLabelValues(r.Method, strconv.Itoa(wrapped.status)).Inc()
})
}

暴露指标

go
import github.com/prometheus/client_golang/prometheus/promhttp

func main() {
http.Handle(/metrics, promhttp.Handler())
http.ListenAndServe(:9090, nil)
}

审查问题

1. 1. 指标类型是否正确（计数器 vs 仪表盘 vs 直方图）？
2. 标签值是否有界（无UUID、时间戳、路径）？
3. 指标名称是否包含单位（seconds、bytes）？
4. 指标是否只注册一次（而非每次请求）？
5. /metrics 端点是否正确暴露？