PgBouncer

Auto-Detection

Built-in Metrics

PgBouncer is a lightweight connection pooler for PostgreSQL.

Auto-Detection

Glouton detects PgBouncer by its process and listening port (default: 6432).

To gather metrics, Glouton connects to PgBouncer’s virtual pgbouncer administration database and runs its SHOW commands. This requires a user (default: pgbouncer) that is allowed to query it — see the stats_users and admin_users settings in your PgBouncer configuration.

If the auto-detected parameters are incorrect, override them manually:

Linux
Windows

sudo tee /etc/glouton/conf.d/99-pgbouncer.conf > /dev/null << 'EOF'
service:
  # For a PgBouncer running outside a container
  - type: "pgbouncer"
    username: "pgbouncer"
    password: "PASSWORD"
    address: "127.0.0.1"
    port: 6432

  # For a PgBouncer running in a Docker container
  - type: "pgbouncer"
    instance: "CONTAINER_NAME"
    username: "pgbouncer"
    password: "PASSWORD"
    address: "172.17.0.2"
    port: 6432
EOF

Create or edit C:\ProgramData\glouton\conf.d\99-pgbouncer.conf:

service:
  # For a PgBouncer running outside a container
  - type: "pgbouncer"
    username: "pgbouncer"
    password: "PASSWORD"
    address: "127.0.0.1"
    port: 6432

  # For a PgBouncer running in a Docker container
  - type: "pgbouncer"
    instance: "CONTAINER_NAME"
    username: "pgbouncer"
    password: "PASSWORD"
    address: "172.17.0.2"
    port: 6432

Glouton automatically detects configuration changes.

Built-in Metrics

Metric	Description
`service_status`	Status of PgBouncer
`pgbouncer_pools_cl_active`	Client connections linked to a server connection and able to process queries
`pgbouncer_pools_cl_waiting`	Client connections that have sent a query but are waiting for a server connection
`pgbouncer_pools_maxwait`	Time the oldest waiting client has waited for a server connection, in seconds
`pgbouncer_pools_sv_active`	Server connections currently assigned to a client
`pgbouncer_pools_sv_idle`	Server connections that are idle and ready to serve a new query
`pgbouncer_query`	Number of SQL queries pooled per second
`pgbouncer_query_time_seconds`	Average time spent by PgBouncer processing a query, in seconds
`pgbouncer_received_bytes`	Network traffic received by PgBouncer, in bytes per second
`pgbouncer_sent_bytes`	Network traffic sent by PgBouncer, in bytes per second

Monitoring Troubleshooting

See Troubleshoot a Service Check or Missing Metrics for what applies to every service: finding the address and port Glouton really uses, what each check message means, and how to read the collection error — which does not appear in the agent logs at the default level.

The Service Check is not OK

The PgBouncer check only opens the TCP port — it sends no query — so it can only fail in three ways:

Status text	Cause	Fix
`TCP port 6432, Connection refused`	PgBouncer listens on another port. Glouton assumes `6432` and falls back to it whenever it cannot read the listening sockets of the process, so a PgBouncer kept on `5432` to stay transparent for existing clients lands here	Set `port` (and `address`) in the Glouton configuration
`TCP port N, connection timed out after 10 seconds`	A firewall drops the packets, or `listen_addr` does not cover the address Glouton uses	Align `listen_addr` and the Glouton `address`, or open the port
`Invalid TCP address "..."` / `Invalid TCP port "..."`	A typo in the `address` or `port` of the Glouton configuration	Fix the configuration

A PgBouncer whose check is green is therefore only proven to accept connections; whether Glouton can read its statistics is a separate question.

Metrics are Missing

A passing check says nothing about the metrics: they are collected separately.

Glouton connects to the virtual pgbouncer administration database, as the username from its configuration (default: pgbouncer), and runs SHOW STATS, SHOW POOLS, SHOW LISTS and SHOW DATABASES. Any of these failing leaves the service with only service_status.

Reproduce exactly what Glouton does, from the machine where the agent runs:

psql "host=127.0.0.1 port=6432 user=pgbouncer dbname=pgbouncer sslmode=disable" -c "SHOW STATS"

What you see	Cause	Fix
`no such user` or a permission error on the `SHOW` query	The user is not allowed on the administration database	Add the user to `stats_users` (read-only) or `admin_users` in `pgbouncer.ini`
`password authentication failed for user "pgbouncer"`	Wrong or missing password	Set `username` and `password` in the Glouton configuration, matching `auth_file`
`no such user`	The user is absent from `auth_file`	Add it, unless `auth_type = trust`, which needs no password at all
a TLS or connection error	PgBouncer requires TLS from its clients	Glouton connects with `sslmode=disable`; `client_tls_sslmode = require` therefore blocks it — allow plain-text connections from the agent
a connection error, alongside a high `pgbouncer_pools_cl_waiting` if metrics arrived before	`max_client_conn` reached	Raise the limit

If that command works and Glouton still reports nothing, check the plan: built-in pgbouncer_* metrics require the Professional plan, while the availability check is available on every plan.

To also monitor the PostgreSQL server behind PgBouncer, see PostgreSQL.