Configuration settings reference - CHERTS/pgscv GitHub Wiki

Configuration settings reference.

pgSCV configuration settings can be defined using YAML configuration file or environment variables.

Location of the configuration file could be specified at startup using --config-file option. It is recommended to store configuration in /etc/pgscv.yaml. Since version 0.8.2, merging settings from environment variables and the configuration file is supported. Settings from environment variables take precedence.
When configuration file is not specified, pgSCV is looking for configuration settings in environment variables PGSCV_CONFIG_FILE.
If no environment variables found, pgSCV runs with default settings.

YAML settings:

listen_address: network address and port where the application should listen on. Environment variable: PGSCV_LISTEN_ADDRESS. Default value: 127.0.0.1:9890.
authentication: enable basic authentication and TLS encryption. Disabled by default.
- username: authentication username. Environment variable: PGSCV_AUTH_USERNAME. Default value: "" (disabled).
- password: authentication password. Environment variable: PGSCV_AUTH_PASSWORD. Default value: "" (disabled).
- keyfile: path to file with the secret key in the PEM format. Environment variable: PGSCV_AUTH_KEYFILE. Default value: "" (disabled).
- certfile: path to file with the certificate in the PEM format. Environment variable: PGSCV_AUTH_CERTFILE. Default value: "" (disabled).
no_track_mode: controls tracking of sensitive information, such as query texts. Environment variable: PGSCV_NO_TRACK_MODE. Default value: false (disabled).
collect_top_query: collect only TOP k queries in postgres/statements collector. Environment variable: PGSCV_COLLECT_TOP_QUERY. Default disabled. Since version 0.9.0
collect_top_table: collect only statistics for TOP k tables in postgres/tables collector. Environment variable: PGSCV_COLLECT_TOP_TABLE. Default disabled. Since version 0.9.0
collect_top_index: collect only statistics for the TOP k indexes in the postgres/indexes collector. Environment variable: PGSCV_COLLECT_TOP_INDEX. Default disabled. Since version 0.9.0
skip_conn_error_mode: skip database connection errors when creating a monitoring service instance. Environment variable: PGSCV_SKIP_CONN_ERROR_MODE. Default false. Since version 0.9.3
services: dictionary of services to which pgSCV should connect and monitor. Environment variable: see here for details. If the setting is not specified, the pgSCV service will terminate. See example for details.
- service_type: type of the service, must be one of postgres, pgbouncer, patroni.
- conninfo: connection string or DSN for connecting to service (only for service_type postgres, pgbouncer).
- baseurl: base connection URI used for connecting to Patroni services (only for service_type patroni).
defaults: default requisites for connecting to auto-discovered services (no environment variables supported). This setting is marked as deprecated and will be removed in future releases. Please don't use it!:
- postgres_dbname: database name for connecting to services which are identified as Postgres. Default value: "postgres".
- postgres_username: username for connecting to services which are identified as Postgres. Default value: "pgscv".
- postgres_password: password for connecting to services which are identified as Postgres. Default value: "".
- pgbouncer_dbname: database name for connecting to services which are identified as Pgbouncer. Default value: "pgbouncer".
- pgbouncer_username: username for connecting to services which are identified as Pgbouncer. Default value: "pgscv".
- pgbouncer_password: password for connecting to services which are identified as Pgbouncer. Default value: "".
databases: regular expression which defines databases from which builtin metrics should be collected. Environment variable: PGSCV_DATABASES. This option is not propagated on user-defined metrics specified in collector settings.
filters: per-collector filtering rules for including or excluding specific collector objects. Exclude rules has higher priority over include rules. No environment variables supported.
- collector_name/label_name: exact name of collector.
  - include: regexp string for including objects.
  - exclude: regexp string for excluding objects. Has higher priority over include.
Supported filters. Currently, only the following list of filters are available:
- diskstats/device: exclude: ^(ram|loop|fd|sr|(h|s|v|xv)d[a-z]|nvme\d+n\d+p)\d+$
- netdev/device: exclude: docker|virbr
- filesystem/fstype: include: ^(ext3|ext4|xfs|btrfs)$
disable_collectors: list of collectors which should be disabled. Environment variable: PGSCV_DISABLE_COLLECTORS - comma separated list of collectors. Default value: [] (all collectors are enabled).
collectors: per-collectors settings. Each entry is a name of collector. Main purpose of collectors is configuring user-defined metrics. No environment variables supported.
- subsystems: per-subsystems settings. Each entry defines exact subsystem.
  - databases: defines regular expression for databases where user-defined metrics of this subsystem should be collected
  - query: defines query used for getting metrics data
  - metrics: list of user metrics should be collected from queried data
    - name: metric name
    - usage: type of metric: GAUGE or COUNTER
    - value: name of column with metric value
    - labeled_values: name of label and names of columns with metric values
    - labels: list of columns names with label values
    - description: metric description

YAML Configuration file example

Complete YAML configuration file example:

listen_address: 127.0.0.1:9890
authentication:
  username: monitoring
  password: supersecretpassword
  keyfile: /etc/ssl/private/ssl-cert-snakeoil.key
  certfile: /etc/ssl/certs/ssl-cert-snakeoil.pem
no_track_mode: false
#collect_top_query: 10
#collect_top_table: 10
#collect_top_index: 10
skip_conn_error_mode: false
services:
  "postgres:5432":
    service_type: "postgres"
    conninfo: "postgres://postgres:[email protected]:5432/postgres"
  "pgbouncer:6432": 
    service_type: "pgbouncer"
    conninfo: "postgres://pgbouncer:[email protected]:6432/pgbouncer"
  "patroni1":
    service_type: "patroni"
    baseurl: "http://localhost:8008"
  "patroni2":
    service_type: "patroni"
    baseurl: "http://localhost:8009"
  "patroni3":
    service_type: "patroni"
    baseurl: "http://localhost:8010"
databases: "^(a-z_)+_prod$"
collectors:
  postgres/custom:
    filters:
      database:
        exclude: "^(staging)_.+$"
    subsystems:
      table:
        databases: "test[0-9]+|pgbench"
        query: "select schemaname,relname,seq_scan,n_tup_ins,n_tup_upd,n_tup_del from pg_stat_user_tables"
        metrics:
          - name: seq_scans
            usage: COUNTER
            value: seq_scan
            labels:
              - schemaname
              - relname
            description: "Total number of tuples by operation."
          - name: tuples_totals
            usage: COUNTER
            labeled_values:
              tuples: [ n_tup_ins, n_tup_upd, n_tup_del ]
            labels:
              - schemaname
              - relname
            description: "Total number of tuples by operation."

Configuring connection settings using environment variables.

Connecting to network services (Postgres or Pgbouncer) is possible without YAML configuration, using environment variables only:

POSTGRES_DSN is used for defining connection string used for connecting to Postgres services.
DATABASE_DSN is used for defining connection string used for connecting to Postgres services. This is an alias for POSTGRES_DSN, which allows to use an environment variable shared across several applications.
PGBOUNCER_DSN is used for defining connection string used for connecting to Pgbouncer services.
PATRONI_URL is used for defining base connection URI used for connecting to Patroni services.

It is possible to use expanded syntax and specify more than one connection strings:

POSTGRES_DSN<SERVICE_ID>
POSTGRES_DSN_<SERVICE_ID>
DATABASE_DSN<SERVICE_ID>
DATABASE_DSN_<SERVICE_ID>
PGBOUNCER_DSN<SERVICE_ID>
PGBOUNCER_DSN_<SERVICE_ID>
PATRONI_URL<SERVICE_ID>
PATRONI_URL_<SERVICE_ID>

Where <SERVICE_ID> is alpha-numeric value used as value for service_id label of exposed metrics.

It is recommended to use common env. variables syntax: uppercase letters, digits, and the '_' (underscore). For more fine-grained service_id naming use YAML configuration.

Important note: Make sure values used as a SERVICE_ID are unique across all used environment variables.

Connection string could be specified in libpq supported formats: as a keyword/value, or a connection URI string.

Examples:

$ DATABASE_DSN="host=127.0.0.1 port=5432 user=pgscv dbname=postgres" pgscv

$ POSTGRES_DSN="postgresql://pgscv:[email protected]:5432/postgres" pgscv

$ PGBOUNCER_DSN="postgresql://pgscv:[email protected]:6432/pgbouncer" pgscv

$ PATRONI_URL="http://localhost:8008" pgscv

$ POSTGRES_DSN_SRV1="postgresql://pgscv:[email protected]:5432/postgres" POSTGRES_DSN_SRV2="postgresql://pgscv:[email protected]:5432/postgres" pgscv

$ PATRONI_URL_patroni1="http://localhost:8008" PATRONI_URL_patroni2="http://localhost:8009" pgscv

Configuration settings reference - CHERTS/pgscv GitHub Wiki