Installation

This lesson shows how to install Prometheus Pushgateway, run it for testing, and configure Prometheus to scrape it. Use Pushgateway when short-lived or batch jobs need to push metrics to Prometheus.

1) Download Pushgateway

Download the latest Pushgateway release from the official GitHub Releases page:

https://github.com/prometheus/pushgateway/releases

The image shows a webpage for downloading the Prometheus Pushgateway with options for different operating systems and corresponding file details such as architecture, size, and SHA256 checksum.

2) Extract and run (quick test)

After downloading the release tarball on your server, extract it and change into the extracted directory:

wget https://github.com/prometheus/pushgateway/releases/download/v1.4.3/pushgateway-1.4.3.linux-amd64.tar.gz
tar xvzf pushgateway-1.4.3.linux-amd64.tar.gz
cd pushgateway-1.4.3.linux-amd64

For a quick test you can run the pushgateway binary directly; it listens on port 9091 by default:

./pushgateway

Open another terminal and verify the metrics endpoint:

curl localhost:9091/metrics
# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.665721119292e+09
# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 7.3271296e+08
# HELP process_virtual_memory_max_bytes Maximum amount of virtual memory available in bytes.
# TYPE process_virtual_memory_max_bytes gauge
process_virtual_memory_max_bytes 1.8446744073709552e+19
# HELP pushgateway_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which pushgateway was built.
# TYPE pushgateway_build_info gauge
pushgateway_build_info{branch="HEAD",goversion="go1.18.2",revision="f9dc1c8664050edbc75916c3664be1df595a1958",version="1.4.3"} 1

3) Install as a systemd service (recommended for production)

Run Pushgateway under systemd to ensure it starts on boot and is managed consistently. Create a dedicated system user and install the binary:

sudo useradd --no-create-home --shell /bin/false pushgateway
sudo cp pushgateway /usr/local/bin/
sudo chown pushgateway:pushgateway /usr/local/bin/pushgateway
sudo chmod 0755 /usr/local/bin/pushgateway

Create the systemd unit file at /etc/systemd/system/pushgateway.service with the following content:

[Unit]
Description=Prometheus Pushgateway
Wants=network-online.target
After=network-online.target

[Service]
User=pushgateway
Group=pushgateway
Type=simple
ExecStart=/usr/local/bin/pushgateway

[Install]
WantedBy=multi-user.target

Reload systemd, start and enable the service:

sudo systemctl daemon-reload
sudo systemctl start pushgateway
sudo systemctl enable pushgateway
sudo systemctl status pushgateway

Quick reference: common commands and locations

Purpose	Command / Path
Run binary for testing	`./pushgateway`
Systemd unit file	`/etc/systemd/system/pushgateway.service`
Installed binary	`/usr/local/bin/pushgateway`
Service user	`pushgateway`
Default listen port	`9091`

If your server has a firewall (for example ufw or firewalld), ensure port 9091 is open for Prometheus scrapes or only allow access from Prometheus servers. Running services as root is not recommended — the example above uses a dedicated unprivileged pushgateway user.

4) Configure Prometheus to scrape Pushgateway

Add Pushgateway as a scrape target in your prometheus.yml. In many setups you should enable honor_labels: true so label values pushed by clients (for example job and instance) are preserved in Prometheus instead of being replaced by the Pushgateway scrape labels. Example prometheus.yml snippet:

scrape_configs:
  - job_name: pushgateway
    honor_labels: true
    static_configs:
      - targets: ["192.168.1.168:9091"]

Use honor_labels: true when multiple jobs push metrics to Pushgateway and you want the original job and instance labels from the pushing clients to be preserved in Prometheus. Without this, Prometheus will overwrite those labels with the Pushgateway’s own scrape labels.

5) Verify end-to-end

Push a sample metric from a client (example using curl):

echo "my_job_metric 42" | curl --data-binary @- http://<PUSHGATEWAY_HOST>:9091/metrics/job/my_job/instance/one

Confirm metrics are visible on Pushgateway:

curl http://<PUSHGATEWAY_HOST>:9091/metrics

Confirm Prometheus scrapes the Pushgateway and the metric appears in Prometheus targets and in PromQL queries (use the Prometheus UI at /targets and /graph).

Troubleshooting tips

If metrics don’t appear in Prometheus:
- Verify prometheus.yml has the correct address and that Prometheus has reloaded.
- Check honor_labels behavior — it may affect label attribution.
- Confirm network/firewall rules allow Prometheus to reach port 9091.
Check logs:
- Pushgateway logs: journalctl -u pushgateway
- Prometheus logs: journalctl -u prometheus or view Prometheus UI logs.

Links and references

Prometheus Pushgateway Releases: https://github.com/prometheus/pushgateway/releases
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

1) Download Pushgateway

2) Extract and run (quick test)

3) Install as a systemd service (recommended for production)

Quick reference: common commands and locations

4) Configure Prometheus to scrape Pushgateway

5) Verify end-to-end

Troubleshooting tips

Links and references

Watch Video

​1) Download Pushgateway

​2) Extract and run (quick test)

​3) Install as a systemd service (recommended for production)

​Quick reference: common commands and locations

​4) Configure Prometheus to scrape Pushgateway

​5) Verify end-to-end

​Troubleshooting tips

​Links and references

Watch Video

1) Download Pushgateway

2) Extract and run (quick test)

3) Install as a systemd service (recommended for production)

Quick reference: common commands and locations

4) Configure Prometheus to scrape Pushgateway

5) Verify end-to-end

Troubleshooting tips

Links and references