Skip to main content

PostgreSQL collector

Overview

PostgreSQL, also known as Postgres, is a free and open-source relational database management system emphasizing extensibility and SQL compliance.

This collector monitors one or more Postgres servers, depending on your configuration.

Collected 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.

global

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

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

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

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

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

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

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 is go.d/postgres.conf.

The file format is YAML. Generally, the format is:

update_every: 1
autodetection_retry: 0
jobs:
- name: some_name1
- name: some_name1

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.5
autodetection_retryRe-check interval in seconds. Zero means not to schedule re-check.0
dsnPostgres server DSN (Data Source Name). See DSN syntax.postgres://postgres:[email protected]:5432/postgresyes
timeoutQuery timeout in seconds.2
collect_databases_matchingDatabases selector. Determines which database metrics will be collected. Syntax is simple patterns.
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.50
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.250

Examples

TCP socket

An example configuration.

Config
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

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

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