From 7da20da930b429f36b65afb5930fd8e350c2bf90 Mon Sep 17 00:00:00 2001 From: Ben Tasker <88340935+btasker@users.noreply.github.com> Date: Tue, 3 Jan 2023 17:35:13 +0000 Subject: [PATCH] docs(inputs.postgresql): update readme and samples to note timeout behavior (#12446) --- plugins/inputs/postgresql/README.md | 198 ++++++++++-------- plugins/inputs/postgresql/sample.conf | 5 +- .../inputs/postgresql_extensible/README.md | 27 ++- .../inputs/postgresql_extensible/sample.conf | 2 +- 4 files changed, 143 insertions(+), 89 deletions(-) diff --git a/plugins/inputs/postgresql/README.md b/plugins/inputs/postgresql/README.md index 376eec39c..26dded752 100644 --- a/plugins/inputs/postgresql/README.md +++ b/plugins/inputs/postgresql/README.md @@ -1,5 +1,111 @@ # PostgreSQL Input Plugin +The `postgresql` plugin provides metrics for your PostgreSQL Server instance. +Recorded metrics are lightweight and use Dynamic Management Views supplied +by PostgreSQL. + +## Global configuration options + +In addition to the plugin-specific configuration settings, plugins support +additional global and plugin configuration settings. These settings are used to +modify metrics, tags, and field or create aliases and configure ordering, etc. +See the [CONFIGURATION.md][CONFIGURATION.md] for more details. + +[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md + +## Configuration + +```toml @sample.conf +# Read metrics from one or many postgresql servers +[[inputs.postgresql]] + ## specify address via a url matching: + ## postgres://[pqgotest[:password]]@localhost[/dbname]?sslmode=[disable|verify-ca|verify-full]&statement_timeout=... + ## or a simple string: + ## host=localhost user=pqgotest password=... sslmode=... dbname=app_production + ## + ## All connection parameters are optional. + ## + ## Without the dbname parameter, the driver will default to a database + ## with the same name as the user. This dbname is just for instantiating a + ## connection with the server and doesn't restrict the databases we are trying + ## to grab metrics for. + ## + address = "host=localhost user=postgres sslmode=disable" + ## A custom name for the database that will be used as the "server" tag in the + ## measurement output. If not specified, a default one generated from + ## the connection address is used. + # outputaddress = "db01" + + ## connection configuration. + ## maxlifetime - specify the maximum lifetime of a connection. + ## default is forever (0s) + ## + ## Note that this does not interrupt queries, the lifetime will not be enforced + ## whilst a query is running + # max_lifetime = "0s" + + ## A list of databases to explicitly ignore. If not specified, metrics for all + ## databases are gathered. Do NOT use with the 'databases' option. + # ignored_databases = ["postgres", "template0", "template1"] + + ## A list of databases to pull metrics about. If not specified, metrics for all + ## databases are gathered. Do NOT use with the 'ignored_databases' option. + # databases = ["app_production", "testing"] + + ## Whether to use prepared statements when connecting to the database. + ## This should be set to false when connecting through a PgBouncer instance + ## with pool_mode set to transaction. + prepared_statements = true +``` + +Specify address via a postgresql connection string: + +```text +host=localhost port=5432 user=telegraf database=telegraf +``` + +Or via an url matching: + +```text +postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=[disable|verify-ca|verify-full] +``` + +It is also possible to specify a query timeout maximum execution time (in ms) +for any individual statement passed over the connection + +```text +postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=[disable|verify-ca|verify-full]&statement_timeout=10000 +``` + +All connection parameters are optional. Without the dbname parameter, the driver +will default to a database with the same name as the user. This dbname is just +for instantiating a connection with the server and doesn't restrict the +databases we are trying to grab metrics for. + +A list of databases to explicitly ignore. If not specified, metrics for all +databases are gathered. Do NOT use with the 'databases' option. + +```text +ignored_databases = ["postgres", "template0", "template1"]` +``` + +A list of databases to pull metrics about. If not specified, metrics for all +databases are gathered. Do NOT use with the 'ignored_databases' option. + +```text +databases = ["app_production", "testing"]` +``` + +### TLS Configuration + +Add the `sslkey`, `sslcert` and `sslrootcert` options to your DSN: + +```shell +host=localhost user=pgotest dbname=app_production sslmode=require sslkey=/etc/telegraf/key.pem sslcert=/etc/telegraf/cert.pem sslrootcert=/etc/telegraf/ca.pem +``` + +## Metrics + This postgresql plugin provides metrics for your postgres database. It currently works with postgres versions 8.1+. It uses data from the built in _pg_stat_database_ and pg_stat_bgwriter views. The metrics recorded depend on @@ -36,92 +142,12 @@ More information about the meaning of these metrics can be found in the [1]: http://www.postgresql.org/docs/9.2/static/monitoring-stats.html#PG-STAT-DATABASE-VIEW -## Global configuration options - -In addition to the plugin-specific configuration settings, plugins support -additional global and plugin configuration settings. These settings are used to -modify metrics, tags, and field or create aliases and configure ordering, etc. -See the [CONFIGURATION.md][CONFIGURATION.md] for more details. - -[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md - -## Configuration - -```toml @sample.conf -# Read metrics from one or many postgresql servers -[[inputs.postgresql]] - ## specify address via a url matching: - ## postgres://[pqgotest[:password]]@localhost[/dbname]?sslmode=[disable|verify-ca|verify-full] - ## or a simple string: - ## host=localhost user=pqgotest password=... sslmode=... dbname=app_production - ## - ## All connection parameters are optional. - ## - ## Without the dbname parameter, the driver will default to a database - ## with the same name as the user. This dbname is just for instantiating a - ## connection with the server and doesn't restrict the databases we are trying - ## to grab metrics for. - ## - address = "host=localhost user=postgres sslmode=disable" - ## A custom name for the database that will be used as the "server" tag in the - ## measurement output. If not specified, a default one generated from - ## the connection address is used. - # outputaddress = "db01" - - ## connection configuration. - ## maxlifetime - specify the maximum lifetime of a connection. - ## default is forever (0s) - # max_lifetime = "0s" - - ## A list of databases to explicitly ignore. If not specified, metrics for all - ## databases are gathered. Do NOT use with the 'databases' option. - # ignored_databases = ["postgres", "template0", "template1"] - - ## A list of databases to pull metrics about. If not specified, metrics for all - ## databases are gathered. Do NOT use with the 'ignored_databases' option. - # databases = ["app_production", "testing"] - - ## Whether to use prepared statements when connecting to the database. - ## This should be set to false when connecting through a PgBouncer instance - ## with pool_mode set to transaction. - prepared_statements = true -``` - -Specify address via a postgresql connection string: +## Example Output ```text -host=localhost port=5432 user=telegraf database=telegraf -``` - -Or via an url matching: - -```text -postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=[disable|verify-ca|verify-full] -``` - -All connection parameters are optional. Without the dbname parameter, the driver -will default to a database with the same name as the user. This dbname is just -for instantiating a connection with the server and doesn't restrict the -databases we are trying to grab metrics for. - -A list of databases to explicitly ignore. If not specified, metrics for all -databases are gathered. Do NOT use with the 'databases' option. - -```text -ignored_databases = ["postgres", "template0", "template1"]` -``` - -A list of databases to pull metrics about. If not specified, metrics for all -databases are gathered. Do NOT use with the 'ignored_databases' option. - -```text -databases = ["app_production", "testing"]` -``` - -### TLS Configuration - -Add the `sslkey`, `sslcert` and `sslrootcert` options to your DSN: - -```shell -host=localhost user=pgotest dbname=app_production sslmode=require sslkey=/etc/telegraf/key.pem sslcert=/etc/telegraf/cert.pem sslrootcert=/etc/telegraf/ca.pem +postgresql,db=postgres_global,server=dbname\=postgres\ host\=localhost\ port\=5432\ statement_timeout\=10000\ user\=postgres tup_fetched=1271i,tup_updated=5i,session_time=1451414320768.855,xact_rollback=2i,conflicts=0i,blk_write_time=0,temp_bytes=0i,datid=0i,sessions_fatal=0i,tup_returned=1339i,sessions_abandoned=0i,blk_read_time=0,blks_read=88i,idle_in_transaction_time=0,sessions=0i,active_time=0,tup_inserted=24i,tup_deleted=0i,temp_files=0i,numbackends=0i,xact_commit=4i,sessions_killed=0i,blks_hit=5616i,deadlocks=0i 1672399790000000000 +postgresql,db=postgres,host=oss_cluster_host,server=dbname\=postgres\ host\=localhost\ port\=5432\ statement_timeout\=10000\ user\=postgres conflicts=0i,sessions_abandoned=2i,active_time=460340.823,tup_returned=119382i,tup_deleted=0i,blk_write_time=0,xact_commit=305i,blks_hit=16358i,deadlocks=0i,sessions=12i,numbackends=1i,temp_files=0i,xact_rollback=5i,sessions_fatal=0i,datname="postgres",blk_read_time=0,idle_in_transaction_time=0,temp_bytes=0i,tup_inserted=3i,tup_updated=0i,blks_read=299i,datid=5i,session_time=469056.613,sessions_killed=0i,tup_fetched=5550i 1672399790000000000 +postgresql,db=template1,host=oss_cluster_host,server=dbname\=postgres\ host\=localhost\ port\=5432\ statement_timeout\=10000\ user\=postgres active_time=0,idle_in_transaction_time=0,blks_read=1352i,sessions_abandoned=0i,tup_fetched=28544i,session_time=0,sessions_killed=0i,temp_bytes=0i,tup_returned=188541i,xact_commit=1168i,blk_read_time=0,sessions_fatal=0i,datid=1i,datname="template1",conflicts=0i,xact_rollback=0i,numbackends=0i,deadlocks=0i,sessions=0i,tup_inserted=17520i,temp_files=0i,tup_updated=743i,blk_write_time=0,blks_hit=99487i,tup_deleted=34i 1672399790000000000 +postgresql,db=template0,host=oss_cluster_host,server=dbname\=postgres\ host\=localhost\ port\=5432\ statement_timeout\=10000\ user\=postgres sessions=0i,datid=4i,tup_updated=0i,sessions_abandoned=0i,blk_write_time=0,numbackends=0i,blks_read=0i,blks_hit=0i,sessions_fatal=0i,temp_files=0i,deadlocks=0i,conflicts=0i,xact_commit=0i,xact_rollback=0i,session_time=0,datname="template0",tup_returned=0i,tup_inserted=0i,idle_in_transaction_time=0,tup_fetched=0i,active_time=0,temp_bytes=0i,tup_deleted=0i,blk_read_time=0,sessions_killed=0i 1672399790000000000 +postgresql,db=postgres,host=oss_cluster_host,server=dbname\=postgres\ host\=localhost\ port\=5432\ statement_timeout\=10000\ user\=postgres buffers_clean=0i,buffers_alloc=426i,checkpoints_req=1i,buffers_checkpoint=50i,buffers_backend_fsync=0i,checkpoint_write_time=5053,checkpoints_timed=26i,checkpoint_sync_time=26,maxwritten_clean=0i,buffers_backend=9i 1672399790000000000 ``` diff --git a/plugins/inputs/postgresql/sample.conf b/plugins/inputs/postgresql/sample.conf index e49d87865..c0ad245d6 100644 --- a/plugins/inputs/postgresql/sample.conf +++ b/plugins/inputs/postgresql/sample.conf @@ -1,7 +1,7 @@ # Read metrics from one or many postgresql servers [[inputs.postgresql]] ## specify address via a url matching: - ## postgres://[pqgotest[:password]]@localhost[/dbname]?sslmode=[disable|verify-ca|verify-full] + ## postgres://[pqgotest[:password]]@localhost[/dbname]?sslmode=[disable|verify-ca|verify-full]&statement_timeout=... ## or a simple string: ## host=localhost user=pqgotest password=... sslmode=... dbname=app_production ## @@ -21,6 +21,9 @@ ## connection configuration. ## maxlifetime - specify the maximum lifetime of a connection. ## default is forever (0s) + ## + ## Note that this does not interrupt queries, the lifetime will not be enforced + ## whilst a query is running # max_lifetime = "0s" ## A list of databases to explicitly ignore. If not specified, metrics for all diff --git a/plugins/inputs/postgresql_extensible/README.md b/plugins/inputs/postgresql_extensible/README.md index 8e2f936b6..5c2599f5d 100644 --- a/plugins/inputs/postgresql_extensible/README.md +++ b/plugins/inputs/postgresql_extensible/README.md @@ -26,7 +26,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # Read metrics from one or many postgresql servers [[inputs.postgresql_extensible]] # specify address via a url matching: - # postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=... + # postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=...&statement_timeout=... # or a simple string: # host=localhost port=5432 user=pqgotest password=... sslmode=... dbname=app_production # @@ -270,3 +270,28 @@ CREATE OR REPLACE VIEW public.sessions AS stat_activity stat WHERE proc.pid = stat.pid; ``` + +## Example Output + +The example out below was taken by running the query + +```sql +select count(*)*100 / (select cast(nullif(setting, '') AS integer) from pg_settings where name='max_connections') as percentage_of_used_cons from pg_stat_activity +``` + +Which generates the following + +```text +postgresql,db=postgres,server=dbname\=postgres\ host\=localhost\ port\=5432\ statement_timeout\=10000\ user\=postgres percentage_of_used_cons=6i 1672400531000000000 +``` + +## Metrics + +The metrics collected by this input plugin will depend on the configured query. + +By default, the following format will be used + +* postgresql + * tags: + * db + * server diff --git a/plugins/inputs/postgresql_extensible/sample.conf b/plugins/inputs/postgresql_extensible/sample.conf index e9c26c10d..46a2e6d50 100644 --- a/plugins/inputs/postgresql_extensible/sample.conf +++ b/plugins/inputs/postgresql_extensible/sample.conf @@ -1,7 +1,7 @@ # Read metrics from one or many postgresql servers [[inputs.postgresql_extensible]] # specify address via a url matching: - # postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=... + # postgres://[pqgotest[:password]]@host:port[/dbname]?sslmode=...&statement_timeout=... # or a simple string: # host=localhost port=5432 user=pqgotest password=... sslmode=... dbname=app_production #