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