PostgreSQL

Auto-Detection

Built-in Metrics

Logs

Tutorial availableMonitoring PostgreSQL with Bleemeo

Read the tutorial

PostgreSQL is a powerful open-source relational database known for its reliability and feature set.

Auto-Detection

Glouton detects PostgreSQL by its process and listening port (default: 5432).

To enable metrics gathering, credentials are required. Glouton finds them automatically if PostgreSQL is running in a Docker container with username and password set through the environment variables POSTGRES_USER (defaults to postgres) and POSTGRES_PASSWORD.

By default, only aggregate metrics are gathered. To monitor specific databases, add them to the detailed_items setting.

When using Docker, you can set the databases to monitor and credentials via labels:

docker run --label glouton.detailed_items="bleemeo,postgres" --label glouton.username="USERNAME" --label glouton.password="PASSWORD" [...]

If auto-detected parameters are incorrect, or you want to monitor specific databases, override them manually:

Linux

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

  # For an additional PostgreSQL running outside a container
  - type: "postgresql"
    instance: "NAME_ASSOCIATED_WITH_YOUR_ADDITIONAL_SERVICE"
    username: "USERNAME"
    password: "PASSWORD"
    address: "127.0.0.1"
    port: 5433

  # For a PostgreSQL running in a Docker container
  - type: "postgresql"
    instance: "CONTAINER_NAME"
    username: "USERNAME"
    password: "PASSWORD"
    address: "172.17.0.2"
    port: 5432
    # Monitor the databases called "bleemeo" and "postgres"
    detailed_items:
      - bleemeo
      - postgres
EOF

Windows

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

service:
  # For a PostgreSQL running outside a container
  - type: "postgresql"
    username: "USERNAME"
    password: "PASSWORD"
    address: "127.0.0.1"
    port: 5432

  # For an additional PostgreSQL running outside a container
  - type: "postgresql"
    instance: "NAME_ASSOCIATED_WITH_YOUR_ADDITIONAL_SERVICE"
    username: "USERNAME"
    password: "PASSWORD"
    address: "127.0.0.1"
    port: 5433

  # For a PostgreSQL running in a Docker container
  - type: "postgresql"
    instance: "CONTAINER_NAME"
    username: "USERNAME"
    password: "PASSWORD"
    address: "172.17.0.2"
    port: 5432
    detailed_items:
      - bleemeo
      - postgres

Glouton automatically detects configuration changes.

Built-in Metrics

Metric	Description
service_status	Status of PostgreSQL
postgresql_blk_read_utilization	PostgreSQL data file block read utilization
postgresql_blk_read_utilization_sum	Sum of PostgreSQL data file block read utilization
postgresql_blk_write_utilization	PostgreSQL data file block write utilization
postgresql_blk_write_utilization_sum	Sum of PostgreSQL data file block write utilization
postgresql_blks_hit_sum	Number of blocks read from PostgreSQL cache per second
postgresql_blks_read_sum	Number of blocks read from disk per second
postgresql_commit_sum	Number of commits per second
postgresql_rollback_sum	Number of rollbacks per second
postgresql_temp_bytes_sum	Temporary file write throughput in bytes per second
postgresql_temp_files_sum	Number of temporary files created per second
postgresql_tup_deleted_sum	Number of rows deleted per second
postgresql_tup_fetched_sum	Number of rows fetched per second
postgresql_tup_inserted_sum	Number of rows inserted per second
postgresql_tup_returned_sum	Number of rows returned per second
postgresql_tup_updated_sum	Number of rows updated per second

Except for service_status, all metrics also exist without the _sum suffix when detailed_items is configured. For example, postgresql_commit with the item mycontainer_mydb corresponds to the number of commits per second on the database mydb running in the container mycontainer.

Logs

Glouton collects PostgreSQL logs for analysis in Bleemeo.

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 check only opens the TCP port — it runs no query:

Status text	Cause	Fix
TCP port 5432, Connection refused	PostgreSQL listens on another port, or listen_addresses excludes the address Glouton uses	Set address and port, or add the agent address to listen_addresses
TCP port N, connection timed out after 10 seconds	A firewall drops the packets	Open the port for the agent
Invalid TCP address "..."	A typo in the Glouton configuration	Fix the configuration

Note that a green check says nothing about authentication: PostgreSQL accepts the TCP connection before rejecting the login.

Metrics are Missing

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

A password is mandatory. As with MySQL, and unlike most other services, Glouton creates no PostgreSQL collector at all when the password is empty, so the service reports only service_status. This is by far the most common cause.

With a password, Glouton connects as host=... port=... user=<username, default postgres> password=... dbname=postgres sslmode=disable and reads pg_stat_database and pg_stat_bgwriter:

Reproduce the exact connection Glouton uses:

psql "host=127.0.0.1 port=5432 user=postgres password=PASSWORD dbname=postgres sslmode=disable" -c "SELECT datname, xact_commit FROM pg_stat_database LIMIT 5"

What you see	Cause	Fix
nothing — the collector is never created	No password configured	Set password in the Glouton configuration
password authentication failed for user "postgres"	Wrong credentials	Fix username and password
no pg_hba.conf entry for host "...", user "...", database "postgres", SSL off	pg_hba.conf requires TLS or does not cover the agent	Glouton connects with sslmode=disable, so a hostssl-only rule blocks it — add a host line for the agent address
role "..." does not exist	The role does not exist	Set username to an existing role
database "postgres" does not exist	The postgres database was dropped	Glouton always connects to the postgres database and this is not configurable — recreate it
no error	Per-database metrics missing	Aggregate metrics only are gathered by default; list the databases in detailed_items

See Also

If you run a connection pooler in front of PostgreSQL, see PgBouncer.