Client Library

In this lesson you’ll learn how to push metrics to the Prometheus Pushgateway using the official Python client library, prometheus_client. This walkthrough covers the three primary push operations, the common workflow for creating and registering metrics, and examples of using the client API.

Keywords: Prometheus Pushgateway, prometheus_client, pushadd_to_gateway, push_to_gateway, delete_from_gateway, CollectorRegistry, Gauge

Pushgateway operations at a glance

Operation	HTTP method	Python function	Behavior	Example
push (replace)	PUT	`push_to_gateway`	Replace all metrics for the specified job/grouping labels	`push_to_gateway('pushgateway:9091', job='batch', registry=registry)`
pushadd (merge/add)	POST	`pushadd_to_gateway`	Add or merge metrics into the group without deleting other metrics	`pushadd_to_gateway('user2:9091', job='batch', registry=registry)`
delete	DELETE	`delete_from_gateway`	Remove all metrics for the specified job/grouping labels	`delete_from_gateway('pushgateway:9091', job='batch')`

Minimal Python example

Below is a concise example that demonstrates the typical workflow:

Create a CollectorRegistry.
Define and register a Gauge.
Set a value.
Push the registry to the Pushgateway using pushadd_to_gateway (POST-like merge behavior).

from prometheus_client import CollectorRegistry, Gauge, pushadd_to_gateway

# Create a registry to hold the metrics for this job/process
registry = CollectorRegistry()

# Define a Gauge and register it with the registry
test_metric = Gauge(
    'test_metric',                 # metric name
    'This is an example metric',   # help/description
    registry=registry
)

# Set the metric value
test_metric.set(10)

# Push the registry to the Pushgateway (pushadd = POST-like behavior)
pushadd_to_gateway('user2:9091', job='batch', registry=registry)

Parameters explained

The first argument to the push function is the Pushgateway address, e.g. host:port ('pushgateway:9091').
job is a required grouping label; metrics are organized by job and optional additional grouping labels in the Pushgateway.
registry is the CollectorRegistry instance containing the metrics to push.

When you want to replace all metrics for a job, use push_to_gateway (PUT semantics). Use pushadd_to_gateway to add/merge metrics (POST semantics). To remove metrics for a job or grouping, use delete_from_gateway.

Additional imports and examples

If you need to perform replace or delete operations, import these functions:

from prometheus_client import push_to_gateway, delete_from_gateway

Example usages:

Replace (PUT semantics):
- push_to_gateway('pushgateway:9091', job='batch', registry=registry') # replaces metrics for job
Delete (DELETE semantics):
- delete_from_gateway('pushgateway:9091', job='batch') # deletes metrics for job

Ensure the Prometheus Pushgateway is reachable from your process. Choose job and any additional grouping labels carefully to avoid unintentionally overwriting or deleting other metrics.

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Pushgateway operations at a glance

Minimal Python example

Parameters explained

Additional imports and examples

Links and references

Watch Video

Practice Lab

​Pushgateway operations at a glance

​Minimal Python example

​Parameters explained

​Additional imports and examples

​Links and references

Watch Video

Practice Lab

Pushgateway operations at a glance

Minimal Python example

Parameters explained

Additional imports and examples

Links and references