17.4.5 Pushgateway与短生命周期任务

Pushgateway用于短生命周期任务指标上报与缓存，解决批处理作业、Cron任务、一次性脚本无法被Prometheus主动抓取的问题。其工作模式为任务完成后主动推送指标到Pushgateway，由Prometheus定时拉取，指标生命周期由任务端控制与清理策略决定。适用场景包括批量ETL、备份与巡检脚本、构建与发布流水线、定时数据校验。原则上避免用于长期服务进程，防止指标过期、重复与高基数问题。

原理草图（推送→缓存→拉取）：

推送模型与分组语义：
- Job/Instance作为基本分组维度，建议区分环境与任务类型
- 使用Grouping Labels标识任务实例（如task_id、batch_id），避免高基数标签
- 并行任务需保证分组标签可唯一定位一个任务实例

安装与启动（Docker）#

# 1) 拉取镜像
docker pull prom/pushgateway:v1.6.2

# 2) 启动容器（本地监听9091）
docker run -d --name pushgateway \
  -p 9091:9091 \
  prom/pushgateway:v1.6.2

# 3) 验证服务可用
curl -s http://127.0.0.1:9091/-/ready && echo "pushgateway ready"

命令解释：
- -p 9091:9091 将容器端口映射到宿主机
- /-/ready 用于检查服务就绪状态

Prometheus抓取配置示例（/etc/prometheus/prometheus.yml）：

scrape_configs:
  - job_name: "pushgateway"
    honor_labels: true
    static_configs:
      - targets: ["127.0.0.1:9091"]

说明：
- honor_labels: true 保留Pushgateway上报的原始标签

典型推送流程示例（含命令与预期效果）#

1) 任务脚本生成指标并推送：

# 假设在备份任务结束后执行
cat <<'EOF' | curl --data-binary @- \
  http://127.0.0.1:9091/metrics/job/backup/instance/host1
# TYPE backup_duration_seconds gauge
backup_duration_seconds 12.7
# TYPE backup_success counter
backup_success 1
# TYPE backup_last_exit_code gauge
backup_last_exit_code 0
EOF

预期效果：
- Pushgateway缓存该分组指标
- Prometheus在下一次抓取中可见 backup_duration_seconds 等指标

2) 任务完成后清理：

# 删除单个任务实例
curl -X DELETE http://127.0.0.1:9091/metrics/job/backup/instance/host1

3) 并行任务分组示例：

# task_id区分并发作业
curl --data-binary "task_items_total 500" \
  http://127.0.0.1:9091/metrics/job/etl/instance/host1/task_id/20240301_01

脚本示例（含重试与幂等）#

#!/usr/bin/env bash
# /usr/local/bin/push_metrics.sh
set -euo pipefail

JOB="daily_check"
INSTANCE="$(hostname -s)"
URL="http://127.0.0.1:9091/metrics/job/${JOB}/instance/${INSTANCE}"

start_ts=$(date +%s)
sleep 1
exit_code=0
duration=$(( $(date +%s) - start_ts ))

cat <<EOF | curl --retry 3 --retry-delay 2 --data-binary @- "$URL"
# TYPE check_duration_seconds gauge
check_duration_seconds ${duration}
# TYPE check_last_exit_code gauge
check_last_exit_code ${exit_code}
# TYPE check_success counter
check_success 1
EOF

说明：
- --retry 避免短暂网络抖动导致任务失败
- 使用gauge记录最终值，保证重试幂等性

指标设计与规范#

指标类型建议为Counter与Gauge，避免Summary/Histogram导致推送体积膨胀
命名建议：业务域_动作_单位，如 batch_duration_seconds
标签数量控制在最小集合，避免将时间戳、随机ID写入标签
高并发任务建议添加 task_id，但避免无限制增长

排错与常见问题#

1) 指标不消失
原因：未清理或分组标签变化导致旧分组残留
处理：

# 查看当前缓存的分组
curl -s http://127.0.0.1:9091/metrics | head

# 删除指定分组
curl -X DELETE http://127.0.0.1:9091/metrics/job/backup/instance/host1

2) 重复指标/重复累计
原因：重试使用Counter，导致累加
处理：改用Gauge覆盖最终值，或增加唯一实例标签

3) Prometheus抓取失败
排查：

# 检查Pushgateway端口
ss -lntp | grep 9091

# 检查Prometheus目标状态
curl -s http://127.0.0.1:9090/targets | grep pushgateway

4) 高基数
原因：分组标签包含动态字段
处理：收敛标签，改为记录字段为指标值或日志

与告警配合建议#

对短任务以“失败/超时”为告警条件
使用“完成标记 + 时长阈值”组合，避免间歇性任务误报
对清理失败设置告警，防止指标长驻

练习#

1) 编写一个每分钟执行的脚本，推送cron_duration_seconds与cron_success指标。
2) 在Prometheus中添加抓取配置并验证目标状态。
3) 模拟任务失败（exit_code!=0）并观察告警规则是否触发。
4) 删除分组并确认指标从Prometheus中消失。