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_total | Counter | method、route、status_class | 请求速率与错误率 |
http_server_request_duration_seconds | Histogram | method、route | 时延分布与分位估计 |
http_server_active_requests | Gauge | 可选 method | 当前并发与饱和度 |
http_server_response_size_bytes | Histogram | route | 响应体是否影响带宽或内存 |
build_info | Gauge | version、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: 10sServiceMonitor 的 endpoints[].port 引用的是 Service 端口名,不是容器端口数字。除此之外,还要同时检查三层选择关系:
- Service 的 selector 是否选中正确 Pod;
- ServiceMonitor 的 selector 是否选中正确 Service;
- Prometheus 实例的
serviceMonitorSelector与serviceMonitorNamespaceSelector是否选中该 ServiceMonitor。
如果平台已经使用 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 中存在目标 Pod | Service 没有选中后端 |
| 上线后 | Prometheus Targets 中目标为 UP | 抓取路径、端口或网络错误 |
| 上线后 | 原始 Counter 持续变化 | 应用埋点或抓取仍有问题 |
| 上线后 | Recording Rule、Dashboard 和 Data Link 正常 | 查询链或跳转配置错误 |
最后再发送少量合成请求,分别覆盖成功、失败和慢请求路径,确认请求速率、错误率与时延按预期变化。不要一开始就用 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。
公开参考
这篇文章的关键技术边界都可以从以下公开文档继续核对。