PostgreSQL Exporter Setup (with Alloy + Grafana Cloud Integration)

This guide documents the verified working configuration for installing and connecting Prometheus PostgreSQL Exporter to Grafana Alloy, which forwards metrics to Grafana Cloud.

---

1. Download & Install

cd /tmp
wget https://github.com/prometheus-community/postgres_exporter/releases/download/v0.9.0/postgres_exporter-0.9.0.linux-amd64.tar.gz
tar -xvf postgres_exporter-0.9.0.linux-amd64.tar.gz
sudo mv postgres_exporter-0.9.0.linux-amd64/postgres_exporter /usr/local/bin/postgres_exporter
sudo chmod +x /usr/local/bin/postgres_exporter

Verify:

/usr/local/bin/postgres_exporter --version

---

2. Create Environment File

This step is mandatory — systemd cannot safely parse passwords that contain special characters (like #), so we define the connection string in a standalone file.

Create /etc/postgres_exporter.env:

DATA_SOURCE_NAME="host=<db-hostname> user=<db-username> password=<db-password> 
dbname=<db-name> port=<db-port> sslmode=require"

Important notes:

• The entire value must be wrapped in double quotes.
• Azure PostgreSQL requires SSL, so keep sslmode=require.
• If your password has #, @, or spaces, quoting prevents systemd from truncating it.

---

3. Create Systemd Unit

Create /etc/systemd/system/postgres-exporter.service:

[Unit]
Description=Prometheus PostgreSQL Exporter
After=network.target

[Service]
EnvironmentFile=/etc/postgres_exporter.env
ExecStart=/usr/local/bin/postgres_exporter
Restart=always

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now postgres-exporter
sudo systemctl status postgres-exporter

---

4. Verify Exporter Metrics

Run:

curl -s http://127.0.0.1:9187/metrics | grep -E 'pg_|postgres' | head

Expected output example:

pg_up 1
pg_database_size_bytes{datname="prezence"} 123456789
pg_stat_database_tup_returned{datname="prezence"} 987654

If you only see go_ metrics:

• Check /etc/postgres_exporter.env quoting.
• Ensure the password wasn’t truncated by systemd.
• Confirm your Azure firewall allows the VM IP.

---

5. Add to Grafana Alloy

If you’re using Grafana Alloy to forward metrics to Grafana Cloud, edit the configuration file:

/etc/alloy/config.alloy

Append the following to your Alloy configuration file (keeping the same style used for Redis/Celery exporters):

prometheus.scrape "postgres" {
  targets = [
    { __address__ = "127.0.0.1:9187", },
  ]
  metrics_path = "/metrics"
  forward_to = [prometheus.relabel.metrics_instance.receiver]
}

Restart Alloy:

sudo systemctl restart alloy

Check Status:

sudo systemctl status alloy

6. Verify in Grafana Cloud

In Grafana Cloud → Explore, run:

up{__address__="127.0.0.1:9187"}

or check a Postgres metric:

pg_up

You should see 1 (meaning exporter is up and reporting).

---

7. Troubleshooting

Issue	Likely Cause	Fix
Only go_ metrics	DATA_SOURCE_NAME not loaded or truncated	Recheck /etc/postgres_exporter.env quotes
Auth or SSL error	Azure requires TLS	Keep sslmode=require
Port 9187 busy	Service already running	Stop service before manual test
No metrics in Grafana	Alloy not restarted	Restart Alloy and re-verify scrape config

---

Final Verification Checklist

Check	Command	Expected
Exporter binary installed	/usr/local/bin/postgres_exporter --version	shows version 0.9.0
Service running	systemctl status postgres-exporter	active (running)
Local metrics	curl -s http://127.0.0.1:9187/metrics	contains pg_ metrics
Grafana Cloud receiving	query pg_up	value = 1

---