General availability (GA) Open source

`prometheus.exporter.postgres`

The prometheus.exporter.postgres component embeds the postgres_exporter for collecting metrics from a PostgreSQL database.

You can specify multiple prometheus.exporter.postgres components by giving them different labels.

Usage

prometheus.exporter.postgres "<LABEL>" {
    data_source_names = "<DATA_SOURCE_NAMES_LIST>"
}

Arguments

You can use the following arguments with prometheus.exporter.postgres:

Name	Type	Description	Default	Required
`data_source_names`	`list(secret)`	Specifies the PostgreSQL servers to connect to.		yes
`custom_queries_config_path`	`string`	Path to YAML file containing custom queries to expose as metrics.	`""`	no
`disable_default_metrics`	`bool`	When `true`, only exposes metrics supplied from `custom_queries_config_path`.	`false`	no
`disable_settings_metrics`	`bool`	Disables collection of metrics from `pg_settings`.	`false`	no
`enabled_collectors`	`list(string)`	List of collectors to enable. Refer to the information below for more detail.	`[]`	no

Refer to the PostgreSQL documentation for more information about the format of the connection strings in data_source_names.

Refer to the examples for the custom_queries_config_path file in the postgres_exporter repository.

By default, the same set of metrics is enabled as in the upstream postgres_exporter. If custom_queries_config_path is set, additional metrics defined in the given configuration file will be exposed. If disable_default_metrics is set to true, only the metrics defined in the custom_queries_config_path file will be exposed.

A subset of metrics collectors can be controlled by setting the enabled_collectors argument. The following collectors are available for selection:

database
database_wraparound
locks
long_running_transactions
postmaster
process_idle
replication
replication_slot
stat_activity_autovacuum
stat_bgwriter
stat_checkpointer - Only supported in PostgreSQL 17 and later
stat_database
stat_statements
stat_user_tables
stat_wal_receiver
statio_user_indexes
statio_user_tables
wal
xlog_location

By default, the following collectors are enabled:

database
locks
replication
replication_slot
stat_bgwriter
stat_database
stat_user_tables
statio_user_tables
wal

Blocks

You can use the following block with prometheus.exporter.postgres:

Name	Description	Required
`autodiscovery`	Database discovery settings.	no

`autodiscovery`

The autodiscovery block configures discovery of databases, outside of any specified in data_source_names.

The following arguments are supported:

Name	Type	Description	Default	Required
`database_allowlist`	`list(string)`	List of databases to filter for, meaning only these databases will be scraped.		no
`database_denylist`	`list(string)`	List of databases to filter out, meaning all other databases will be scraped.		no
`enabled`	`bool`	Whether to automatically discover other databases.	`false`	no

If enabled is set to true and no allowlist or denylist is specified, the exporter scrapes from all databases.

If autodiscovery is disabled, neither database_allowlist nor database_denylist has any effect.

Exported fields

The following fields are exported and can be referenced by other components.

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.postgres is only reported as unhealthy if given an invalid configuration.

Debug information

prometheus.exporter.postgres doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.postgres doesn’t expose any component-specific debug metrics.

Examples

Collect metrics from a PostgreSQL server

The following example uses a prometheus.exporter.postgres component to collect metrics from a PostgreSQL server running locally with all default settings:

// Because no autodiscovery is defined, this will only scrape the 'database_name' database, as defined
// in the DSN below.
prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://username:password@localhost:5432/database_name?sslmode=disable"]
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Collect custom metrics from an allowlisted set of databases

The following example uses a prometheus.exporter.postgres component to collect custom metrics from a set of specific databases, replacing default metrics with custom metrics derived from queries in /etc/alloy/custom-postgres-metrics.yaml:

prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://username:password@localhost:5432/database_name?sslmode=disable"]

  // This block configures autodiscovery to check for databases outside of the 'database_name' db
  // specified in the DSN above. The database_allowlist field means that only the 'frontend_app' and 'backend_app'
  // databases will be scraped.
  autodiscovery {
    enabled            = true
    database_allowlist = ["frontend_app", "backend_app"]
  }

  disable_default_metrics    = true
  custom_queries_config_path = "/etc/alloy/custom-postgres-metrics.yaml"
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Collect metrics from all databases except for a denylisted database

This example uses a prometheus.exporter.postgres component to collect custom metrics from all databases except for the secrets database.

prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://username:password@localhost:5432/database_name?sslmode=disable"]

  // The database_denylist field will filter out those databases from the list of databases to scrape,
  // meaning that all databases *except* these will be scraped.
  //
  // In this example it will scrape all databases except for the one named 'secrets'.
  autodiscovery {
    enabled           = true
    database_denylist = ["secrets"]
  }
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.