pgmon/manpages/pgmon.1

.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