Introduction

• Preserves metrics from short-lived jobs that cannot be scraped directly.
• Integrates seamlessly with Prometheus — the Pushgateway is just another scrape target.
• Supports push, pushadd (merge), and delete operations, plus client library helpers.

• The Pushgateway stores metrics pushed by short-lived jobs and exposes them via an HTTP endpoint.
• Prometheus scrapes the Pushgateway using normal scrape_configs; no special Prometheus logic is required.
• The Pushgateway is intended only for short-lived or push-only workflows, not as a long-term replacement for instrumenting always-on services.

• Prometheus Pushgateway documentation
• Prometheus documentation — scraping

​

How it works (high-level)

1. A batch job or short-lived process runs and collects metrics.
2. Before exiting, the job pushes its metrics to the Pushgateway.
3. The Pushgateway stores the metrics under a grouping key (labels derived from the request path).
4. Prometheus scrapes the Pushgateway at its scrape interval and ingests the stored metrics.

• The URL path encodes the grouping key. For example, /metrics/job/batch-job/instance/instance1 creates labels job="batch-job" and instance="instance1" on the stored metrics.

​

Quick reference: key concepts

​

Common Pushgateway operations

​

Example: push a metric using curl (text format)

# Push a single gauge metric value 42 for job "batch-job" and instance "instance1"
echo "my_batch_job_last_run_seconds 42" | \
  curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/batch-job/instance/instance1

• The data sent is in Prometheus text exposition format (my_batch_job_last_run_seconds 42).
• The request path /metrics/job/batch-job/instance/instance1 creates labels job="batch-job" and instance="instance1".
• The Pushgateway stores the metric and exposes it for scraping.

​

Example: Prometheus scrape configuration

scrape_configs:
  - job_name: 'pushgateway'
    static_configs:
      - targets: ['pushgateway.example.org:9091']

• Prometheus will scrape the Pushgateway endpoint and ingest any metrics that have been pushed there.
• Treat the Pushgateway just like any other scrape target in Prometheus.

​

Example: delete metrics for a grouping key

# Remove metrics for job "batch-job" and instance "instance1"
curl -X DELETE http://pushgateway.example.org:9091/metrics/job/batch-job/instance/instance1

• Use DELETE to remove stale or no-longer-relevant metrics and avoid cardinality growth.

​

Push modes and semantics

​

Client libraries (recommended)

• push / pushgateway.push (replace)
• pushadd / pushgateway.pushAdd (merge)
• delete / pushgateway.delete

​

Best practices and cautions

• Do not use the Pushgateway as a general-purpose metrics aggregator for long-running services. It is designed for short-lived jobs that cannot be scraped directly.
• Carefully design grouping keys (labels) to avoid unintentionally creating high cardinality. Avoid including highly variable labels (e.g., timestamps, unique IDs) in grouping keys.
• Regularly delete metrics for completed jobs if the data is no longer relevant, or implement lifecycle management to avoid stale series.
• Remember that metrics in the Pushgateway are treated “as if” they were exposed by the job. Incorrect labels or timestamps can produce misleading results.

​

Example workflow summary

1. Instrument your batch job to collect metrics (using a Prometheus client library if possible).
2. Before the job exits, push metrics to the Pushgateway using the appropriate method (PUT / POST).
3. Configure Prometheus to scrape the Pushgateway as a normal target.
4. Periodically delete or rotate metrics for completed jobs to prevent stale series.