【Prometheus 】通过 Pushgateway 上报指标数据
Prometheus 是目前最流行的开源监控系统之一，其拉取（pull）模型非常适合服务发现和静态目标的监控。然而，在某些场景下，例如短生命周期任务、批处理作业或无法暴露 HTTP 接口的服务，传统的拉取方式并不适用。此时，Pushgateway 就派上了用场。
本文将详细介绍 Prometheus Pushgateway 的标准上报协议、使用场景、最佳实践以及常见误区，帮助你构建一个稳定、可维护的监控上报机制。
一、Pushgateway 简介
Prometheus Pushgateway 是一个中间组件，允许用户以“推送”的方式将监控指标发送给它。Pushgateway 会将这些指标缓存，并供 Prometheus Server 拉取。
主要用途：
- 支持短时任务（如 cronjob）上报指标
- 为不支持 HTTP 暴露端点的服务提供指标中转
- 避免频繁重启导致指标丢失（如 CI/CD 作业）
二、Pushgateway 上报协议详解
Pushgateway 提供了一个简单的 HTTP 接口用于接收指标推送，其核心接口如下：
POST /metrics/job/<JOB_NAME>{/group_label/name}
1. URL 参数说明：
| 参数 | 必填 | 描述 |
|---|---|---|
job | ✅ | Prometheus 中定义的 job 名称，是必须参数 |
group_label.name | ❌ | 可选的一组标签，用于区分不同实例或分组 |
示例：
POST http://pushgateway.example.com:9091/metrics/job/my-job/instance/my-instance
2. 请求体格式（PLAIN TEXT）
请求体内容为 Prometheus 文本格式的指标输出，即类似于如下形式：
# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027
注意：所有指标都应包含 HELP 和 TYPE 注释行，虽然不是强制要求，但这是推荐的最佳实践。
三、客户端库推荐
大多数语言都有对应的 Prometheus 客户端库，可以直接生成符合规范的文本格式并推送到 Pushgateway。
以下是部分主流语言的客户端库推荐：
| 语言 | 客户端库 | 特性 |
|---|---|---|
| Go | prometheus/client_golang | 官方支持 Pusher 功能 |
| Python | prometheus_client | 支持 Pushgateway 推送 |
| Java | simpleclient_pushgateway | Spring Boot 集成友好 |
| Node.js | prom-client | 轻量级，易集成 |
四、典型上报流程示例（Python）
以下是一个使用 Python 向 Pushgateway 上报计数器指标的完整示例：
from prometheus_client import CollectorRegistry, Gauge, push_to_gatewayregistry = CollectorRegistry()
g = Gauge('some_metric', 'Description of metric', registry=registry)
g.set(10)push_to_gateway('http://pushgateway:9091', job='my-python-job', registry=registry)
该代码会向 Pushgateway 的 /metrics/job/my-python-job 路径推送一个名为 some_metric 的指标值。
五、Prometheus 配置示例
在 Prometheus 的配置文件中添加 Pushgateway 的 scrape 目标即可：
scrape_configs:- job_name: 'pushgateway'static_configs:- targets: ['pushgateway.example.com:9091']honor_labels: true # 保留客户端设置的标签
⚠️ 注意：建议设置
honor_labels: true，否则 Prometheus 会覆盖客户端上报的标签。
六、最佳实践与注意事项
✅ 最佳实践：
-
合理设计 job 和 instance 标签
使用有意义的 job 名称和 instance 标签，便于识别数据来源。 -
避免重复推送相同指标
多次推送相同 job + instance 的指标会导致旧数据被覆盖，除非你明确希望如此。 -
使用 TTL 清理过期数据
可通过脚本定期清理长时间未更新的指标（例如使用DELETE /metrics/job/<job>）。 -
配合短时任务使用
在 Kubernetes CronJob 或 AWS Lambda 等场景中，推送完成后清理指标是一种好习惯。 -
不要滥用 Pushgateway
对于长期运行的服务，尽量使用 Pull 模式暴露/metrics接口。
❌ 常见误区：
-
把 Pushgateway 当作远程存储
Pushgateway 不是远程写入后端，不具备持久化能力，也不适合大规模指标聚合。 -
所有服务都使用 Pushgateway 上报
这会导致数据管理混乱，违背 Prometheus 的设计理念。 -
忽视数据时效性问题
如果没有清理机制，历史数据可能误导监控结果。
七、扩展功能与高级用法
1. 删除特定指标
可以通过 DELETE 方法删除某个 job 的指标：
DELETE /metrics/job/my-job/instance/my-instance
2. 查询当前指标状态
访问 Pushgateway 的 Web 页面或直接访问：
GET /metrics
可以查看当前缓存的所有指标。
八、总结
Pushgateway 是 Prometheus 生态中一个非常有用的补充工具，尤其适用于短时任务和无法暴露 HTTP 接口的场景。了解其标准上报协议、正确使用方法及最佳实践，能够帮助我们更高效地构建监控体系。
| 场景 | 推荐方式 |
|---|---|
| 长时服务 | 暴露 /metrics 接口，由 Prometheus 拉取 |
| 短时任务 | 使用 Pushgateway 推送指标 |
| 批处理作业 | 推送后清理数据 |
| 无暴露能力的服务 | 通过 Sidecar 或脚本推送至 Pushgateway |
九、参考资料
- Pushgateway 官方文档
- Prometheus 数据模型
- Client Libraries 列表