Go OpenTelemetry 指标实战:Counter、Gauge、Histogram 一次讲透

在 Go 应用中用 OpenTelemetry 记录并导出业务与运行时指标:HTTP 服务器自动指标、Counter 计数、UpDownCounter 升降计数、Gauge 瞬时值、Histogram 分布统计,以及如何用 View 裁剪无用指标。指标最终导入观测云统一监控告警。

最佳实践
Go OpenTelemetry 指标实战:Counter、Gauge、Histogram 一次讲透封面

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 Metrics SDK 和 View · HTTP 指标语义约定 · OTLP 指标数据模型 · 观测云监控

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台