Client Library

This guide shows how to push metrics from Python to a Prometheus Pushgateway using the Prometheus client library for Python. It focuses on the three primary operations you will use when pushing metrics and provides clear, copy-paste examples for common workflows.

push — replaces all metrics for a given job (HTTP PUT).
pushadd — merges the pushed metrics with any existing metrics for the same job, overriding any metrics with identical names while leaving other metrics intact (HTTP POST).
delete — removes all metrics for a given job/group (HTTP DELETE).

All three functions accept a registry argument (a CollectorRegistry instance) that contains the metrics you want to push. They also accept a job name and an optional grouping_key to distinguish different groups within the same job. Summary of Pushgateway client functions

Function	Behavior	Equivalent HTTP verb	Typical use case
`push_to_gateway`	Replace all metrics for the specified job	`PUT`	Short-lived batch jobs that should fully replace metrics for a job
`pushadd_to_gateway`	Merge pushed metrics with existing metrics for the job	`POST`	When multiple processes contribute different metrics under the same job
`delete_from_gateway`	Remove metrics for a job or grouping	`DELETE`	Cleanup when a job or instance finishes

CollectorRegistry and registry usage

Use CollectorRegistry to create an isolated registry that contains only the metrics you intend to push.
Register metrics with the registry either by passing registry=... when creating them, or by registering collectors explicitly.

Example — pushadd (merge) This example creates a CollectorRegistry, defines a Gauge, sets its value, and merges it into the Pushgateway’s existing metrics for job batch.

from prometheus_client import CollectorRegistry, Gauge, pushadd_to_gateway

# Create a registry to contain only the metrics we want to push.
registry = CollectorRegistry()

# Define a Gauge and register it explicitly with the registry.
test_metric = Gauge(
    'test_metric',
    'This is an example metric',
    registry=registry
)

# Set the metric value.
test_metric.set(10)

# Push (merge) metrics to the Pushgateway for job 'batch'.
# Replace 'user2:9091' with your Pushgateway host:port (for example, 'localhost:9091').
pushadd_to_gateway('user2:9091', job='batch', registry=registry)

Example — push (replace) Use push_to_gateway to replace all metrics for a job. This will overwrite any metrics previously stored for the specified job.

from prometheus_client import CollectorRegistry, Gauge, push_to_gateway

registry = CollectorRegistry()
g = Gauge('another_metric', 'Another example metric', registry=registry)
g.set(3.14)

# This will replace the entire metric set for job 'batch' at the Pushgateway.
push_to_gateway('user2:9091', job='batch', registry=registry)

Example — delete (remove metrics for a job or grouping) When a job finishes or you need to remove metrics, call delete_from_gateway. You can delete all metrics for a job or target a specific grouping using a grouping key.

from prometheus_client import delete_from_gateway

# Delete all metrics for job 'batch' from the Pushgateway.
delete_from_gateway('user2:9091', job='batch')

# To delete a specific grouping, pass a grouping_key dict:
# delete_from_gateway('user2:9091', job='batch', grouping_key={'instance': 'worker-1'})

Notes on grouping keys

Use the grouping_key parameter to distinguish different subsets of metrics within the same job (for example, one job per instance).
Pass a dict of label names to values, for example: grouping_key={'instance': 'worker-1'}.
The grouping_key argument is supported by push_to_gateway, pushadd_to_gateway, and delete_from_gateway.

The Pushgateway is intended for short-lived batch jobs or ephemeral processes that cannot be scraped directly by Prometheus. For long-running services, prefer exposing metrics via an HTTP endpoint and letting Prometheus scrape them directly.

Links and references

Prometheus Pushgateway: https://github.com/prometheus/pushgateway
Prometheus Python client: https://github.com/prometheus/client_python
Prometheus documentation: https://prometheus.io/docs/

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Watch Video

Practice Lab