Lazy loaded image
运维管理
Pushgateway 推送无法通过抓取方式获取的作业指标
Words 2007Read Time≈ 6 min
2026-1-10
2026-1-10
date
related_level
slug
prometheus_pushgateway
type
Post
relate_date
summary
Pushgateway 是短期批处理任务的指标缓存补充方案，弥补 Prometheus 拉取模型不足，但存在单点、指标不自动清理等缺陷，需谨慎使用
status
Published
tags
可观测性
category
运维管理
last_updated
Jan 10, 2026 07:16 PM
是否已更新
orginal_page
是否推荐
参考资料
Pushgateway 不是聚合器或分布式计数器 ，而更像是一个指标缓存
  • 常见有效用例是捕获服务级批处理作业的结果
  • 与机器相关的批处理作业推荐用 node_exporter 来处理，如自动安全更新 cron 作业或配置管理客户端运行
Prometheus 拉取（pull） 模型对比推送（push）模型的优势
  • 三个关键点
    • 便于临时启动监控实例（如本地开发调试）
    • 更可靠地判断目标是否宕机
    • 可直接通过浏览器访问目标的指标端点进行健康检查
  • 对于必须使用推送的场景（如短期任务），提供了 Pushgateway 作为补充方案
Pushgateway 推送机制缺陷
  • 当通过单个 Pushgateway 监控多个实例时，Pushgateway 既会成为单点故障，也会成为潜在的瓶颈
  • 失去 Prometheus 通过每次抓取时生成 up 指标提供的自动实例健康监控功能
  • Pushgateway 永远不会忘记推送给它的时间序列，并且会永远将它们暴露给 Prometheus
    • 即使原始实例被重命名或删除，该实例的指标仍会保留在 Pushgateway 中
      • 需要手动删除
    • 与 Prometheus 常用的拉取式监控形成鲜明对比：当一个实例消失（无论有意还是无意）时，其指标也会随之自动消失
Pushgateway 中的 job 和 instance 标签
  • Prometheus 默认会给从 Pushgateway 抓取的指标加上自己的 job（来自 scrape 配置）和 instance（Pushgateway 的 host:port）标签
    • 如果推送的指标本身包含 job/instance，会被重命名为 exported_job/exported_instance，以避免冲突
  • 因此 Prometheus 抓取 Pushgateway 的 scrape 配置中应该设置 honor_labels: true ，以保留原始推送的 job 和 instance
  • 若推送的指标没有 instance 标签，Pushgateway 会显式设置 {instance=""}，防止 Prometheus 自动覆盖
Pushgateway 指标一致性
  • Pushgateway 通过 /metrics 同时暴露自身指标和用户推送的指标
  • 所有指标必须遵循
    • 同名指标类型一致（如都是 Counter）
    • 不能有完全相同的名称+标签组合（即无重复）
  • 不一致的推送会被拒绝（HTTP 400）；help 文本不一致则被容忍，系统会选一个并记录日志
  • 可通过 --push.disable-consistency-check 禁用推送时的一致性检查以提升性能，但可能导致后续抓取失败，风险较高
Pushgateway 拒绝接收带时间戳的推送
  • 为了确保指标不会因“过期”而被 Prometheus 视为消失，Prometheus 抓取指标时使用的是抓取时刻的时间戳，而非推送时间
    • Prometheus 的每个样本只支持一个时间戳，无法区分“推送时间”和“抓取时间”
为了便于对推送失败或长时间未运行的推送任务进行告警，Pushgateway 会自动为每个 group 添加以下两个指标
  • push_time_seconds：记录该 group 最后一次成功执行 POST/PUT 请求的 Unix 时间戳
  • push_failure_time_seconds：记录该 group 最后一次推送失败的 Unix 时间戳
 

Pushgateway 写入和公开指标

使用 URL 路径和 HTTP 方法通过 Pushgateway API 写入指标
  • 默认端口：9091
URL 路径定义分组键（grouping key）
  • /metrics/job/<JOB_NAME>{/<LABEL_NAME>/<LABEL_VALUE>}
  • 分组键（grouping key）
    • <JOB_NAME> 作为 job 标签值，后可跟任意数量的其他标签对，共同构成
样例：分组键 {job="some_job",instance="some_instance"}
  • body 为内容
HTTP 方法定义了操作语义：PUT, POST, DELETE
PUT 替换整个分组下的所有指标
  • 请求体支持：
    • 文本格式（Prometheus 0.0.4）
    • Protocol Buffers（需设 Content-Type）
  • 成功响应码：
    • 200：成功推送（含创建或替换）
    • 202：仅当禁用一致性检查时返回（异步处理）
    • 400：请求错误或指标不一致（如类型冲突、重复）
  • POST 仅替换与新推指标同名的指标（同分组内）
DELETE 删除指定分组的所有指标
  • 无请求体，成功返回 202（异步删除）
    • 顺序保证：DELETE 与后续 PUT/POST 的执行顺序严格保持
  • 即使分组已空，也不报错
空 body 处理
  • PUT = 删除该分组所有指标，并更新 push_time_seconds
  • POST = 仅更新 push_time_seconds，不修改现有指标
  • DELETE 本身就没有 body
使用 Base64 编码处理特殊字符与空值处理
  • 若 job 或标签值包含 / 或为空，需使用 Base64 URL 安全编码，并在标签名后加 @base64 后缀
    • 如 /metrics/job/directory_cleaner/path@base64/L3Zhci90bXA
      • 对应分组键 {job="directory_cleaner",path="/var/tmp"}
  • 空值需用 = 填充
    • 如 /metrics/job/example/first_label@base64/=/second_label/foobar
      • 对应分组键 {job="example",first_label="",second_label="foobar"}
  • 普通特殊字符也可用 URI 编码，但 Base64 更可靠
默认不支持非 ASCII 字符的指标或标签名
  • 启动时加 --push.enable-utf8-names 启用UTF-8 标签/指标名支持
    • 默认关闭，因为存在极小概率的命名冲突风险
  • 编码规则：
    • 标签名以 U__ 开头
    • 非字母/数字/下划线字符转为 _Unicode码_
      • 如 foo.bar → U__foo_2e_bar
    • 原始下划线转为 __
无强持久化保证
  • 服务崩溃可能导致数据丢失（取决于是否启用磁盘持久化）
支持 gzip 或 snappy 压缩请求体
  • 需添加对应 Content-Encoding 头
对 Pushgateway 中发生的推送失败进行告警
当 push_time_seconds 明显落后于预期时间时进行告警
  • 可以同时捕获以下情况：
    • 推送失败
    • 推送端（pusher）完全宕机
  • 设置以下告警条件可以更早地发现失败情况
    • push_failure_time_seconds > push_time_seconds
因为格式错误而推送失败
  • 此时推送请求不会进入任何指标分组，也不会产生 push_failure_time_seconds 指标
  • 仍会计入 pushgateway_http_requests_total{code="400",handler="push"}
  • 可以基于该指标的 速率（rate） 设置告警
Pushgateway 公开指标
  • 通过配置的 --web.telemetry-path 路径公开指标
    • 默认值： /metrics
Pushgateway 公开以下指标
  • 被推送的指标
每个推送分组（group）对应的时间指标
  • push_time_seconds：记录该 group 最后一次成功执行 POST/PUT 请求的 Unix 时间戳
  • push_failure_time_seconds：记录该 group 最后一次推送失败的 Unix 时间戳
Prometheus Go 客户端库提供的常规指标
  • process_...
  • go_...
  • promhttp_metric_handler_requests_...
一些 Pushgateway 自身特有的指标
管理和查询 Pushgateway
  • 默认端口：9091
管理 API
  • 通过 --web.enable-lifecycle 启用 quit 端点
  • 可用端点
      • METHOD
      HANDLER
      DESCRIPTION
      GET
      /-/healthy
      Pushgateway 正常时返回 200
      GET
      /-/ready
      当 Pushgateway 准备好处理流量时，返回 200
      PUT
      /-/quit
      触发 Pushgateway 的优雅关闭
通过 --web.enable-admin-api 显式启用 Admin API 来删除所有指标
  • URL 路径 /api/<API_VERSION>/admin/<HANDLER>
  • 可用端点
      • METHOD
      API
      HANDLER
      DESCRIPTION
      PUT
      v1
      wipe
      安全地删除 Pushgateway 中的所有指标
  • 样例
    • curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
查询 API
  • URL 路径 /api/<API_VERSION>/<HANDLER>
  • 可用端点
      • METHOD
      API
      HANDLER
      DESCRIPTION
      GET
      v1
      status
      以 JSON 格式返回构建信息、命令行标志和开始时间
      GET
      v1
      metrics
      以 JSON 格式返回已推送的指标族
  • 样例
    • curl -X GET http://pushgateway.example.org:9091/api/v1/status | jq
 
上一篇
Prometheus 规则配置：记录规则和告警规则
下一篇
指标（Metric）和 Promethues 概述
Comments
Loading...
Catalog