Prometheus Pushgateway部署与监控实践指南

1. Pushgateway在Prometheus监控体系中的定位

Pushgateway是Prometheus生态中一个特殊的中间组件，它的核心作用是作为临时性指标的缓冲区。与Prometheus主服务主动拉取（pull）指标的常规工作模式不同，Pushgateway允许客户端通过HTTP协议主动推送（push）指标数据。这种设计主要解决以下几类监控场景：

• 短生命周期任务监控：对于执行时间短暂的批处理作业或定时任务，这些任务可能在Prometheus执行抓取前就已经结束运行。通过Pushgateway，这些任务可以在退出前将最终状态指标推送到网关暂存。

• 服务发现受限环境：在某些无法使用服务发现的网络环境中（如跨安全域监控），Pushgateway可以作为指标汇聚点。典型场景包括监控第三方API的调用状态或黑盒探测结果。

• 指标聚合中转：当需要将多个分散数据源的指标聚合成一个整体指标时（如分布式计算的阶段完成率），可以先将部分指标推送到Pushgateway再统一暴露。

重要提示：Pushgateway不应被用作长期指标存储方案。所有暂存指标默认保留2小时（可通过--persistence.interval参数调整），且没有数据压缩和聚合功能。长期存储仍应依赖Prometheus TSDB或其他时序数据库。

2. 部署环境准备与安装流程

2.1 系统环境要求

Pushgateway作为轻量级服务，对运行环境要求较低。以下是推荐的生产环境配置：

实测在4核CPU/8GB内存的机器上，Pushgateway可以稳定处理每秒5000+的指标推送请求。对于大多数企业场景，单独部署2C4G的实例已经足够。

2.2 二进制安装（推荐方式）

这是最快捷的部署方式，适合大多数Linux环境：

bash复制# 下载最新版本（当前为1.6.2）
wget https://github.com/prometheus/pushgateway/releases/download/v1.6.2/pushgateway-1.6.2.linux-amd64.tar.gz

# 解压并安装
tar xvf pushgateway-1.6.2.linux-amd64.tar.gz
sudo cp pushgateway-1.6.2.linux-amd64/pushgateway /usr/local/bin/
sudo chmod +x /usr/local/bin/pushgateway

# 验证版本
pushgateway --version

2.3 Docker容器化部署

对于已容器化的环境，推荐使用官方Docker镜像：

bash复制docker run -d \
  -p 9091:9091 \
  --name pushgateway \
  --restart always \
  prom/pushgateway:v1.6.2 \
  --web.listen-address=":9091" \
  --persistence.file="/data/metrics.store"

关键参数说明：

• --web.listen-address：服务监听端口
• --persistence.file：指标持久化存储路径（容器内需挂载volume）

2.4 系统服务配置（Systemd）

生产环境建议配置为系统服务实现自动管理：

ini复制# /etc/systemd/system/pushgateway.service
[Unit]
Description=Prometheus Pushgateway
After=network.target

[Service]
User=pushgateway
Group=pushgateway
ExecStart=/usr/local/bin/pushgateway \
  --web.listen-address=":9091" \
  --persistence.interval=5m \
  --persistence.file="/var/lib/pushgateway/metrics.store"
Restart=always

[Install]
WantedBy=multi-user.target

创建专用用户并启动服务：

bash复制sudo useradd --no-create-home --shell /bin/false pushgateway
sudo mkdir /var/lib/pushgateway
sudo chown pushgateway:pushgateway /var/lib/pushgateway
sudo systemctl daemon-reload
sudo systemctl enable --now pushgateway

3. Prometheus集成配置

3.1 基础抓取配置

在prometheus.yml中添加以下job配置：

yaml复制scrape_configs:
  - job_name: 'pushgateway'
    honor_labels: true  # 保留客户端提交的标签
    scrape_interval: 15s
    static_configs:
      - targets: ['pushgateway-ip:9091']

关键参数honor_labels必须设置为true，否则Prometheus会用instance标签覆盖客户端提交的原始标签。

3.2 指标过滤策略

为避免Pushgateway积累过多过期指标，建议配置指标过滤规则：

yaml复制scrape_configs:
  - job_name: 'pushgateway'
    metric_relabel_configs:
      - source_labels: [__name__]
        regex: 'up|push_time_seconds|push_failure_time_seconds'
        action: keep

这个配置只保留Pushgateway自身的健康指标和推送时间戳，其他业务指标需要根据实际需求调整正则表达式。

3.3 分片与高可用方案

当单个Pushgateway实例无法承受流量压力时，可以采用以下架构：

code复制                          +-----------------+
                          |  Load Balancer  |
                          +--------+--------+
                                   |
           +-----------------------+-----------------------+
           |                       |                       |
+----------+----------+  +--------+--------+  +-----------+-----------+
| Pushgateway Shard 1 |  | Pushgateway Shard 2 |  | Pushgateway Shard N |
+---------------------+  +---------------------+  +---------------------+

对应的Prometheus配置需要为每个分片单独配置job：

yaml复制scrape_configs:
  - job_name: 'pushgateway_shard1'
    static_configs:
      - targets: ['shard1-ip:9091']
  - job_name: 'pushgateway_shard2' 
    static_configs:
      - targets: ['shard2-ip:9091']

4. 客户端推送实践

4.1 基础推送示例

使用curl进行最简单的指标推送：

bash复制echo "example_metric 3.14" | curl --data-binary @- http://pushgateway:9091/metrics/job/some_job

这会在Pushgateway中创建一个指标路径：
/metrics/job/some_job/example_metric

4.2 带标签的推送

添加更多维度标签：

bash复制cat <<EOF | curl --data-binary @- http://pushgateway:9091/metrics/job/some_job/instance/some_instance
# TYPE example_counter counter
example_counter{env="prod",team="devops"} 42
# HELP example_gauge A sample gauge metric
example_gauge 6.28
EOF

生成的指标路径包含多层标签：
/metrics/job/some_job/instance/some_instance

4.3 使用Client SDK推送

各语言官方客户端库都支持Pushgateway集成：

Python示例：

python复制from prometheus_client import CollectorRegistry, Gauge, push_to_gateway

registry = CollectorRegistry()
g = Gauge('job_last_success', 'Last successful run', registry=registry)
g.set_to_current_time()

push_to_gateway('pushgateway:9091', job='batch_job', registry=registry)

Java示例：

java复制import io.prometheus.client.CollectorRegistry;
import io.prometheus.client.Gauge;
import io.prometheus.client.exporter.PushGateway;

public class Example {
  public static void main(String[] args) throws Exception {
    Gauge duration = Gauge.build()
        .name("job_duration_seconds")
        .help("Duration of job in seconds")
        .register();
    
    duration.set(42.5);
    
    PushGateway pg = new PushGateway("pushgateway:9091");
    pg.pushAdd(CollectorRegistry.defaultRegistry, "my_job");
  }
}

4.4 最佳实践建议

1. 标签设计原则：

   • 必须包含job标签标识任务类型
   • 建议包含instance标签标识任务实例
   • 业务标签应具有有限的可取值（如env=[prod,staging,dev]）

2. 推送频率控制：

   • 短任务：任务结束时推送最终状态
   • 长任务：周期性推送心跳指标（如每5分钟）
   • 避免高频推送（间隔<15秒可能影响Prometheus抓取）

3. 指标清理策略：

   bash复制# 删除特定job的所有指标
   curl -X DELETE http://pushgateway:9091/metrics/job/some_job
   
   # 删除特定instance的指标
   curl -X DELETE http://pushgateway:9091/metrics/job/some_job/instance/some_instance
   

5. 监控与维护

5.1 内置指标说明

Pushgateway自身暴露的关键监控指标：

5.2 健康检查配置

建议的Prometheus告警规则示例：

yaml复制groups:
- name: pushgateway
  rules:
  - alert: PushgatewayDown
    expr: up{job="pushgateway"} == 0
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "Pushgateway down (instance {{ $labels.instance }})"
      
  - alert: StalePushgatewayMetrics
    expr: time() - push_time_seconds > 3600
    for: 30m
    labels:
      severity: warning
    annotations:
      summary: "Metrics not updated in 1 hour (job {{ $labels.job }})"

5.3 性能调优参数

关键启动参数优化建议：

6. 常见问题排查

6.1 指标未出现在Prometheus中

检查步骤：

1. 确认Pushgateway指标端点可访问：

   bash复制curl -v http://pushgateway:9091/metrics
   

2. 检查Prometheus配置中honor_labels: true是否设置
3. 验证Prometheus的target页面显示Pushgateway为UP状态
4. 检查指标是否有有效的时间戳（使用push_time_seconds判断）

6.2 推送失败错误处理

常见错误代码及解决方案：

6.3 内存泄漏排查

当观察到Pushgateway内存持续增长时：

1. 检查活跃指标数量：

   bash复制curl -s http://pushgateway:9091/metrics | grep -c 'TYPE'
   

2. 确认是否有客户端未清理过期指标
3. 添加--log.level=debug查看详细请求日志
4. 考虑设置指标自动过期时间：

   bash复制# 启动时添加参数
   pushgateway --metric.lifetime=2h
   

7. 高级应用场景

7.1 批处理作业监控

典型的大数据作业监控方案：

bash复制#!/bin/bash

# 作业开始前推送开始标记
echo "job_start_time $(date +%s)" | curl --data-binary @- $PUSHGATEWAY/metrics/job/$JOB_NAME/instance/$INSTANCE_ID

# 执行实际作业
your_batch_job.sh

# 根据作业结果推送不同状态
if [ $? -eq 0 ]; then
  STATUS=1
else
  STATUS=0
fi

cat <<EOF | curl --data-binary @- $PUSHGATEWAY/metrics/job/$JOB_NAME/instance/$INSTANCE_ID
# TYPE job_status gauge
job_status $STATUS
# TYPE job_duration_seconds gauge
job_duration_seconds $SECONDS
EOF

# 清理本实例指标
curl -X DELETE $PUSHGATEWAY/metrics/job/$JOB_NAME/instance/$INSTANCE_ID

7.2 跨网络域监控

通过Pushgateway实现DMZ区监控数据采集：

code复制[DMZ区] 
  │
  ↓ (推送)
[Pushgateway] ← (抓取) [Prometheus Server]
  (仅开放9091端口)      (位于安全内网)

配置要点：

1. Pushgateway部署在边界网络区
2. 只允许DMZ机器访问Pushgateway的9091端口
3. Prometheus从内网抓取Pushgateway指标

7.3 与Grafana集成

推荐的面板配置：

1. 创建Pushgateway状态看板：
   • 使用push_time_seconds显示各job最后活跃时间
   • 设置颜色阈值（绿色<1h，黄色<6h，红色>6h）
2. 批处理作业统计看板：
   • 使用job_status计算成功率
   • 使用job_duration_seconds显示耗时分布
3. 预警指标：

   sql复制sum(rate(push_failure_time_seconds[5m])) by (job)
   

在Grafana中使用以下PromQL查询示例：

promql复制# 各job的指标新鲜度
time() - push_time_seconds{job!=""}

# 批处理作业成功率
avg(job_status) by (job)

# 推送失败率
rate(pushgateway_http_requests_total{code!~"2.."}[5m])