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 會覆蓋客戶端上報的標簽。

---

六、最佳實踐與注意事項

? 最佳實踐：

1. 合理設計 job 和 instance 標簽
   使用有意義的 job 名稱和 instance 標簽，便于識別數據來源。

2. 避免重復推送相同指標
   多次推送相同 job + instance 的指標會導致舊數據被覆蓋，除非你明確希望如此。

3. 使用 TTL 清理過期數據
   可通過腳本定期清理長時間未更新的指標（例如使用 DELETE /metrics/job/<job>）。

4. 配合短時任務使用
   在 Kubernetes CronJob 或 AWS Lambda 等場景中，推送完成后清理指標是一種好習慣。

5. 不要濫用 Pushgateway
   對于長期運行的服務，盡量使用 Pull 模式暴露 /metrics 接口。

? 常見誤區：

1. 把 Pushgateway 當作遠程存儲
   Pushgateway 不是遠程寫入后端，不具備持久化能力，也不適合大規模指標聚合。

2. 所有服務都使用 Pushgateway 上報
   這會導致數據管理混亂，違背 Prometheus 的設計理念。

3. 忽視數據時效性問題
   如果沒有清理機制，歷史數據可能誤導監控結果。

---

七、擴展功能與高級用法

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 列表

---