Go 服务指标工程:用 RED、Histogram 和 ServiceMonitor 建立可验证合同

Go 服务指标工程:用 RED、Histogram 和 ServiceMonitor 建立可验证合同

Hello,我是小兔大白糖。 一个 Go 进程能够启动,只能证明代码暂时跑起来了。想让服务在 Kubernetes 里可运营,还要回答三个问题:请求有没有变慢或失败,Prometheus 是否真的抓到了这些信号,异常出现后能否从应用一路下钻到 Workload、Pod 和日志。

本文把这三件事连成一条可验证的链路:应用用 client_golang 产生稳定的 RED 指标,Prometheus Operator 通过 ServiceMonitor 发现目标,Grafana 再把应用指标与 Kubernetes 运行状态放进同一调查入口。

【示例场景·合成数据】
文中的服务名、路由、拓扑和阈值均为合成示例,不对应任何组织、产品或实际事件。账号、区域、规格、真实资源名、域名、容量、请求规模和成本均不出现。

估计阅读时间:18 分钟


先定边界:RED 说明请求结果,资源指标帮助解释原因

应用 RED 与 Kubernetes 资源状态应该出现在同一调查入口,但两者不能互相替代。

RED 是请求驱动服务最小的一组健康信号:

  • Rate:单位时间内处理了多少请求;
  • Errors:多少请求失败,或失败占比是多少;
  • Duration:请求时延如何分布,而不只是平均值。

RED 回答的是「用户请求经历了什么」。CPU、内存、Pod Ready、重启和 OOM 回答的是「运行环境发生了什么」。CPU 平稳不能证明接口成功,错误率上升也不能直接证明 CPU 是根因。

异步 Worker 仍可沿用这个模型:Rate 映射为处理速率,Errors 映射为失败率,Duration 映射为处理时长;然后再增加队列深度、最老消息年龄和并发槽位,描述离处理上限还有多远。

观察对象优先回答的问题常见信号
HTTP 或 RPC 请求用户是否收到成功、及时的响应Rate、错误率、时延分布
异步 Worker任务是否持续被消费并完成处理速率、失败率、处理时长
运行环境应用为什么变慢、失败或退出CPU、throttle、内存、重启、Ready
饱和度系统离上限还有多远活动请求、队列年龄、连接池、并发槽位

指标合同先于 Dashboard:名称、类型和标签必须稳定

先把指标语义写成合同,再做 Dashboard;否则面板越多,错误口径越难清理。

【目标设计】
每个 Go HTTP 服务至少统一请求总数、请求时延和活动请求数,并保留 Go Runtime 与进程指标。额外指标只有在明确回答容量或排障问题时才启用。

指标类型建议标签回答的问题
http_server_requests_totalCountermethod、route、status_class请求速率与错误率
http_server_request_duration_secondsHistogrammethod、route时延分布与分位估计
http_server_active_requestsGauge可选 method当前并发与饱和度
http_server_response_size_bytesHistogramroute响应体是否影响带宽或内存
build_infoGaugeversion、revision当前运行版本
Go 与进程默认指标Counter / Gauge不增加业务标签GC、内存、线程与进程状态

这里最重要的字段是 route。它必须使用路由模板,例如 /users/:id,不能直接记录原始 URL。未匹配路由也要收敛为固定值,不能退回到原始路径。

user_id、request_id、trace_id 和完整错误文本都不能成为 Prometheus Label。这些值几乎不受控,会让时序数量按标签组合成倍增长。需要保留单次请求上下文时,应把它放到日志或 Trace。

【经验建议】
新增 Label 前先列出它的值域、保留周期和查询用途。如果无法给出稳定上限,就不要把它放进指标。高基数不是 Dashboard 慢一点,而是采集、存储和查询成本一起上升。

Go 埋点要交给 client_golang,暴露端点交给 promhttp

使用 client_golang 的 Collector 与 promhttp 暴露指标,不要手写 Prometheus 文本协议。

下面的核心注册代码使用独立 Registry,并显式保留 Go Runtime 与 Process Collector:

package metrics
 
import (
	"net/http"
 
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/collectors"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)
 
var (
	requests = prometheus.NewCounterVec(
		prometheus.CounterOpts{Name: "http_server_requests_total"},
		[]string{"method", "route", "status_class"})
	duration = prometheus.NewHistogramVec(
		prometheus.HistogramOpts{Name: "http_server_request_duration_seconds",
			Buckets: prometheus.DefBuckets},
		[]string{"method", "route"})
	inflight = prometheus.NewGauge(
		prometheus.GaugeOpts{Name: "http_server_active_requests"})
)
 
func Handler() http.Handler {
	r := prometheus.NewRegistry()
	r.MustRegister(requests, duration, inflight,
		collectors.NewGoCollector(),
		collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}))
	return promhttp.HandlerFor(r,
		promhttp.HandlerOpts{EnableOpenMetrics: true})
}

如果应用直接使用默认 Registry,promhttp.Handler() 就能暴露默认 Gatherer 中已注册的指标。使用独立 Registry 时,则应像示例一样调用 promhttp.HandlerFor();两种方式不要混用,否则容易出现重复注册或指标缺失。

HTTP Middleware 至少要完成四件事:请求进入时增加活动请求数,退出时减少;记录最终状态码;从框架读取路由模板;用单调时钟计算耗时。Counter 必须统计全部请求,不能只在成功后递增。

普通的 Observe() 不会自动从 OpenTelemetry Context 附加 Trace ID。要让 RED Histogram 产生 Exemplar,中间件需要显式调用 Exemplar API:

func observeDuration(
	ctx context.Context,
	observer prometheus.Observer,
	seconds float64,
) {
	sc := trace.SpanContextFromContext(ctx)
	eo, ok := observer.(prometheus.ExemplarObserver)
	if !ok || !sc.IsSampled() {
		observer.Observe(seconds)
		return
	}
	eo.ObserveWithExemplar(seconds, prometheus.Labels{
		"trace_id": sc.TraceID().String(),
	})
}

这里的 trace 来自 OpenTelemetry Go API。只有预计会导出并保留的采样 Trace 才附加 ID;否则 Exemplar 会指向不存在的 Trace。Handler 还要启用 OpenMetrics,并验证 Prometheus 抓取链确实协商、保存了 Exemplar。

生产实现还要单独处理 panic、流式响应、WebSocket 升级和未匹配路由。WebSocket 的 HTTP Duration 只覆盖握手,不能代表连接生命周期;连接数、连接时长、异常关闭和消息处理错误应使用独立指标。

Histogram 的桶决定精度,也决定时序数量

Histogram Bucket 要围绕服务目标和真实延迟分布设计,默认桶只能作为起点。

每个 Bucket 都会生成一条带 le 标签的累计时序。桶越多,分位估计可能越细,但时序数量和查询开销也越高。不同延迟语义的请求不应为了省指标名而强塞进同一个 Histogram。

【示例场景·合成数据】
如果一个接口的目标阈值在亚秒级,可以在阈值前后增加边界;如果某类外部计算通常持续数秒甚至更久,就需要另一组桶。具体边界应由目标与观测分布共同决定,不应照抄示例。

经典 Histogram 的高分位查询要先按 le 和所需业务维度聚合,再调用 histogram_quantile():

histogram_quantile(
  0.99,
  sum by (le, route) (
    rate(http_server_request_duration_seconds_bucket[5m])
  )
)

这个 P99 是基于 Bucket 的估计,不是从原始请求样本中精确排序得到的结果。低流量窗口中的分位还会明显波动,所以告警必须同时设置最小请求量或持续时间条件。

修改 Bucket 会改变时序集合,应该按指标合同变更处理。发布前要检查 Recording Rule、Dashboard 和告警是否仍按相同边界解释数据。

ServiceMonitor 只声明发现规则,不会替你创建采集目标

ServiceMonitor 通过 Service Label 和端口名发现目标;它不是网络代理,也不会增加业务 Pod。

【示例架构·当前实现】
以下 YAML 只展示 Service 与 ServiceMonitor 的最小连接关系。名称均为占位示例,省略了与本文无关的部署字段。

apiVersion: v1
kind: Service
metadata:
  name: example-api
  labels:
    app.kubernetes.io/name: example-api
spec:
  selector:
    app.kubernetes.io/name: example-api
  ports:
    - name: metrics
      port: 8080
      targetPort: metrics
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: example-api
  labels:
    monitoring: platform
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: example-api
  endpoints:
    - port: metrics
      path: /metrics
      interval: 30s
      scrapeTimeout: 10s

ServiceMonitor 的 endpoints[].port 引用的是 Service 端口名,不是容器端口数字。除此之外,还要同时检查三层选择关系:

  1. Service 的 selector 是否选中正确 Pod;
  2. ServiceMonitor 的 selector 是否选中正确 Service;
  3. Prometheus 实例的 serviceMonitorSelector 与 serviceMonitorNamespaceSelector 是否选中该 ServiceMonitor。
Go 服务指标从埋点到 ServiceMonitor 和 Prometheus 的采集合同
Go 服务指标从埋点到 ServiceMonitor 和 Prometheus 的采集合同 · 点击查看 SVG 原图

如果平台已经使用 Prometheus Operator,ServiceMonitor 通常更容易审核和复用;没有 Operator、且已有统一 Annotation Discovery 时,Annotation 可以减少 CRD 依赖;没有稳定 Service 的 Pod 可使用 PodMonitor;外部目标则按平台能力选择 Probe、ScrapeConfig 或静态发现。

这些方案没有脱离上下文的唯一最优解,但同一个目标不应被两套发现方式重复抓取。

统一 Dashboard 要合并调查入口,不要混淆指标语义

把应用 RED、Workload/Pod 状态和调查链接放在同一张看板,目的是减少切换,不是把不同语义压成一个健康分。

一张面向后端、SRE 与 DevOps 的统一应用看板,可以按下面五行组织:

行内容主要用途
服务概览请求速率、错误率、P50/P95/P99、活动请求判断用户影响
接口明细按 route、method、status_class 分组找到异常接口
运行状态可用副本、Pod Ready、重启、OOM、部署版本判断发布与运行状态
资源与饱和度CPU、throttle、内存 working set、request/limit、网络解释资源瓶颈
调查入口日志、Trace、Workload 与 Pod 下钻链接延续证据链

请求速率、错误率与经典 Histogram 分位可以从下面三类查询起步:

sum by (route) (
  rate(http_server_requests_total{service="$service"}[5m])
)

(
  sum(rate(http_server_requests_total{
    service="$service", status_class="5xx"}[5m]))
  or on()
  0 * sum(rate(http_server_requests_total{
    service="$service"}[5m]))
)
/
clamp_min(sum(rate(http_server_requests_total{
  service="$service"}[5m])), 1e-9)

or on() 0 * 总请求 只在总请求时序存在时补出零错误。总请求本身消失时,结果仍是 No Data,不会被伪装成 0%;Target 缺失和抓取失败应由 up、absent() 或独立数据完整性规则监控。

CPU throttle 比例要比较被节流周期与总周期,不能只看 CPU 使用量。内存则应同时展示 working set、request 和 limit;只显示一个百分比,会掩盖「使用量稳定但离上限太近」的风险。

变量可以统一为 environment、namespace、service、workload 和 route。开启 All 前要检查正则范围,避免一次选择触发跨环境、跨命名空间的大查询。

不要复制现有 Kubernetes Dashboard 的 JSON 再改一份。更稳妥的方式是新建应用看板,复用同一数据源、查询片段或 Data Link,保留原有集群看板的职责边界。

上线前验证合同,上线后验证整条采集链

大部分错误可以在上线前发现;只有目标发现和真实抓取必须在目标集群验证。

阶段验证项失败通常说明什么
上线前Counter、状态码、路由模板的单元测试Middleware 语义错误
上线前本地请求 /metrics,执行 promtool check metrics暴露格式或注册错误
上线前校验 Service 与 ServiceMonitor selector标签合同不一致
上线前对测试数据执行 PromQL 与 Dashboard 查询聚合维度或变量错误
上线后EndpointSlice 中存在目标 PodService 没有选中后端
上线后Prometheus Targets 中目标为 UP抓取路径、端口或网络错误
上线后原始 Counter 持续变化应用埋点或抓取仍有问题
上线后Recording Rule、Dashboard 和 Data Link 正常查询链或跳转配置错误
Go 服务指标在上线前和上线后的分阶段验证路径
Go 服务指标在上线前和上线后的分阶段验证路径 · 点击查看 SVG 原图

最后再发送少量合成请求,分别覆盖成功、失败和慢请求路径,确认请求速率、错误率与时延按预期变化。不要一开始就用 Dashboard 结果反推所有环节;从原始 Counter 向上验证,定位会更直接。

常见失败大多发生在合同接缝处

最难排查的往往不是某个组件完全不可用,而是相邻组件对名称和语义的理解不一致。

  • /metrics 与业务端口共用,却被认证中间件拦截;
  • ServiceMonitor 选择了错误的 Service Label;
  • ServiceMonitor 端口填写成数字,没有引用 Service 端口名;
  • Middleware 使用原始 URL,制造高基数时序;
  • Counter 名为 *_total,代码却只统计成功请求;
  • 业务失败全部映射成 HTTP 200,HTTP 错误率因此不可见;
  • Histogram Bucket 与服务目标不匹配;
  • 应用指标复用了 job、instance、service 或 endpoint 等采集拓扑标签,出现 exported_*;
  • Dashboard 只有 CPU 和内存,没有应用 RED;
  • 同一目标同时被 Annotation Discovery 与 ServiceMonitor 抓取,产生重复时序。

看到 exported_* 时,应先检查应用 Label 与 Target Label 的冲突,而不是让 Dashboard 永久兼容错误命名。应用 Label 要表达业务语义;采集拓扑标签交给 Prometheus 抓取配置管理。

小结

一套可靠的 Go 服务指标链路,本质上是从代码、发现、查询到 Dashboard 都遵守同一份可验证合同。

  • RED 描述用户请求结果,Kubernetes 指标提供运行状态和根因线索;
  • 使用 client_golang 与 promhttp,不要手写 Prometheus exposition;
  • Histogram Bucket 同时影响分位精度和时序成本,修改时按合同变更处理;
  • 路由模板与低基数 Label 比「多采几个字段」更重要;
  • ServiceMonitor 声明目标发现规则,不创建 Service、Pod 或网络代理;
  • 统一应用与 Kubernetes 看板,但保留各层信号的职责边界;
  • 上线前验证埋点、格式、selector 和 PromQL,上线后再验证 EndpointSlice、Target 与 Dashboard。

公开参考

这篇文章的关键技术边界都可以从以下公开文档继续核对。