pganalyze Collector settings

The collector can be configured through one of three mechanisms:

1. Package-based install: INI config file, commonly in /etc/pganalyze-collector.conf
2. Docker-based install: INI config passed via the CONFIG_CONTENTS environment variable
3. Docker-based install: Individual environment variables for each setting (e.g. DB_HOST)

Most settings can be configured through either INI config settings or individual environment variables. When you set individual environment variables in addition to the INI config, the environment variable settings apply to all monitored servers. If both are present, the INI config takes precedence.

Note that a single collector instance can monitor more than one database server, by utilizing separate configuration sections in the INI config. Utilizing individual environment variables only supports configuring a single server.

For the INI config, the [pganalyze] section describes settings that apply to all servers. Other sections describe the servers to monitor, how to connect to them, and server-specific configuration settings. You should name the other sections after the servers they correspond to, though note these are not the names that will appear in the app. In-app names are based on hostname settings as determined during monitoring.

After you make changes, you can run pganalyze-collector --test to verify the new configuration. If the test succeeds, this will automatically load the new configuration in the collector background process (equivalent to using the --reload flag). This minimizes monitoring interruptions and simplifies config file updates.

The tables below list configuration settings, their defaults if not set, and their descriptions. If a setting is configurable through environment variables, the environment variable name follows the setting in parentheses. Environment variables for boolean settings expect 1 for true and 0 for false.

Note that these settings apply to the latest version of the collector.

General settings

Common settings for configuring collector behavior, independent of the platform.

Server connection settings

How to connect to the server(s) pganalyze will be monitoring. Note that when monitoring multiple databases on the same server, the first specified is considered the primary database. This is where helper functions are expected to be defined, and the one we connect to for server-wide metrics.

PII Filtering settings

We take the responsibility of access to your database very seriously. As discussed above, we already limit the direct access we have to your data, but some personally-identifiable information or other sensitive values can still come up in query text or logs. To address this, the collector has several settings to filter these before we collect them.

By default the pganalyze collector only filters logs that contain syntax errors (which may contain accidental copy and paste of passwords, etc), or could not be identified.

filter_log_secret: credential,parsing_error,unidentified

For servers containing sensitive information in the logs and to maximize data privacy (at the cost of less useful data in pganalyze) we recommend setting:

filter_log_secret: all
filter_query_sample: normalize
filter_query_text: unparsable

Note the normalize setting for filter_query_sample, which will remove all query parameter values from query samples, including those contained within automatically collected EXPLAIN plans.

In order to utilize auto_explain with this configuration, make sure to set auto_explain.log_format to json (other formats are currently not supported by the EXPLAIN normalization).

Schema filter settings

The pganalyze collector limits the number of schema objects (tables, views, etc.) that can be monitored on each database server. This limit is currently 5,000 tables or views per database server. If this limit is exceeded, no schema information will be collected.

You can avoid reaching this limit by using the following setting to select which tables/views should be excluded:

To validate whether the setting is working as intended, you can run a query on your database server to count the number of monitored tables and views. Note you would have to run this on each database on the server and then summarize the counts, which should not exceed the 5,000 limit in aggregate:

SELECT current_database() AS dbname,
       COUNT(*) AS table_and_view_count
  FROM pg_class c
       LEFT JOIN pg_catalog.pg_namespace n ON (n.oid = c.relnamespace)
 WHERE c.relkind IN ('r','v','m','p')
       AND c.relpersistence <> 't'
       AND c.relname NOT IN ('pg_stat_statements')
       AND n.nspname NOT IN ('pg_catalog','pg_toast','information_schema')
       AND (n.nspname || '.' || c.relname) !~* 'REGEXP';

Make sure to replace REGEXP with the value of your ignore_schema_regexp setting.

AWS settings

Only relevant if you are running your database in Amazon RDS or Amazon Aurora. See our RDS/Aurora setup instructions for details.

Note that the aws_endpoint_* settings are only relevant if you are using custom AWS endpoints. See the AWS documentation for details.

Azure settings

Only relevant if you are running your database in Azure using Azure Database for PostgreSQL. See our

Google Cloud Platform

Only relevant if you are running your database in GCP using Google Cloud SQL or Google AlloyDB. See the GCP setup instructions for details.

Crunchy Bridge settings

Only relevant if you are running your database in Crunchy Bridge.

Self-managed servers

If running on your own infrastructure, a platform other than the cloud providers listed above, or in a self-managed VM on a cloud provider, the configuration settings here may be useful.

OpenTelemetry exporter settings

To integrate with application performance monitoring (APM) tools, the collector can optionally act as an OpenTelemetry tracing exporter. This adds data from pganalyze into existing application traces, and allows application engineers to have a quick way to find out if slow database queries are causing performance problems in the app.

The exporter, if enabled, will send a tracing span for each collected EXPLAIN plan to the configured OpenTelemetry endpoint, with a link back to the full plan in pganalyze via the db.postgresql.plan span attribute.

Note that this requires queries to have parent span information propagated using the traceparent query tag, as defined in the W3 Trace Context specification. This is enabled on the application side by libraries like sqlcommenter.

Additional settings

Like the general settings above, but less commonly used. We only recommend using these settings after talking to pganalyze support.