> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pushing Metrics

> Guide to pushing Prometheus metrics to a Pushgateway via HTTP, covering URL grouping keys, curl examples, and POST PUT DELETE semantics for updating or deleting metric groups

This article explains how to push metrics to a Prometheus Pushgateway using the HTTP endpoint. You can push metrics in two ways:

* Send an HTTP request directly to the Pushgateway (covered here).
* Use a Prometheus client library to push metrics programmatically (not covered).

This guide covers URL structure, examples with `curl`, grouping behavior, and the different HTTP methods (POST, PUT, DELETE) and their semantics.

## HTTP push URL structure

The Pushgateway accepts metric pushes at an endpoint that encodes a grouping key in the URL path. The grouping key is derived from the `job` name and any additional label/value pairs encoded as path segments.

Pattern:

`http://<pushgateway_address>:<port>/metrics/job/<job_name>/<label1>/<value1>/<label2>/<value2>`

Key points:

* Labels encoded in the path are appended to every pushed metric and form part of the grouping key.
* The grouping key determines how metrics are grouped for updates and deletions.
* Always URL-encode label names and values that include special characters (slashes, spaces, etc.).

Reference:

* Prometheus Pushgateway documentation: [https://github.com/prometheus/pushgateway](https://github.com/prometheus/pushgateway)
* Prometheus text exposition format: [https://prometheus.io/docs/instrumenting/exposition\_formats/](https://prometheus.io/docs/instrumenting/exposition_formats/)

## Pushing a single metric with curl

Metric data must be sent in Prometheus' text exposition format. A common pattern is to pipe the metric text into `curl` with `--data-binary @-`, which reads the request body from stdin and sends a POST by default.

Example: push a simple metric named `example_metric` with value `4421` under `job="db_backup"`:

```bash theme={null}
echo "example_metric 4421" | curl --data-binary @- http://localhost:9091/metrics/job/db_backup
```

Explanation:

* `echo "example_metric 4421"` writes the metric in the text exposition format.
* `curl --data-binary @-` sends stdin as the request body (POST by default).
* The URL `http://localhost:9091/metrics/job/db_backup` sets the grouping key `job="db_backup"`.

Verify the metric is exposed by the Pushgateway:

```bash theme={null}
curl http://localhost:9091/metrics | grep example_metric
```

## Grouping behavior and label-based grouping keys

Metrics pushed to the same URL path—i.e., the same `job` and identical label/value path components—belong to the same group. Groups enable updating or deleting a set of metrics together.

Example: push two metrics into the same group (`job=archive`, `db=mysql`):

```bash theme={null}
cat <<EOF | curl --data-binary @- http://localhost:9091/metrics/job/archive/db/mysql
# TYPE metric_one counter
metric_one{label="val1"} 11
# TYPE metric_two gauge
# HELP metric_two Just an example.
metric_two 100
EOF
```

Push another group (`job=archive`, `app=web`):

```bash theme={null}
cat <<EOF | curl --data-binary @- http://localhost:9091/metrics/job/archive/app/web
# TYPE metric_one counter
metric_one{label="val1"} 22
# TYPE metric_two gauge
# HELP metric_two Just an example.
metric_two 200
# TYPE metric_three gauge
metric_three 300
EOF
```

Inspect metrics filtered for the `archive` job:

```bash theme={null}
curl http://localhost:9091/metrics | grep archive -A2 -B1
```

You will see metrics grouped by the path labels, for example:

```prometheus theme={null}
metric_one{db="mysql",job="archive",label="val1"} 11
metric_two{db="mysql",job="archive"} 100

metric_one{app="web",job="archive",label="val1"} 22
metric_two{app="web",job="archive"} 200
metric_three{app="web",job="archive"} 300
```

## POST vs PUT vs DELETE — semantics and examples

The HTTP method you use affects how metrics are updated in the target group.

| Method | Semantics                                                                                                                                                          | Common curl usage                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| POST   | Replace only metrics in the group that have the same metric name as those in the POST payload; other metrics in the group remain unchanged. Also adds new metrics. | `curl --data-binary @- http://localhost:9091/metrics/job/<job>/<labels>`        |
| PUT    | Replace the entire group at the target URL. Any previously stored metrics in that group are deleted and replaced by the PUT payload (idempotent).                  | `curl -X PUT --data-binary @- http://localhost:9091/metrics/job/<job>/<labels>` |
| DELETE | Delete the entire group at the target URL.                                                                                                                         | `curl -X DELETE http://localhost:9091/metrics/job/<job>/<labels>`               |

Note: `curl --data-binary @-` sends a POST by default. Use `-X PUT` or `-X DELETE` to get PUT or DELETE semantics.

### POST example

POST a new value for `metric_one` (replaces only that metric in the `archive/app=web` group):

```bash theme={null}
cat <<EOF | curl --data-binary @- http://localhost:9091/metrics/job/archive/app/web
# TYPE metric_one counter
metric_one{label="val1"} 44
EOF
```

Resulting group contents:

```prometheus theme={null}
metric_one{app="web",job="archive",label="val1"} 44
metric_two{app="web",job="archive"} 200
metric_three{app="web",job="archive"} 300
```

### PUT example

Replace the entire `archive/app=web` group with only `metric_one`:

```bash theme={null}
cat <<EOF | curl -X PUT --data-binary @- http://localhost:9091/metrics/job/archive/app/web
# TYPE metric_one counter
metric_one{label="val1"} 44
EOF
```

After this PUT, the `archive/app=web` group will contain only:

```Prometheus theme={null}
metric_one{app="web",job="archive",label="val1"} 44
```

All previously stored metrics in that group are removed.

### DELETE example

Delete the `archive/app=web` group entirely:

```bash theme={null}
curl -X DELETE http://localhost:9091/metrics/job/archive/app/web
```

After the DELETE, only metrics from other groups (for example, `db=mysql`) remain.

## Recap

* The grouping key is encoded in the path: `job` plus any additional label/value path segments.
* Labels in the path are appended to every pushed metric.
* Use POST to update specific metric names within a group (non-destructive for other metrics in the group).
* Use PUT to replace the entire group.
* Use DELETE to remove the entire group.
* URL-encode path segments that include special characters.

<Callout icon="lightbulb" color="#1CB2FE">
  When using `curl --data-binary @-`, curl sends a POST request by default. Use `-X PUT` or `-X DELETE` when you want the explicit PUT or DELETE semantics.
</Callout>

## Links and References

* Prometheus Pushgateway (GitHub): [https://github.com/prometheus/pushgateway](https://github.com/prometheus/pushgateway)
* Prometheus exposition formats: [https://prometheus.io/docs/instrumenting/exposition\_formats/](https://prometheus.io/docs/instrumenting/exposition_formats/)
* Prometheus client libraries: [https://prometheus.io/docs/instrumenting/clientlibs/](https://prometheus.io/docs/instrumenting/clientlibs/)

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/prometheus-certified-associate-pca/module/18b41166-411a-42a8-91c2-18a5b49bc189/lesson/2ea926a1-5349-4263-8205-7364ecbb84a1" />
</CardGroup>