Golang怎么接入OpenTelemetry Metric_Golang如何用OTel SDK采集自定义指标数据【教程】

2次阅读

metric.MustNewMeterProvider 会 panic，因为 OpenTelemetry Go SDK 要求必须显式配置 exporter（如 metric.WithReader）和资源（如 resource.WithAttributes），否则 Validate 失败触发防护性 panic。

Golang 怎么接入 OpenTelemetry Metric_Golang 如何用 OTel SDK 采集自定义指标数据【教程】

为什么 `metric.MustNewMeterProvider` 会 panic？

因为 OpenTelemetry Go SDK 的 metric.MeterProvider 默认不支持直接创建指标——它需要显式配置一个 exporter 和资源（resource），否则 MustNewMeterProvider 会在内部调用 Validate 失败并 panic。这不是 bug，是 SDK 的主动防护：避免你误以为指标已上报，其实压根没配置出口。

必须传入至少一个 metric.WithReader（比如 otlpmetrichttp.NewClient 或 prometheus.NewExporter），否则无处发送数据
resource.WithAttributes 虽非强制，但缺失会导致所有指标缺少服务名、实例 ID 等关键维度，查问题时基本不可定位
本地调试时别只用 stdoutmetric.NewExporter，它只打印一次快照，且不支持累积型指标（如 Counter）的连续观测

Go SDK 不允许复用同一个 Meter 下同名、同类型、同单位的指标实例。一旦重复 meter.Int64Counter("http.requests")，第二次调用会返回 nil + error，但很多人忽略 error 检查，导致后续 .Add() panic。

每个指标应只初始化一次，通常放在 init() 或包级变量中，例如：var httpRequests = meter.Int64Counter("http.requests", metric.WithUnit("1"))
Gauge 必须配合回调函数（instrument.WithCallback）使用，不能像 Prometheus 那样直接 Set()；否则值不会被采集
Histogram 的 Boundaries（分桶边界）需在创建时固定，运行时无法修改；选错边界会导致 P90/P99 统计严重失真（比如全落在最后一个桶里）

OpenTelemetry 的 Histogram 默认导出为 Prometheus 的 _sum/_count/_bucket 三组指标，但命名和标签逻辑和原生 Prometheus client 不完全一致——尤其 exemplar 和 native_histogram 模式目前不支持，容易让 SRE 误判数据来源。

用 prometheus.NewExporter 时，确保 Registerer 是共享的（如全局 prometheus.DefaultRegisterer），否则指标不会出现在 /metrics 端点
OTel 的 http.route 属性会被转成 Prometheus 标签 http_route，但如果你代码里写的是 route（漏了 http. 前缀），Prometheus 就收不到这个维度
如果已有 Prometheus client 在用 promauto，别混用 OTel 的 prometheus.Exporter —— 两者注册机制冲突，可能导致指标重复或丢失

最常见原因是忘记调用 provider.Shutdown(context.Background())，或者没给 exporter 留够 flush 时间。OTel Metric 是异步批量上报的，main 函数退出太快，数据根本来不及发送。

立即学习 “go 语言免费学习笔记（深入）”；

在 main() 结尾加 defer provider.Shutdown(context.Background())，否则进程结束时 buffer 里的指标全丢
用 otlpmetrichttp 连接远端 collector 时，检查 http://localhost:4318/v1/metrics 是否可通；404 表示 collector 没开 metrics endpoint（默认只开 traces）
用 stdoutmetric 调试时，确保程序运行 >5 秒——它的默认 interval 是 5s，短于这个时间看不到任何输出

指标名、单位、属性键这些看似静态的东西，实际在 exporter 层会被重写、过滤甚至丢弃。别只看 Meter 创建成功就认为万事大吉，得盯着最终落盘的原始样本确认字段是否符合预期。

发表于：后端

近一天内