如何在Prometheus go_client中暴露exemplar并解决示例不生效问题

客户端侧配置 #

• 确保client_golang依赖版本不低于v1.12.0，这是首个正式支持Exemplar特性的稳定版本
• 初始化Counter、Histogram类型指标时，必须显式开启Exemplar支持，传入WithExemplarFromContext参数：

  // 带自定义Exemplar标签提取逻辑的Histogram示例
  var reqDurations = prometheus.NewHistogram(
    prometheus.HistogramOpts{
      Name:    "http_request_duration_seconds",
      Help:    "HTTP请求耗时分布",
      Buckets: prometheus.DefBuckets,
    },
    // 配置从Context中提取trace_id作为Exemplar标签
    prometheus.WithExemplarFromContext(func(ctx context.Context) prometheus.Labels {
      if traceID, ok := ctx.Value("trace_id").(string); ok {
        return prometheus.Labels{"trace_id": traceID}
      }
      return nil
    }),
  )
  

• 上报指标时必须使用带Context的方法，不能用普通的Add/Observe方法：
  • Counter使用AddWithContext(ctx, 数值)
  • Histogram使用ObserveWithContext(ctx, 数值)
• 暴露Metrics接口时必须开启OpenMetrics格式支持，默认Handler不会返回Exemplar，正确初始化逻辑如下：

  http.Handle("/metrics", promhttp.HandlerFor(
    prometheus.DefaultGatherer,
    promhttp.HandlerOpts{
      EnableOpenMetrics: true, // 必须开启，Exemplar仅支持在OpenMetrics协议下返回
    },
  ))
  

这是运行官方示例也看不到Exemplar的核心原因：官方示例默认使用的基础Handler未开启OpenMetrics支持

验证方式 #

不要直接用浏览器访问/metrics接口，大部分浏览器默认请求头不会声明支持OpenMetrics格式，使用以下curl命令验证：

curl -H "Accept: application/openmetrics-text; version=0.0.1,text/plain;version=0.0.4;q=0.5,*/*;q=0.1" http://<你的服务地址>/metrics

返回结果中如果出现# Exemplar开头的行，即说明Exemplar暴露正常

Prometheus服务端采集配置（可选） #

如果需要Prometheus采集并存储Exemplar，需要满足以下配置：

• Prometheus版本不低于v2.33.0
• 对应抓取任务的配置中开启Exemplar采集：

  scrape_configs:
    - job_name: 'your-service'
      static_configs:
        - targets: ['<服务地址>:<端口>']
      exemplar_config:
        max_exemplars: 100 # 单时间序列最多存储的Exemplar数量，默认100
  

内容的提问来源于stack exchange，提问作者kehao