Go OpenTelemetry 指标实战:Counter、Gauge、Histogram 一次讲透
在 Go 应用中用 OpenTelemetry 记录并导出业务与运行时指标:HTTP 服务器自动指标、Counter 计数、UpDownCounter 升降计数、Gauge 瞬时值、Histogram 分布统计,以及如何用 View 裁剪无用指标。指标最终导入观测云统一监控告警。
OpenTelemetry Go 指标 API 提供四种核心仪器——Counter、UpDownCounter、Gauge、Histogram,分别对应"只增计数、可增可减、瞬时快照、分布统计"四类场景——选对仪器是指标设计的第一步,选错了会导致数据语义混乱、无法正确聚合。
核心要点速览
- otelhttp 包装 Handler 后产出 HTTP 耗时直方图等服务端指标,可用直方图 Count 查看已记录的请求次数;
- Counter 记总量、UpDownCounter 记当前在制品、Gauge 记瞬时值、Histogram 记分布;
- 用 View 按名称丢弃无用指标流,或过滤保留指标的属性;用实际时序数与计量规则核对影响;
- 先用本机 Collector 核对 OTLP 数据,再按实际配置接入观测云 DataKit。
初始化 MeterProvider
示例使用 Go 1.26、OpenTelemetry Go SDK 1.47.0、Go contrib 0.72.0 和 Collector Contrib 0.165.0。先将接收配置保存为 collector.yaml,运行 otelcol-contrib --config=collector.yaml。debug 导出器会打印收到的指标。
receivers:
otlp:
protocols:
grpc:
endpoint: 127.0.0.1:14317
exporters:
debug:
verbosity: detailed
service:
pipelines:
metrics:
receivers: [otlp]
exporters: [debug]
在空目录安装依赖,把 Go 示例保存为 main.go,执行 go run .。
go mod init example.com/otel-order-metrics
go get go.opentelemetry.io/otel/metric@v1.47.0 \
go.opentelemetry.io/otel/sdk@v1.47.0 \
go.opentelemetry.io/otel/sdk/metric@v1.47.0 \
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc@v1.47.0 \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.72.0 \
go.opentelemetry.io/contrib/instrumentation/runtime@v0.72.0
package main
import (
"context"
"errors"
"fmt"
"io"
"log"
"net/http"
"net/http/httptest"
"strings"
"time"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
otelruntime "go.opentelemetry.io/contrib/instrumentation/runtime"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
"go.opentelemetry.io/otel/metric"
sdkmetric "go.opentelemetry.io/otel/sdk/metric"
"go.opentelemetry.io/otel/sdk/resource"
)
func orderHandler(meter metric.Meter) (http.Handler, error) {
created, err := meter.Int64Counter("orders.created", metric.WithUnit("{order}"))
if err != nil {
return nil, err
}
inFlight, err := meter.Int64UpDownCounter("orders.inflight", metric.WithUnit("{request}"))
if err != nil {
return nil, err
}
queueDepth, err := meter.Int64Gauge("orders.queue.depth", metric.WithUnit("{order}"))
if err != nil {
return nil, err
}
duration, err := meter.Float64Histogram("orders.process.duration", metric.WithUnit("s"),
metric.WithExplicitBucketBoundaries(0.05, 0.1, 0.25, 0.5, 1, 5))
if err != nil {
return nil, err
}
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
started := time.Now()
inFlight.Add(ctx, 1)
defer inFlight.Add(ctx, -1)
defer func() { duration.Record(ctx, time.Since(started).Seconds()) }()
queueDepth.Record(ctx, 2)
if _, err := io.Copy(io.Discard, r.Body); err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
if r.URL.Query().Get("fail") == "1" {
w.WriteHeader(http.StatusServiceUnavailable)
return
}
created.Add(ctx, 1, metric.WithAttributes(attribute.String("channel", "app")))
w.WriteHeader(http.StatusCreated)
}), nil
}
func run() (err error) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
exporter, err := otlpmetricgrpc.New(ctx, otlpmetricgrpc.WithEndpoint("127.0.0.1:14317"),
otlpmetricgrpc.WithInsecure())
if err != nil {
return err
}
mp := sdkmetric.NewMeterProvider(
sdkmetric.WithResource(resource.NewSchemaless(attribute.String("service.name", "order-service"))),
sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter, sdkmetric.WithInterval(30*time.Second))),
sdkmetric.WithView(sdkmetric.NewView(
sdkmetric.Instrument{Name: "http.server.request.body.size"},
sdkmetric.Stream{Aggregation: sdkmetric.AggregationDrop{}},
)),
)
defer func() {
shutdownCtx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
err = errors.Join(err, mp.Shutdown(shutdownCtx))
}()
if err := otelruntime.Start(otelruntime.WithMeterProvider(mp)); err != nil {
return err
}
const route = "/orders"
handler, err := orderHandler(mp.Meter("example.com/order-service"))
if err != nil {
return err
}
mux := http.NewServeMux()
mux.Handle("POST "+route, otelhttp.NewHandler(
handler, route, otelhttp.WithMeterProvider(mp),
))
server := httptest.NewServer(mux)
defer server.Close()
for _, suffix := range []string{"", "?fail=1"} {
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
server.URL+route+suffix, strings.NewReader("demo"))
if err != nil {
return err
}
resp, err := server.Client().Do(req)
if err != nil {
return err
}
resp.Body.Close()
fmt.Println(resp.StatusCode)
}
return nil
}
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
WithInsecure() 会禁用传输层保护,只在这个本机回环示例中使用。远端部署应配置实际接收地址、TLS 和认证。进程运行时按 30 秒周期收集;短示例先关闭测试 HTTP 服务,再用独立超时调用 Shutdown 做最后一次收集并检查结果。
HTTP 服务器自动指标
otelhttp.NewHandler 包装后,http.server.request.duration 直方图会记录已完成的埋点请求,可按相同维度用 Count 得到请求次数。示例输出 201 和 503,各对应一次耗时观测,http.route 为 /orders。它们和业务 Counter 的计数口径不同,后者只记录一次订单创建。
示例中的 View 丢弃 http.server.request.body.size,保留响应体大小和耗时。只想减掉某些属性时,可以用 View 属性过滤,先确认剩余维度能满足查询。
四种仪器的正确用法
Counter(只增)——请求总量、错误总数、订单创建数。示例只有返回 201 的请求更新 orders.created,属性为 channel=app。
UpDownCounter(可增可减)——当前处理中的请求数、队列积压。进入处理时加一,退出时用相同属性减一,两次请求结束后读到零。
Gauge(瞬时值)——温度、当前内存、在线人数。同步 Int64Gauge 记录采样时刻的值,示例用固定值 2 演示队列深度。需要收集时读取当前值,可以用 ObservableGauge。
Histogram(分布)——响应耗时、订单金额。示例用秒记录耗时,250 ms 对应 0.25 的桶边界。P95 是基于桶计数的估算,精度取决于桶分辨率。跨实例汇总时要使用兼容的桶布局,在后端合并分布后估算分位数。
指标命名与属性规范
名称用点分小写(orders.created),单位用 WithUnit 显式声明(UCUM 标准,秒为 s、字节为 By);属性只放聚合维度(渠道、地区),绝不放请求级 ID——那是高基数问题的头号来源。
验证业务指标上报
启用观测云 DataKit 的 OpenTelemetry 输入,让 Go exporter 的协议和接收端实际监听地址一致。若改用 OTLP/HTTP,应使用 Protobuf 格式的 HTTP exporter,按配置设置指标路径。DataKit 文档中的默认 HTTP 端口为 9529,默认指标路径为 /otel/v1/metrics。触发固定次数的订单创建,核对接收后的指标名、Counter 增量、单位、属性和直方图表示。再重启一个测试实例,检查所用查询怎样处理计数器归零。DataKit OpenTelemetry 接收端
需要按指标查同时间的链路时,先统一服务名和环境标签,并确认请求的 Span 已采集;单条聚合指标通常不能唯一指向一条 Trace。
常见问题(FAQ)
Q:Counter 重启归零怎么办? 累积型 OTLP 数据点可以带起始时间。进程重启后重新累计,后端查询需正确处理重置。使用 Delta 时,每个点描述对应区间的增量。用测试实例重启验证速率结果。
Q:Histogram 和 Summary 选哪个? 需要跨实例估算分位数时,可将兼容的 Histogram 桶聚合。客户端算出的 Summary 分位数无法直接合成整体分位数,Go Metrics API 的分布仪器是 Histogram。
Q:指标上报间隔多久合适? 本例设为 30 秒。根据告警窗口、接收端容量和所需的数据时效选择,缩短周期会增加发送批次数,开销需按实际负载核对。
Q:Go 运行时指标(GC、goroutine)怎么拿? 用示例中的 runtime.Start 并传入同一 MeterProvider,当前版本包括 go.goroutine.count 和 go.memory.gc.goal 等指标。若需要调度等待时间直方图 go.schedule.duration,在 Reader 配置 runtime.NewProducer()。Go 运行时埋点文档
系列阅读
- 上一篇:《Go OpenTelemetry 链路追踪》
- 下一篇:《Node.js OpenTelemetry 监控》
- 相关:《OpenTelemetry 指标详解》 · 《OpenTelemetry 指标 vs Prometheus 指标》 · 《返回索引》
参考:Go Metrics SDK 和 View · HTTP 指标语义约定 · OTLP 指标数据模型 · 观测云监控