Skip to main content

PostgreSQL

Plugin: go.d.plugin Module: postgres

Overview

This collector monitors the activity and performance of Postgres servers, collects replication statistics, metrics for each database, table and index, and more.

It establishes a connection to the Postgres instance via a TCP or UNIX socket. To collect metrics for database tables and indexes, it establishes an additional connection for each discovered database.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Default Behavior

Auto-Detection

By default, it detects instances running on localhost by trying to connect as root and netdata using known PostgreSQL TCP and UNIX sockets:

  • 127.0.0.1:5432
  • /var/run/postgresql/

Limits

Table and index metrics are not collected for databases with more than 50 tables or 250 indexes. These limits can be changed in the configuration file.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per PostgreSQL instance

These metrics refer to the entire monitored application.

This scope has no labels.

Metrics:

MetricDimensionsUnit
postgres.connections_utilizationusedpercentage
postgres.connections_usageavailable, usedconnections
postgres.connections_state_countactive, idle, idle_in_transaction, idle_in_transaction_aborted, disabledconnections
postgres.transactions_durationa dimension per buckettransactions/s
postgres.queries_durationa dimension per bucketqueries/s
postgres.locks_utilizationusedpercentage
postgres.checkpoints_ratescheduled, requestedcheckpoints/s
postgres.checkpoints_timewrite, syncmilliseconds
postgres.bgwriter_halts_ratemaxwrittenevents/s
postgres.buffers_io_ratecheckpoint, backend, bgwriterB/s
postgres.buffers_backend_fsync_ratefsynccalls/s
postgres.buffers_allocated_rateallocatedB/s
postgres.wal_io_ratewriteB/s
postgres.wal_files_countwritten, recycledfiles
postgres.wal_archiving_files_countready, donefiles/s
postgres.autovacuum_workers_countanalyze, vacuum_analyze, vacuum, vacuum_freeze, brin_summarizeworkers
postgres.txid_exhaustion_towards_autovacuum_percemergency_autovacuumpercentage
postgres.txid_exhaustion_perctxid_exhaustionpercentage
postgres.txid_exhaustion_oldest_txid_numxidxid
postgres.catalog_relations_countordinary_table, index, sequence, toast_table, view, materialized_view, composite_type, foreign_table, partitioned_table, partitioned_indexrelations
postgres.catalog_relations_sizeordinary_table, index, sequence, toast_table, view, materialized_view, composite_type, foreign_table, partitioned_table, partitioned_indexB
postgres.uptimeuptimeseconds
postgres.databases_countdatabasesdatabases

Per repl application

These metrics refer to the replication application.

Labels:

LabelDescription
applicationapplication name

Metrics:

MetricDimensionsUnit
postgres.replication_app_wal_lag_sizesent_lag, write_lag, flush_lag, replay_lagB
postgres.replication_app_wal_lag_timewrite_lag, flush_lag, replay_lagseconds

Per repl slot

These metrics refer to the replication slot.

Labels:

LabelDescription
slotreplication slot name

Metrics:

MetricDimensionsUnit
postgres.replication_slot_files_countwal_keep, pg_replslot_filesfiles

Per database

These metrics refer to the database.

Labels:

LabelDescription
databasedatabase name

Metrics:

MetricDimensionsUnit
postgres.db_transactions_ratiocommitted, rollbackpercentage
postgres.db_transactions_ratecommitted, rollbacktransactions/s
postgres.db_connections_utilizationusedpercentage
postgres.db_connections_countconnectionsconnections
postgres.db_cache_io_ratiomisspercentage
postgres.db_io_ratememory, diskB/s
postgres.db_ops_fetched_rows_ratiofetchedpercentage
postgres.db_ops_read_rows_ratereturned, fetchedrows/s
postgres.db_ops_write_rows_rateinserted, deleted, updatedrows/s
postgres.db_conflicts_rateconflictsqueries/s
postgres.db_conflicts_reason_ratetablespace, lock, snapshot, bufferpin, deadlockqueries/s
postgres.db_deadlocks_ratedeadlocksdeadlocks/s
postgres.db_locks_held_countaccess_share, row_share, row_exclusive, share_update, share, share_row_exclusive, exclusive, access_exclusivelocks
postgres.db_locks_awaited_countaccess_share, row_share, row_exclusive, share_update, share, share_row_exclusive, exclusive, access_exclusivelocks
postgres.db_temp_files_created_ratecreatedfiles/s
postgres.db_temp_files_io_ratewrittenB/s
postgres.db_sizesizeB

Per table

These metrics refer to the database table.

Labels:

LabelDescription
databasedatabase name
schemaschema name
tabletable name
parent_tableparent table name

Metrics:

MetricDimensionsUnit
postgres.table_rows_dead_ratiodeadpercentage
postgres.table_rows_countlive, deadrows
postgres.table_ops_rows_rateinserted, deleted, updatedrows/s
postgres.table_ops_rows_hot_ratiohotpercentage
postgres.table_ops_rows_hot_ratehotrows/s
postgres.table_cache_io_ratiomisspercentage
postgres.table_io_ratememory, diskB/s
postgres.table_index_cache_io_ratiomisspercentage
postgres.table_index_io_ratememory, diskB/s
postgres.table_toast_cache_io_ratiomisspercentage
postgres.table_toast_io_ratememory, diskB/s
postgres.table_toast_index_cache_io_ratiomisspercentage
postgres.table_toast_index_io_ratememory, diskB/s
postgres.table_scans_rateindex, sequentialscans/s
postgres.table_scans_rows_rateindex, sequentialrows/s
postgres.table_autovacuum_since_timetimeseconds
postgres.table_vacuum_since_timetimeseconds
postgres.table_autoanalyze_since_timetimeseconds
postgres.table_analyze_since_timetimeseconds
postgres.table_null_columnsnullcolumns
postgres.table_sizesizeB
postgres.table_bloat_size_percbloatpercentage
postgres.table_bloat_sizebloatB

Per index

These metrics refer to the table index.

Labels:

LabelDescription
databasedatabase name
schemaschema name
tabletable name
parent_tableparent table name
indexindex name

Metrics:

MetricDimensionsUnit
postgres.index_sizesizeB
postgres.index_bloat_size_percbloatpercentage
postgres.index_bloat_sizebloatB
postgres.index_usage_statusused, unusedstatus

Alerts

The following alerts are available:

Alert nameOn metricDescription
postgres_total_connection_utilization postgres.connections_utilizationaverage total connection utilization over the last minute
postgres_acquired_locks_utilization postgres.locks_utilizationaverage acquired locks utilization over the last minute
postgres_txid_exhaustion_perc postgres.txid_exhaustion_percpercent towards TXID wraparound
postgres_db_cache_io_ratio postgres.db_cache_io_ratioaverage cache hit ratio in db ${label:database} over the last minute
postgres_db_transactions_rollback_ratio postgres.db_cache_io_ratioaverage aborted transactions percentage in db ${label:database} over the last five minutes
postgres_db_deadlocks_rate postgres.db_deadlocks_ratenumber of deadlocks detected in db ${label:database} in the last minute
postgres_table_cache_io_ratio postgres.table_cache_io_ratioaverage cache hit ratio in db ${label:database} table ${label:table} over the last minute
postgres_table_index_cache_io_ratio postgres.table_index_cache_io_ratioaverage index cache hit ratio in db ${label:database} table ${label:table} over the last minute
postgres_table_toast_cache_io_ratio postgres.table_toast_cache_io_ratioaverage TOAST hit ratio in db ${label:database} table ${label:table} over the last minute
postgres_table_toast_index_cache_io_ratio postgres.table_toast_index_cache_io_ratioaverage index TOAST hit ratio in db ${label:database} table ${label:table} over the last minute
postgres_table_bloat_size_perc postgres.table_bloat_size_percbloat size percentage in db ${label:database} table ${label:table}
postgres_table_last_autovacuum_time postgres.table_autovacuum_since_timetime elapsed since db ${label:database} table ${label:table} was vacuumed by the autovacuum daemon
postgres_table_last_autoanalyze_time postgres.table_autoanalyze_since_timetime elapsed since db ${label:database} table ${label:table} was analyzed by the autovacuum daemon
postgres_index_bloat_size_perc postgres.index_bloat_size_percbloat size percentage in db ${label:database} table ${label:table} index ${label:index}

Setup

Prerequisites

Create netdata user

Create a user with granted pg_monitor or pg_read_all_stat built-in role.

To create the netdata user with these permissions, execute the following in the psql session, as a user with CREATEROLE privileges:

CREATE USER netdata;
GRANT pg_monitor TO netdata;

After creating the new user, restart the Netdata agent with sudo systemctl restart netdata, or the appropriate method for your system.

Configuration

File

The configuration file name for this integration is go.d/postgres.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/postgres.conf

Options

The following options can be defined globally: update_every, autodetection_retry.

Config options
NameDescriptionDefaultRequired
update_everyData collection frequency.5no
autodetection_retryRecheck interval in seconds. Zero means no recheck will be scheduled.0no
dsnPostgres server DSN (Data Source Name). See DSN syntax.postgres://postgres:[email protected]:5432/postgresyes
timeoutQuery timeout in seconds.2no
collect_databases_matchingDatabases selector. Determines which database metrics will be collected. Syntax is simple patterns.no
max_db_tablesMaximum number of tables in the database. Table metrics will not be collected for databases that have more tables than max_db_tables. 0 means no limit.50no
max_db_indexesMaximum number of indexes in the database. Index metrics will not be collected for databases that have more indexes than max_db_indexes. 0 means no limit.250no

Examples

TCP socket

An example configuration.

jobs:
- name: local
dsn: 'postgresql://[email protected]:5432/postgres'

Unix socket

An example configuration.

Config
jobs:
- name: local
dsn: 'host=/var/run/postgresql dbname=postgres user=netdata'

Multi-instance

Note: When you define multiple jobs, their names must be unique.

Local and remote instances.

Config
jobs:
- name: local
dsn: 'postgresql://[email protected]:5432/postgres'

- name: remote
dsn: 'postgresql://[email protected]:5432/postgres'

Troubleshooting

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the postgres collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

  • Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].

    cd /usr/libexec/netdata/plugins.d/
  • Switch to the netdata user.

    sudo -u netdata -s
  • Run the go.d.plugin to debug the collector:

    ./go.d.plugin -d -m postgres

Getting Logs

If you're encountering problems with the postgres collector, follow these steps to retrieve logs and identify potential issues:

  • Run the command specific to your system (systemd, non-systemd, or Docker container).
  • Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep postgres

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector's name:

grep postgres /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:

docker logs netdata 2>&1 | grep postgres

Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.