WEEW12 BLOG

外观

11：短时任务监控：Pushgateway 推送指标方案全解与避坑指南

约 1772 字大约 6 分钟

2026-03-29

Prometheus 核心采用拉取式架构采集指标，但在实际场景中，部分资源无法被直接拉取（如短时容器、批处理作业、网络隔离的服务）。Pushgateway 作为 Prometheus 生态的关键组件，专为“推送指标”场景设计，成为短时任务、不可直连资源监控的核心解决方案。本文将全面解析 Pushgateway 的使用方法、配置要点与避坑指南。

一、Pushgateway 核心认知：是什么 & 适用场景

1.1 什么是 Pushgateway

Pushgateway 是独立的中间件服务，通过 HTTP REST API 接收指标推送，自身作为 Prometheus 的抓取目标，实现“推送-中转-拉取”的指标流转闭环。其定位是指标代理（而非聚合器），与黑盒 exporter 行为相反：接收指标而非主动探测。

核心架构：

应用/作业 → 推送指标 → Pushgateway（存储） → Prometheus 拉取指标

1.2 适用场景（仅作为有限解决方案）

Pushgateway 并非银弹，仅适用于以下场景：

  • 网络/安全限制：目标资源无法被 Prometheus 直连（如仅开放特定端口/路径）；
  • 短时生命周期：容器、批处理作业等启动/执行/停止极快，拉取窗口期过短；
  • 无抓取端点：批处理作业等无 HTTP 服务，无法暴露指标接口。

1.3 核心局限性（避坑前置）

  • 非聚合器：仅缓存最后一次推送的指标值，不会累加/聚合（如多次推送同一指标，仅保留最后一次值）；
  • 单点风险：可扩展性远低于 Prometheus，需避免作为核心监控链路的单点；
  • 指标残留：默认内存存储，重启丢失；未主动删除的话，已下线实例的指标会长期留存；
  • 丢失原生能力：无法通过 up 指标监控实例状态，无指标自动过期机制。

二、Pushgateway 部署：多环境安装指南

2.1 官方下载与系统支持

Pushgateway 基于 Go 开发，支持多系统（Linux/Windows/Mac/FreeBSD 等），可从 Prometheus 下载页 获取对应二进制包，旧版本可从 GitHub Releases 下载（本文示例版本：0.5.2）。

2.2 Linux 快速安装

# 1. 下载二进制包
cd /tmp
wget https://github.com/prometheus/pushgateway/releases/download/v0.5.2/pushgateway-0.5.2-linux-amd64.tar.gz

# 2. 解压并移动到系统路径
tar -xzf pushgateway-0.5.2-linux-amd64.tar.gz
sudo cp pushgateway-0.5.2-linux-amd64/pushgateway /usr/local/bin/

# 3. 验证安装
pushgateway --version

2.3 Windows 安装

# 1. 创建目录
C:\> MKDIR pushgateway
C:\> CD pushgateway

# 2. 下载二进制包（手动下载或通过工具）
# 地址：https://github.com/prometheus/pushgateway/releases/download/v0.5.2/pushgateway-0.5.2.windows-amd64.tar.gz

# 3. 解压后配置环境变量
$env:Path += ";C:\pushgateway"

# 4. 验证安装
C:\> pushgateway.exe --version

2.4 配置管理工具安装（推荐生产环境）

三、Pushgateway 配置与运行：核心参数

Pushgateway 开箱即用，无需配置文件，通过命令行参数调整行为：

3.1 基础启动（指定端口/监听地址）

# 默认端口9091，绑定所有网卡
pushgateway --web.listen-address="0.0.0.0:9091"

启动后可访问 http://<IP>:9091 查看加粗图11-2 Pushgateway仪表板：

3.2 指标持久化（避免重启丢失）

默认指标仅存于内存，重启后丢失，需配置持久化：

# 指定持久化文件路径（注意空格转义）
pushgateway --persistence.file="/tmp/pushgateway_persist" \
  --persistence.interval=1m  # 持久化间隔（默认5分钟）

3.3 查看所有参数

pushgateway --help

四、指标操作：推送、查看、删除

4.1 快速推送（curl 示例）

Pushgateway 支持通过 HTTP API 接收指标，最简单的方式是 curl：

# 基础推送：指定job标签
echo 'batchjob1_user_counter 2' | curl --data-binary @- http://localhost:9091/metrics/job/batchjob1

# 带instance标签推送
echo 'batchjob1_user_counter 2' | curl --data-binary @- http://localhost:9091/metrics/job/batchjob1/instance/sidekiq_server

# 带自定义标签推送
echo 'batchjob1_user_counter{job_id="123ABC"} 2' | curl --data-binary @- http://localhost:9091/metrics/job/batchjob1/instance/sidekiq_server

# 带类型+描述的标准推送（推荐）
cat <<EOF | curl --data-binary @- http://localhost:9091/metrics/job/batchjob1/instance/sidekiq_server
# TYPE batchjob1_user_counter counter
# HELP batchjob1_user_counter 批处理任务1的用户计数
batchjob1_user_counter{job_id="123ABC"} 2
EOF

关键规则：

  • 路径格式：/metrics/job/<jobname>/<label_name>/<label_value>；
  • 路径中的标签会覆盖指标自身的同名标签；
  • 标签值/作业名不支持 /（包括转义）。

4.2 查看已推送指标

curl http://localhost:9091/metrics

输出示例包含推送的业务指标，以及 Pushgateway 自身指标（如 push_time_seconds：最后一次推送时间）。

4.3 删除指标

# 删除整个job的所有指标
curl -X DELETE http://localhost:9091/metrics/job/batchjob1

# 仅删除指定instance的指标
curl -X DELETE http://localhost:9091/metrics/job/batchjob1/instance/sidekiq_server

也可通过 Pushgateway 仪表板的「Delete Group」按钮手动删除。

五、客户端集成：以 Rails 为例

生产环境需通过 Prometheus 客户端库推送指标，以下是 Ruby on Rails 示例：

5.1 创建推送类

# lib/metricspush.rb
require 'prometheus/client'
require 'prometheus/client/push'

class MetricsPush
  attr_reader :job, :registry, :pushgateway_url

  def initialize
    @job = 'mwp-rails'
    @pushgateway_url = 'http://localhost:9091'
  end

  def registry
    @registry ||= Prometheus::Client.registry
  end

  # 定义计数器（支持Gauge/Summary/Histogram）
  def counter(name, desc, labels = {})
    registry.get(name) || registry.counter(name, desc)
  end

  # 推送指标到Pushgateway
  def push
    Prometheus::Client::Push.new(job, nil, pushgateway_url).add(registry)
  end
end

5.2 使用示例

# 初始化并推送指标
mp = MetricsPush.new
mp.counter(:test_counter, "测试计数器", service: 'mwp-rails-job').increment
mp.push

推送后可在 Pushgateway 仪表板查看

六、Prometheus 抓取 Pushgateway 配置

Pushgateway 仅为指标中转，最终需 Prometheus 拉取其指标，核心配置如下：

6.1 核心配置（prometheus.yml）

- job_name: pushgateway
  honor_labels: true  # 关键：保留指标原有job/instance标签
  file_sd_configs:    # 基于文件的服务发现（推荐）
    - files:
        - targets/pushgateway/*.json
      refresh_interval: 5m

6.2 目标文件（targets/pushgateway/pg_targets.json）

[{"targets": ["pg1.example.com:9091"]}]

6.3 honor_labels: true 核心作用

  • 开启：Prometheus 直接使用 Pushgateway 中指标的 job/instance 标签（保留指标源信息）；
  • 关闭：Prometheus 重命名原有标签为 exported_job/exported_instance，并附加自身抓取的 job/instance。

抓取后可在 Prometheus 中查看指标

七、避坑指南（核心重点）

  1. 拒绝“万能解”思维：仅用于短时任务/不可直连资源，长期可访问的资源优先用原生拉取模式；
  2. 避免单点故障：可部署多个 Pushgateway，结合 Prometheus 工作节点扩展，或使用 PushProx 替代（适用于NAT场景）；
  3. 指标不会自动过期：需手动删除无用指标，或定期清理（如通过脚本调用 DELETE API）；
  4. 不是聚合器：多次推送同一指标仅保留最后一次值，如需聚合需在客户端处理；
  5. 持久化注意事项：持久化文件路径避免空格（或正确转义），间隔根据业务调整（不宜过短）；
  6. 标签覆盖风险：路径中的标签会覆盖指标自身标签，需统一标签命名规范。

八、总结

Pushgateway 是 Prometheus 拉取架构的重要补充，解决了短时任务、网络隔离资源的指标采集问题，但需明确其“有限场景”定位。核心要点：

  • 部署：多环境安装简单，优先用配置管理工具；
  • 配置：重点关注端口、持久化、honor_labels；
  • 操作：指标推送需规范标签，无用指标及时删除；
  • 避坑：避免单点、拒绝滥用、关注指标残留。

Copyright © 2026 weew12