diff --git a/DEBIAN/control b/DEBIAN/control index 0e8bc21..b35b783 100644 --- a/DEBIAN/control +++ b/DEBIAN/control @@ -3,7 +3,7 @@ Version: 1.0 Section: utils Priority: optional Architecture: all -Depends: python3, python3-psycopg2, systemd +Depends: python3 (>= 3.6), python3-psycopg2, systemd Maintainer: James Campbell Homepage: https://www.commandprompt.com Description: A bridge to sit between monitoring tools and PostgreSQL diff --git a/manpages/pgmon.1 b/manpages/pgmon.1 index e69de29..147025b 100644 --- a/manpages/pgmon.1 +++ b/manpages/pgmon.1 @@ -0,0 +1,174 @@ +.TH PGMON 1 +.SH NAME +pgmon \- gather metrics from PostgreSQL on demand +.SH SYNOPSIS +.B pgmon +[\fIconfig\fR] +.SH DESCRIPTION +.B pgmon +acts as a bridge between monitoring software and a PostgreSQL cluster. +It listens for requests on the localhost interface, runs preconfigured queries to gather statistics from a PostgreSQL cluster, and passes back the results in JSON format. + +All configuration is done through a \fIconfig\fR file, which defaults to \fB/etc/pgmon/pgmon.yml\fR if not specified as the only argument. +See +.B "CONFIG FILE" +below for details on the syntax and settings. +.SH OPTIONS +.TP +.BR \fIconfig\fR +The config file to use (default: \fB/etc/pgmon/pgmon.yml\fR). +See below for config file syntax. +.SH CONFIG FILE +The +.B pgmon +config file is a YAML file that defines any number of settings, along with the metrics that can be requested. + +The only required element of the configuration file is the metric queries. +All other settings have default values. + +Any errors in the config file will cause it not to be read. +Unknown settings will be ignored. + +Along with the settings listed below, a list of additional files to include in the configuration can be specified as \fBinclude\fR. +These can either be absolute paths, or paths relative to the config file from which they are included. + +If a setting is configured in multiple locations, the last one encountered wins. +If a dictionary is defined multiple places, the first will be updated using the second. +Similarly, lists are appended (with the exception of the \fBinclude\fR setting, which is handled on a per-file basis. +No matter the order in which settings are defined in a config file, that file is processed prior to any files it includes. + +The below example will include two files. +\fBpgmon\fR will look for \fBmore_metrics.yml\fR in the same directory as the config file that contains these lines, while \fB/var/lib/pgmon/standard_metrics.yml\fR will be expected to be at that absolute path. + +.in 10 +include: + \- more_metrics.yml + \- /var/lib/pgmon/standard_metrics.yml +.in + +Config files can be included recursively, but be aware that \fBpgmon\fR currently makes no checks for loops. + +.SH CONFIG SETTINGS + +The below settings can be specified in a config file. + +.TP +.BR min_pool_size +The minimum number of connections to maintain per database in the cluster. +Default: \fB0\fR + +.TP +.BR max_pool_size +The maximum number of connections to maintain per database in the cluster. +Default: \fB4\fR + +.TP +.BR max_idle_time +The maximum amount of time (seconds) a connection can remain unused before it's closed (not implemented yet) +Default: \fB30\fR + +.TP +.BR log_level +The log level for \fBpgmon\fR. +Possible values are: \fBdebug\fR, \fBinfo\fR, \fBwarning\fR, \fBerror\fR, \fBcritical\fR. +Case does not matter for these. +Default: \fBerror\fR + +.TP +.BR dbuser +The database user to connect as. +Default: \fBpostgres\fR + +.TP +.BR dbhost +The host to connect to (DNS name, IP address, or path to unix socket directory). +Default: \fB/var/run/postgresql\fR + +.TP +.BR dbport +The port to connect to. +Default: \fB5432\fR + +.TP +.BR dbname +The default database to connect to when none is specified for a metric. +Default: \fBpostgres\fR + +.TP +.BR pool_slot_timeout +The number of seconds to wait to be given an open connection. +Default: \fB5\fR + +.TP +.BR connect_timeout +The timeout when connecting to the database. +Note that this time can be a little more than doubled due to the reconnect attempt logic. +Default: \fB5\fR + +.TP +.BR reconnect_cooldown +The number of seconds to leave a database alone after failing to connect to it. +Default: \fB30\fR + +.TP +.BR version_check_period +The number of seconds to cache the current version of PostgreSQL before \fBpgmon\fR checks it again. +Default: \fB300\fR + +.TP +.BR metrics +The definitions of all metrics \fBpgmon\fR knows about, along with their queries. +See \fBMETRIC DEFINITIONS\fR below. +Default: \fB{}\fR + +.SH METRIC DEFINITIONS + +Each metric definition specifies a \fIname\fR for the metric, a return \fRtype\fR for the data, and a set of \fIqueries\fR to use for various version of PostgreSQL. + +The \fIname\fR of the metric is used as the key in the dictionary of metrics. + +For metrics where there is one query to be used for any version of PostgreSQL, the version is set to \fB0\fR. + +For metrics that no longer apply to versions of PostgreSQL after a given version, the query for that version is defined as an empty string. + +Otherwise \fBpgmon\fR will use the query for the highest version of the query that does not exceed the version of PostgreSQL being monitored. + +Versions are specified as 5 or 6 digit integers, like what's returned by \fBSHOW server_version_num\fR. + +There are four possible return types: + +.BR value +A single scalar value. + +.BR row +A single row of values. + +.BR set +Multiple rows of values. + +.BR column +Multiple rows, each containing a single value, are returned as a list. + +Any \fIquery\fR can either be defined inline or read from a separate file. +To read a query from a file, prefix the path to the \fIfile\fR with \fBfile:\fR. +There can be no space between the colon (\fB:\fR) and the path. +The path can either be relative to the config file where the query is defined, or an absolute path. + +Requests can supply additional arguments that can be passed as query arguments. +These are referenced by name in the queries using \fB%(\fIname\fB)\fR syntax. + +Below are some example metrics to show the format. + +.in 10 +metrics: + \- pg_version: + type: value + query: + 0: SHOW sever_version_num + + \- discover_dbs: + type: set + query: + 0: SELECT datname AS dbname FROM pg_database + +