尧图网页设计 
Go语言Prometheus Exporter自定义指标采集与Grafana面板导语在云原生可观测性体系中Prometheus Grafana 是最主流的监控组合。Prometheus 负责指标采集与存储Grafana 负责可视化展示。但 Prometheus 只能采集暴露了/metrics端点的应用这就需要我们为自定义业务场景开发 Exporter指标暴露器。Go 语言生态对 Prometheus 有原生支持prometheus/client_golang是官方推荐的 Go SDK性能优异且 API 设计优雅。本文将深入讲解如何使用 Go 语言开发自定义 Prometheus Exporter从四种核心指标类型Counter、Gauge、Histogram、Summary到 Registry 管理再到 Grafana 面板配置带您完整走一遍生产级 Exporter 的开发流程。核心技术知识点讲解1. Prometheus 指标类型详解类型语义典型场景关键方法Counter只增不减的计数器请求总数、错误总数、任务完成数Inc(),Add(float64)Gauge可增可减的数值当前 goroutine 数、队列长度、温度Set(),Inc(),Dec(),Add()Histogram统计分布按桶计数 分位数估算请求延迟、响应大小Observe(float64)Summary滑动窗口分位数客户端计算请求延迟分位数P50/P99Observe(float64)Counter vs Gauge 选择原则值只会增加 → Counter值可能增加也可能减少 → Gauge需要计算速率如 QPS→ Counter rate()函数Histogram vs Summary 选择原则需要在 Prometheus 服务端计算分位数跨实例聚合→ Histogram每个实例独立计算分位数不需要聚合 → Summary2. Exporter 的/metrics端点格式Prometheus 通过 HTTP GET/metrics拉取指标格式为文本格式Text Format# HELP http_requests_total Total number of HTTP requests # TYPE http_requests_total counter http_requests_total{methodGET,status200} 1234 http_requests_total{methodPOST,status500} 56 # HELP http_request_duration_seconds Request latency # TYPE http_request_duration_seconds histogram http_request_duration_seconds_bucket{methodGET,le0.005} 1203 http_request_duration_seconds_bucket{methodGET,le0.01} 1250 http_request_duration_seconds_bucket{methodGET,leInf} 1300 http_request_duration_seconds_sum{methodGET} 45.3 http_request_duration_seconds_count{methodGET} 13003. Go 中 prometheus/client_golang 核心 APIimport(github.com/prometheus/client_golang/prometheusgithub.com/prometheus/client_golang/prometheus/promhttp)// 1. 定义指标最佳实践包级变量 NewXxx 初始化var(httpRequestsTotalprometheus.NewCounterVec(prometheus.CounterOpts{Name:http_requests_total,Help:Total number of HTTP requests,},[]string{method,status},// 标签维度)httpDurationprometheus.NewHistogramVec(prometheus.HistogramOpts{Name:http_request_duration_seconds,Help:HTTP request duration,Buckets:prometheus.DefBuckets,// 默认桶[0.005, 0.01, ..., 10]},[]string{method},))// 2. 注册指标init 函数中执行funcinit(){prometheus.MustRegister(httpRequestsTotal)prometheus.MustRegister(httpDuration)}// 3. 暴露 /metrics 端点http.Handle(/metrics,promhttp.Handler())4. 自定义 Registry多租户/多应用隔离场景默认的prometheus.DefaultRegisterer是全局单例不适合多租户场景。应创建独立 Registryreg:prometheus.NewRegistry()reg.MustRegister(myCounter)reg.MustRegister(myGauge)// 使用独立 Handlerhandler:promhttp.HandlerFor(reg,promhttp.HandlerOpts{})http.Handle(/metrics,handler)实战代码演示/项目案例总结项目背景我们开发一个文件处理服务File Processor它需要暴露以下业务指标处理文件总数Counter当前正在处理的文件数Gauge文件处理耗时分布Histogram文件大小分布Histogram当前服务内存使用量Gauge通过 runtime 包采集完整实战代码第一步定义所有指标// internal/metrics/metrics.gopackagemetricsimport(github.com/prometheus/client_golang/prometheus)// ── 定义指标标签常量 ─────────────────────────────────────const(LabelStatusstatus// success / failedLabelOpTypeop_type// upload / download / deleteLabelMethodmethod)// ── 文件处理核心指标 ─────────────────────────────────────var(// Counter文件处理总数按状态 操作类型维度FileProcessedTotalprometheus.NewCounterVec(prometheus.CounterOpts{Namespace:fileproc,// 指标命名空间Subsystem:worker,// 子系统Name:files_processed_total,Help:Total number of files processed,},[]string{LabelStatus,LabelOpType},)// Gauge当前正在处理的文件数FileProcessingInFlightprometheus.NewGauge(prometheus.GaugeOpts{Namespace:fileproc,Subsystem:worker,Name:files_processing_in_flight,Help:Number of files currently being processed,},)// Gauge当前服务 goroutine 数GoroutinesInFlightprometheus.NewGaugeFunc(prometheus.GaugeOpts{Namespace:fileproc,Subsystem:runtime,Name:goroutines,Help:Number of goroutines,},func()float64{returnfloat64(runtime.NumGoroutine())},)// Histogram文件处理耗时秒FileProcessDurationprometheus.NewHistogramVec(prometheus.HistogramOpts{Namespace:fileproc,Subsystem:worker,Name:file_process_duration_seconds,Help:File processing duration in seconds,Buckets:[]float64{0.01,0.05,0.1,0.5,1,5,10,30,60},},[]string{LabelOpType},)// Histogram文件大小分布字节对数刻度桶FileSizeBytesprometheus.NewHistogramVec(prometheus.HistogramOpts{Namespace:fileproc,Subsystem:worker,Name:file_size_bytes,Help:Processed file size in bytes,Buckets:prometheus.ExponentialBuckets(1024,2,10),// 1KB ~ 512KB},[]string{LabelOpType},)// Counter处理失败原因统计ProcessErrorsTotalprometheus.NewCounterVec(prometheus.CounterOpts{Namespace:fileproc,Subsystem:worker,Name:process_errors_total,Help:Total number of processing errors by type,},[]string{error_type},// timeout / disk_full / permission_denied))// Init 注册所有指标到默认 Registry// 在 main() 中调用funcInit(){prometheus.MustRegister(FileProcessedTotal,FileProcessingInFlight,GoroutinesInFlight,FileProcessDuration,FileSizeBytes,ProcessErrorsTotal,)}第二步在业务代码中使用指标// internal/worker/worker.gopackageworkerimport(contextfmtostimeyour-module/internal/metrics)typeWorkerstruct{maxConcurrentintsemchanstruct{}// 并发控制信号量}funcNewWorker(maxConcurrentint)*Worker{returnWorker{maxConcurrent:maxConcurrent,sem:make(chanstruct{},maxConcurrent),}}// ProcessFile 处理单个文件核心业务逻辑func(w*Worker)ProcessFile(ctx context.Context,opTypestring,filePathstring,)error{// 1. 并发控制select{casew.sem-struct{}{}:deferfunc(){-w.sem}()case-ctx.Done():returnctx.Err()}// 2. Gauge 1正在处理metrics.FileProcessingInFlight.Inc()defermetrics.FileProcessingInFlight.Dec()start:time.Now()// 3. 获取文件大小用于 Histograminfo,err:os.Stat(filePath)iferrnil{metrics.FileSizeBytes.WithLabelValues(opType).Observe(float64(info.Size()))}// 4. 模拟文件处理// ... 实际业务逻辑 ...time.Sleep(100*time.Millisecond)// 模拟耗时// 5. 模拟处理结果varprocessErrerror// processErr fmt.Errorf(timeout) // 取消注释测试错误场景elapsed:time.Since(start).Seconds()// 6. 记录 Histogrammetrics.FileProcessDuration.WithLabelValues(opType).Observe(elapsed)// 7. 记录 CounterifprocessErr!nil{metrics.FileProcessedTotal.WithLabelValues(failed,opType).Inc()// 记录错误类型errType:unknownifopTypeupload{errTypetimeout}metrics.ProcessErrorsTotal.WithLabelValues(errType).Inc()returnprocessErr}metrics.FileProcessedTotal.WithLabelValues(success,opType).Inc()returnnil}// SimulateTraffic 模拟并发请求用于测试func(w*Worker)SimulateTraffic(ctx context.Context,opTypestring){fori:0;;i{select{case-ctx.Done():returndefault:filePath:fmt.Sprintf(/tmp/testfile-%d.dat,i)// 创建测试文件os.WriteFile(filePath,make([]byte,4096),0644)gofunc(fstring){_w.ProcessFile(ctx,opType,f)}(filePath)time.Sleep(50*time.Millisecond)}}}第三步启动 HTTP 服务并暴露 /metrics// cmd/exporter/main.gopackagemainimport(contextlognet/httpruntimetimegithub.com/prometheus/client_golang/prometheusgithub.com/prometheus/client_golang/prometheus/collectorsgithub.com/prometheus/client_golang/prometheus/promhttpyour-module/internal/metricsyour-module/internal/worker)funcmain(){// 1. 初始化自定义指标metrics.Init()// 2. 同时注册 Go 运行时默认指标可选但强烈推荐reg:prometheus.NewRegistry()reg.MustRegister(collectors.NewGoCollector(),// Go runtime 指标GC、goroutine 等collectors.NewProcessCollectors(// 进程级指标CPU、内存、FD 等collectors.ProcessCollectorOpts{},),)// 注册自定义指标到同一 registryreg.MustRegister(metrics.FileProcessedTotal)reg.MustRegister(metrics.FileProcessingInFlight)reg.MustRegister(metrics.GoroutinesInFlight)reg.MustRegister(metrics.FileProcessDuration)reg.MustRegister(metrics.FileSizeBytes)reg.MustRegister(metrics.ProcessErrorsTotal)// 3. 启动 Worker 并模拟流量w:worker.NewWorker(10)ctx,cancel:context.WithCancel(context.Background())defercancel()gow.SimulateTraffic(ctx,upload)gow.SimulateTraffic(ctx,download)// 4. 暴露 /metrics 端点// 使用自定义 Registry 的 Handlerhandler:promhttp.HandlerFor(reg,promhttp.HandlerOpts{EnableOpenMetrics:true,// 支持 OpenMetrics 格式})http.Handle(/metrics,handler)// 5. 健康检查端点http.HandleFunc(/healthz,func(w http.ResponseWriter,r*http.Request){w.Write([]byte(ok))})log.Println(Exporter 启动在 :2112/metrics)log.Fatal(http.ListenAndServe(:2112,nil))}第四步Grafana 面板配置JSON 片段 查询语句在 Grafana 中创建 Dashboard添加以下 PanelPanel 1文件处理 QPS使用 Counter ratePromQL 查询rate(fileproc_worker_files_processed_total[1m])Panel 2文件处理耗时 P99使用 Histogram histogram_quantilePromQL 查询histogram_quantile(0.99, rate(fileproc_worker_file_process_duration_seconds_bucket[5m]) )Panel 3当前正在处理的文件数Gauge 直接读取PromQL 查询fileproc_worker_files_processing_in_flightPanel 4处理错误率PromQL 查询sum(rate(fileproc_worker_process_errors_total[5m])) by (error_type)第五步docker-compose 一键启动 Prometheus Grafana# deploy/docker-compose.ymlversion:3.8services:prometheus:image:prom/prometheus:latestvolumes:-./prometheus.yml:/etc/prometheus/prometheus.ymlports:-9090:9090grafana:image:grafana/grafana:latestports:-3000:3000environment:-GF_SECURITY_ADMIN_PASSWORDadminvolumes:-grafana-storage:/var/lib/grafanafileproc-exporter:build:..ports:-2112:2112volumes:grafana-storage:# deploy/prometheus.ymlglobal:scrape_interval:15sscrape_configs:-job_name:fileprocstatic_configs:-targets:[fileproc-exporter:2112]开发痛点与报错避坑指南坑点 1指标重复注册导致 panic现象启动时报duplicate metrics collector registration attempted。原因同一指标被注册了两次。常见于在测试中多次调用prometheus.MustRegister()多个包分别注册了同名的指标正确做法// 使用 prometheus.MustRegister 前先检查是否已注册// 或者在 init() 中注册只执行一次// 测试中使用 prometheus.NewRegistry() 隔离funcTestXxx(t*testing.T){reg:prometheus.NewRegistry()reg.MustRegister(myMetric)// 测试隔离}坑点 2Histogram 桶设计不合理导致内存浪费或精度不足现象Grafana 图表中 P99 数据不准确或者 Prometheus 内存占用过高。原因桶Buckets设置不当。桶太少 → 精度低桶太多 → 内存/存储开销大。正确做法// API 请求延迟使用指数桶覆盖从 5ms 到 5sBuckets:prometheus.ExponentialBuckets(0.005,2,10),// 即[0.005, 0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56]// 文件大小覆盖 1KB ~ 1GBBuckets:prometheus.ExponentialBuckets(1024,2,20),坑点 3Labels 基数爆炸Cardinality Explosion现象Prometheus 内存爆炸查询变慢。原因Label 的值域过大。例如user_id百万级作为 Label会产生百万条时间序列。正确做法Label 只能使用有限枚举值如status、method、region绝对不能用 uuid、email、IP 作为 Label使用promtool检查基数promtool tsdb analyze坑点 4Goroutine 泄露导致 Gauge 值不准现象服务重启后Gauge 指标仍然显示旧值。原因Gauge 是设点值如果 goroutine 异常退出没有执行Defer Gauge.Dec()Gauge 值只会增不会减。正确做法所有Gauge.Inc()必须配对defer Gauge.Dec()或者使用GaugeFunc动态计算。坑点 5Summary 不支持跨实例聚合现象多个实例的 P99 延迟在 Prometheus 中无法正确聚合。原因Summary 的分位数是在客户端应用侧计算的不能跨实例聚合。Histogram 的分位数是在服务端Prometheus计算的支持聚合。正确做法优先使用 Histogram除非你明确不需要跨实例聚合。全文总结技术进阶展望本文系统讲解了使用 Go 语言开发 Prometheus Exporter 的完整流程四种核心指标类型Counter只增、Gauge可增可减、Histogram服务端正位计算、Summary客户端分位数指标命名规范{namespace}_{subsystem}_{name}Label 只能使用有限枚举值Registry 管理生产环境使用独立 Registry避免全局状态污染Grafana 可视化使用rate()计算 QPS使用histogram_quantile()计算分位数Exporter 部署通过 docker-compose 一键启动 Prometheus Grafana Exporter关键认知Prometheus 是拉模型Pull应用只需要暴露/metrics端点不需要主动推送指标设计的核心原则是低基数 有意义的标签Histogram 的桶设计需要在精度和成本之间权衡进阶方向Exporter 高可用多实例场景下使用 Consul 或 K8s Service Discovery 自动发现 Exporter 实例自定义 Collector实现prometheus.Collector接口从外部系统数据库、消息队列拉取指标OpenMetrics 格式新一代指标暴露格式支持 UTF-8、Native HistogramNative HistogramPrometheus v2.40指数桶直方图大幅降低存储成本Grafana Mimir / ThanosPrometheus 长期存储与全局查询方案参考文献Prometheus Client Golang. https://github.com/prometheus/client_golangPrometheus Metric Types. https://prometheus.io/docs/concepts/metric-types/Writing Exporters. https://prometheus.io/docs/instrumenting/writing_exporters/prometheus/client_golang API Docs. https://pkg.go.dev/github.com/prometheus/client_golang/prometheusGrafana Dashboard Best Practices. https://grafana.com/docs/grafana/latest/best-practices/Histogram vs Summary. https://prometheus.io/docs/practices/histograms/ Go语言Prometheus Exporter自定义指标采集与Grafana面板
Go语言Prometheus Exporter自定义指标采集与Grafana面板导语在云原生可观测性体系中Prometheus Grafana 是最主流的监控组合。Prometheus 负责指标采集与存储Grafana 负责可视化展示。但 Prometheus 只能采集暴露了/metrics端点的应用这就需要我们为自定义业务场景开发 Exporter指标暴露器。Go 语言生态对 Prometheus 有原生支持prometheus/client_golang是官方推荐的 Go SDK性能优异且 API 设计优雅。本文将深入讲解如何使用 Go 语言开发自定义 Prometheus Exporter从四种核心指标类型Counter、Gauge、Histogram、Summary到 Registry 管理再到 Grafana 面板配置带您完整走一遍生产级 Exporter 的开发流程。核心技术知识点讲解1. Prometheus 指标类型详解类型语义典型场景关键方法Counter只增不减的计数器请求总数、错误总数、任务完成数Inc(),Add(float64)Gauge可增可减的数值当前 goroutine 数、队列长度、温度Set(),Inc(),Dec(),Add()Histogram统计分布按桶计数 分位数估算请求延迟、响应大小Observe(float64)Summary滑动窗口分位数客户端计算请求延迟分位数P50/P99Observe(float64)Counter vs Gauge 选择原则值只会增加 → Counter值可能增加也可能减少 → Gauge需要计算速率如 QPS→ Counter rate()函数Histogram vs Summary 选择原则需要在 Prometheus 服务端计算分位数跨实例聚合→ Histogram每个实例独立计算分位数不需要聚合 → Summary2. Exporter 的/metrics端点格式Prometheus 通过 HTTP GET/metrics拉取指标格式为文本格式Text Format# HELP http_requests_total Total number of HTTP requests # TYPE http_requests_total counter http_requests_total{methodGET,status200} 1234 http_requests_total{methodPOST,status500} 56 # HELP http_request_duration_seconds Request latency # TYPE http_request_duration_seconds histogram http_request_duration_seconds_bucket{methodGET,le0.005} 1203 http_request_duration_seconds_bucket{methodGET,le0.01} 1250 http_request_duration_seconds_bucket{methodGET,leInf} 1300 http_request_duration_seconds_sum{methodGET} 45.3 http_request_duration_seconds_count{methodGET} 13003. Go 中 prometheus/client_golang 核心 APIimport(github.com/prometheus/client_golang/prometheusgithub.com/prometheus/client_golang/prometheus/promhttp)// 1. 定义指标最佳实践包级变量 NewXxx 初始化var(httpRequestsTotalprometheus.NewCounterVec(prometheus.CounterOpts{Name:http_requests_total,Help:Total number of HTTP requests,},[]string{method,status},// 标签维度)httpDurationprometheus.NewHistogramVec(prometheus.HistogramOpts{Name:http_request_duration_seconds,Help:HTTP request duration,Buckets:prometheus.DefBuckets,// 默认桶[0.005, 0.01, ..., 10]},[]string{method},))// 2. 注册指标init 函数中执行funcinit(){prometheus.MustRegister(httpRequestsTotal)prometheus.MustRegister(httpDuration)}// 3. 暴露 /metrics 端点http.Handle(/metrics,promhttp.Handler())4. 自定义 Registry多租户/多应用隔离场景默认的prometheus.DefaultRegisterer是全局单例不适合多租户场景。应创建独立 Registryreg:prometheus.NewRegistry()reg.MustRegister(myCounter)reg.MustRegister(myGauge)// 使用独立 Handlerhandler:promhttp.HandlerFor(reg,promhttp.HandlerOpts{})http.Handle(/metrics,handler)实战代码演示/项目案例总结项目背景我们开发一个文件处理服务File Processor它需要暴露以下业务指标处理文件总数Counter当前正在处理的文件数Gauge文件处理耗时分布Histogram文件大小分布Histogram当前服务内存使用量Gauge通过 runtime 包采集完整实战代码第一步定义所有指标// internal/metrics/metrics.gopackagemetricsimport(github.com/prometheus/client_golang/prometheus)// ── 定义指标标签常量 ─────────────────────────────────────const(LabelStatusstatus// success / failedLabelOpTypeop_type// upload / download / deleteLabelMethodmethod)// ── 文件处理核心指标 ─────────────────────────────────────var(// Counter文件处理总数按状态 操作类型维度FileProcessedTotalprometheus.NewCounterVec(prometheus.CounterOpts{Namespace:fileproc,// 指标命名空间Subsystem:worker,// 子系统Name:files_processed_total,Help:Total number of files processed,},[]string{LabelStatus,LabelOpType},)// Gauge当前正在处理的文件数FileProcessingInFlightprometheus.NewGauge(prometheus.GaugeOpts{Namespace:fileproc,Subsystem:worker,Name:files_processing_in_flight,Help:Number of files currently being processed,},)// Gauge当前服务 goroutine 数GoroutinesInFlightprometheus.NewGaugeFunc(prometheus.GaugeOpts{Namespace:fileproc,Subsystem:runtime,Name:goroutines,Help:Number of goroutines,},func()float64{returnfloat64(runtime.NumGoroutine())},)// Histogram文件处理耗时秒FileProcessDurationprometheus.NewHistogramVec(prometheus.HistogramOpts{Namespace:fileproc,Subsystem:worker,Name:file_process_duration_seconds,Help:File processing duration in seconds,Buckets:[]float64{0.01,0.05,0.1,0.5,1,5,10,30,60},},[]string{LabelOpType},)// Histogram文件大小分布字节对数刻度桶FileSizeBytesprometheus.NewHistogramVec(prometheus.HistogramOpts{Namespace:fileproc,Subsystem:worker,Name:file_size_bytes,Help:Processed file size in bytes,Buckets:prometheus.ExponentialBuckets(1024,2,10),// 1KB ~ 512KB},[]string{LabelOpType},)// Counter处理失败原因统计ProcessErrorsTotalprometheus.NewCounterVec(prometheus.CounterOpts{Namespace:fileproc,Subsystem:worker,Name:process_errors_total,Help:Total number of processing errors by type,},[]string{error_type},// timeout / disk_full / permission_denied))// Init 注册所有指标到默认 Registry// 在 main() 中调用funcInit(){prometheus.MustRegister(FileProcessedTotal,FileProcessingInFlight,GoroutinesInFlight,FileProcessDuration,FileSizeBytes,ProcessErrorsTotal,)}第二步在业务代码中使用指标// internal/worker/worker.gopackageworkerimport(contextfmtostimeyour-module/internal/metrics)typeWorkerstruct{maxConcurrentintsemchanstruct{}// 并发控制信号量}funcNewWorker(maxConcurrentint)*Worker{returnWorker{maxConcurrent:maxConcurrent,sem:make(chanstruct{},maxConcurrent),}}// ProcessFile 处理单个文件核心业务逻辑func(w*Worker)ProcessFile(ctx context.Context,opTypestring,filePathstring,)error{// 1. 并发控制select{casew.sem-struct{}{}:deferfunc(){-w.sem}()case-ctx.Done():returnctx.Err()}// 2. Gauge 1正在处理metrics.FileProcessingInFlight.Inc()defermetrics.FileProcessingInFlight.Dec()start:time.Now()// 3. 获取文件大小用于 Histograminfo,err:os.Stat(filePath)iferrnil{metrics.FileSizeBytes.WithLabelValues(opType).Observe(float64(info.Size()))}// 4. 模拟文件处理// ... 实际业务逻辑 ...time.Sleep(100*time.Millisecond)// 模拟耗时// 5. 模拟处理结果varprocessErrerror// processErr fmt.Errorf(timeout) // 取消注释测试错误场景elapsed:time.Since(start).Seconds()// 6. 记录 Histogrammetrics.FileProcessDuration.WithLabelValues(opType).Observe(elapsed)// 7. 记录 CounterifprocessErr!nil{metrics.FileProcessedTotal.WithLabelValues(failed,opType).Inc()// 记录错误类型errType:unknownifopTypeupload{errTypetimeout}metrics.ProcessErrorsTotal.WithLabelValues(errType).Inc()returnprocessErr}metrics.FileProcessedTotal.WithLabelValues(success,opType).Inc()returnnil}// SimulateTraffic 模拟并发请求用于测试func(w*Worker)SimulateTraffic(ctx context.Context,opTypestring){fori:0;;i{select{case-ctx.Done():returndefault:filePath:fmt.Sprintf(/tmp/testfile-%d.dat,i)// 创建测试文件os.WriteFile(filePath,make([]byte,4096),0644)gofunc(fstring){_w.ProcessFile(ctx,opType,f)}(filePath)time.Sleep(50*time.Millisecond)}}}第三步启动 HTTP 服务并暴露 /metrics// cmd/exporter/main.gopackagemainimport(contextlognet/httpruntimetimegithub.com/prometheus/client_golang/prometheusgithub.com/prometheus/client_golang/prometheus/collectorsgithub.com/prometheus/client_golang/prometheus/promhttpyour-module/internal/metricsyour-module/internal/worker)funcmain(){// 1. 初始化自定义指标metrics.Init()// 2. 同时注册 Go 运行时默认指标可选但强烈推荐reg:prometheus.NewRegistry()reg.MustRegister(collectors.NewGoCollector(),// Go runtime 指标GC、goroutine 等collectors.NewProcessCollectors(// 进程级指标CPU、内存、FD 等collectors.ProcessCollectorOpts{},),)// 注册自定义指标到同一 registryreg.MustRegister(metrics.FileProcessedTotal)reg.MustRegister(metrics.FileProcessingInFlight)reg.MustRegister(metrics.GoroutinesInFlight)reg.MustRegister(metrics.FileProcessDuration)reg.MustRegister(metrics.FileSizeBytes)reg.MustRegister(metrics.ProcessErrorsTotal)// 3. 启动 Worker 并模拟流量w:worker.NewWorker(10)ctx,cancel:context.WithCancel(context.Background())defercancel()gow.SimulateTraffic(ctx,upload)gow.SimulateTraffic(ctx,download)// 4. 暴露 /metrics 端点// 使用自定义 Registry 的 Handlerhandler:promhttp.HandlerFor(reg,promhttp.HandlerOpts{EnableOpenMetrics:true,// 支持 OpenMetrics 格式})http.Handle(/metrics,handler)// 5. 健康检查端点http.HandleFunc(/healthz,func(w http.ResponseWriter,r*http.Request){w.Write([]byte(ok))})log.Println(Exporter 启动在 :2112/metrics)log.Fatal(http.ListenAndServe(:2112,nil))}第四步Grafana 面板配置JSON 片段 查询语句在 Grafana 中创建 Dashboard添加以下 PanelPanel 1文件处理 QPS使用 Counter ratePromQL 查询rate(fileproc_worker_files_processed_total[1m])Panel 2文件处理耗时 P99使用 Histogram histogram_quantilePromQL 查询histogram_quantile(0.99, rate(fileproc_worker_file_process_duration_seconds_bucket[5m]) )Panel 3当前正在处理的文件数Gauge 直接读取PromQL 查询fileproc_worker_files_processing_in_flightPanel 4处理错误率PromQL 查询sum(rate(fileproc_worker_process_errors_total[5m])) by (error_type)第五步docker-compose 一键启动 Prometheus Grafana# deploy/docker-compose.ymlversion:3.8services:prometheus:image:prom/prometheus:latestvolumes:-./prometheus.yml:/etc/prometheus/prometheus.ymlports:-9090:9090grafana:image:grafana/grafana:latestports:-3000:3000environment:-GF_SECURITY_ADMIN_PASSWORDadminvolumes:-grafana-storage:/var/lib/grafanafileproc-exporter:build:..ports:-2112:2112volumes:grafana-storage:# deploy/prometheus.ymlglobal:scrape_interval:15sscrape_configs:-job_name:fileprocstatic_configs:-targets:[fileproc-exporter:2112]开发痛点与报错避坑指南坑点 1指标重复注册导致 panic现象启动时报duplicate metrics collector registration attempted。原因同一指标被注册了两次。常见于在测试中多次调用prometheus.MustRegister()多个包分别注册了同名的指标正确做法// 使用 prometheus.MustRegister 前先检查是否已注册// 或者在 init() 中注册只执行一次// 测试中使用 prometheus.NewRegistry() 隔离funcTestXxx(t*testing.T){reg:prometheus.NewRegistry()reg.MustRegister(myMetric)// 测试隔离}坑点 2Histogram 桶设计不合理导致内存浪费或精度不足现象Grafana 图表中 P99 数据不准确或者 Prometheus 内存占用过高。原因桶Buckets设置不当。桶太少 → 精度低桶太多 → 内存/存储开销大。正确做法// API 请求延迟使用指数桶覆盖从 5ms 到 5sBuckets:prometheus.ExponentialBuckets(0.005,2,10),// 即[0.005, 0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56]// 文件大小覆盖 1KB ~ 1GBBuckets:prometheus.ExponentialBuckets(1024,2,20),坑点 3Labels 基数爆炸Cardinality Explosion现象Prometheus 内存爆炸查询变慢。原因Label 的值域过大。例如user_id百万级作为 Label会产生百万条时间序列。正确做法Label 只能使用有限枚举值如status、method、region绝对不能用 uuid、email、IP 作为 Label使用promtool检查基数promtool tsdb analyze坑点 4Goroutine 泄露导致 Gauge 值不准现象服务重启后Gauge 指标仍然显示旧值。原因Gauge 是设点值如果 goroutine 异常退出没有执行Defer Gauge.Dec()Gauge 值只会增不会减。正确做法所有Gauge.Inc()必须配对defer Gauge.Dec()或者使用GaugeFunc动态计算。坑点 5Summary 不支持跨实例聚合现象多个实例的 P99 延迟在 Prometheus 中无法正确聚合。原因Summary 的分位数是在客户端应用侧计算的不能跨实例聚合。Histogram 的分位数是在服务端Prometheus计算的支持聚合。正确做法优先使用 Histogram除非你明确不需要跨实例聚合。全文总结技术进阶展望本文系统讲解了使用 Go 语言开发 Prometheus Exporter 的完整流程四种核心指标类型Counter只增、Gauge可增可减、Histogram服务端正位计算、Summary客户端分位数指标命名规范{namespace}_{subsystem}_{name}Label 只能使用有限枚举值Registry 管理生产环境使用独立 Registry避免全局状态污染Grafana 可视化使用rate()计算 QPS使用histogram_quantile()计算分位数Exporter 部署通过 docker-compose 一键启动 Prometheus Grafana Exporter关键认知Prometheus 是拉模型Pull应用只需要暴露/metrics端点不需要主动推送指标设计的核心原则是低基数 有意义的标签Histogram 的桶设计需要在精度和成本之间权衡进阶方向Exporter 高可用多实例场景下使用 Consul 或 K8s Service Discovery 自动发现 Exporter 实例自定义 Collector实现prometheus.Collector接口从外部系统数据库、消息队列拉取指标OpenMetrics 格式新一代指标暴露格式支持 UTF-8、Native HistogramNative HistogramPrometheus v2.40指数桶直方图大幅降低存储成本Grafana Mimir / ThanosPrometheus 长期存储与全局查询方案参考文献Prometheus Client Golang. https://github.com/prometheus/client_golangPrometheus Metric Types. https://prometheus.io/docs/concepts/metric-types/Writing Exporters. https://prometheus.io/docs/instrumenting/writing_exporters/prometheus/client_golang API Docs. https://pkg.go.dev/github.com/prometheus/client_golang/prometheusGrafana Dashboard Best Practices. https://grafana.com/docs/grafana/latest/best-practices/Histogram vs Summary. https://prometheus.io/docs/practices/histograms/