Prometheus采集/metric指标时如何配置自定义x-auth-token请求头？

要满足应用对采集请求的自定义头要求，无需额外部署代理或组件，直接修改prometheus.yml中的对应采集任务配置即可实现。

核心配置逻辑 #

Prometheus 原生支持在采集请求中携带自定义HTTP头，只需要在对应job的配置块下添加http_headers字段，声明要求的x-auth-token头即可。

可直接参考的配置片段 #

scrape_configs:
  # 原有其他采集任务配置保持不变
  - job_name: "auth-protected-app"
    metrics_path: "/metrics"
    static_configs:
      - targets:
          - "your-app-host:service-port"
    # 核心配置：注入自定义请求头
    http_headers:
      x-auth-token:
        value: "<customrandomtoken>"

生产环境适配建议 #

• 敏感信息不建议明文写入主配置文件，可以将token存储为独立的secret文件，将配置中的value字段替换为file字段，指定token文件在Prometheus运行环境中的绝对路径，Prometheus会自动读取文件内容作为请求头的值，示例：

  http_headers:
    x-auth-token:
      file: "/etc/prometheus/secrets/app_x_auth_token"
  

• 配置修改完成后，执行promtool check config prometheus.yml校验配置语法，避免因缩进、字段拼写错误导致配置加载失败
• 如果Prometheus开启了热更新参数--web.enable-lifecycle，可直接调用/-/reload接口重载配置，无需重启进程中断正常采集

注意事项 #

• http_headers字段是Prometheus 2.31.0版本正式引入的能力，如果使用的版本低于该版本，暂不支持原生自定义头配置，可以通过轻量反向代理层为采集请求注入指定鉴权头，再将Prometheus的采集目标指向代理地址
• 自定义请求头的名称需要和应用要求的x-auth-token完全一致，避免拼写错误导致鉴权拦截
• 注意避免将明文token提交到公开代码仓库，建议通过配置加密、secret挂载的方式管理敏感鉴权信息

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