At the beginning of the check_pgactivity, the %services hash describes every available services.
The hash is defined this way :
my %services = (
# 'service_name' => {
# 'sub' => sub reference to call to run this service
# 'desc' => 'a desctiption of the service'
# }
'autovacuum' => {
'sub' => \&check_autovacuum,
'desc' => 'Check the autovacuum activity.'
},
...
'example' => {
'sub' => \&check_example,
'desc' => 'Check number of connections (example service).'
}
First, add the service_name and values for the sub and desc entries.
That is enough to declare a new service. You can now see your new service listed when you call check_pgactivity with the --list argument.
Now, define a new check_servicename function before the mark "End of SERVICE section in pod doc".
To know about arguments provided to the service support function, see the %args hash.
Get some inspiration from other service functions to see how to handle an new one, for example check_stat_snapshot_age is a good starter as it is really simple. Here are however some guidelines.
Your service has to identify itself with a variable $me. This variable will be used when calling the output functions. For example :
sub check_example {
my $me = 'POSTGRES_EXAMPLE';
Several other variables are defined :
@rs: array to store the result set of the monitoring query@perfdata: array to store the returned perdata@msg: array to store the returned messages@hosts: array to know the host(s) to query%args: hash containing service arguments
Consider using these variables names as a convention.
Also populate your own %args hash from the first argument :
my %args = %{ $_[0] };
Now the interesting stuff comes. You can declare a simple query to monitor something in your PostgreSQL server. Here we declare a query that may work with any PostgreSQL version, for example :
my $query = qq{ SELECT count(*) FROM pg_stat_activity};
If you must provide multiple queries for mulitple PostgreSQL versions, please refer to the section "Supporting multiple PostgreSQL versions".
If your service has to react according some user-thresholds, verify that the user has given the thresholds as arguments :
defined $args{'warning'} and defined $args{'critical'}
Use pod2usage to output the error message.
It is recommended to validate the format of the threshold using a regexp :
$args{'warning'} =~ m/^([0-9.]+)/
The parse_hosts function will populate the @hosts array :
@hosts = @{ parse_hosts %args };
If your service does not work until a given PostgreSQL version, use some code like :
is_compat $hosts[0], 'example', $PG_VERSION_95 or exit 1;
Query the database using the query function :
@rs = @{ query ( $hosts[0], $query ) };
In our example, we can directly get the result :
$num_connections = $rs[0][0];
Populate the @perfdata array with the resulting metrics :
push @perfdata => [ "connections_number", $num_connections, undef ];
You must provide some mandatory data in the @perfdata array :
- perfdata name
- the data itself, in numerical form
- the unit used:'B' for bytes, 's' for secondes or undef for raw numbers
The following data are optional :
- warning threshold
- critical threshold
- minimum value
- maximum value
Your service can return "ok" by calling the function of the same name :
return ok( $me, \@msg, \@perfdata );
check_pgactivity provides 4 functions for the 4 given A Nagios-compatible service states :
- ok
- warning
- critical
- unknown
check_pgactivity's documentation is handled in its source file, in POD format, as Plain Old Documentation format. Refer to the perlpod documentation for further informations.
See also the releasing.md file to see how to regenerate the documentation.
Test your service in several conditions, verify that it returns a OK, a warning or critical alert by simulating each conditions.
Test your service upon several PostgreSQL versions. Verify that the service returns an error for unsupported versions, and that every other versions work well.
The best way to submit your patch is to send a pull request in github.
Each major PostgreSQL version brings some incompatibilities from previous releases. You can easily add compatibility to a new PostgreSQL version by following some guidelines given here.
First, you have to add a new $PG_VERSION_XXX variable, as following :
my $PG_VERSION_MIN = 70400;
my $PG_VERSION_74 = 70400;
...
my $PG_VERSION_95 = 90500;
my $PG_VERSION_96 = 90600;
my $PG_VERSION_100 = 100000;
The value of the variable is given from the parameter server_version_num. You can look at the function set_pgversion() and is_compat() to see how it is used.
Then, you will probably have to adapt some queries for the new PostgreSQL version. In order to ease this process, most probes provides a %queries hash that stores a given query associated to a given PostgreSQL version. You don't have to write the same query for each major release, you can simply store the appropriate query for the version that enters the incompatibility, it will be used for each following version.
For example, the probe autovacuum, implemented in the check_autovacuum function provides the following hash :
my %queries = (
# field current_query, not autovacuum_max_workers
$PG_VERSION_81 => q{
SELECT current_query,
extract(EPOCH FROM now()-query_start)::bigint,
'NaN'
FROM pg_stat_activity
WHERE current_query LIKE 'autovacuum: %'
ORDER BY query_start ASC
},
# field current_query, autovacuum_max_workers
$PG_VERSION_83 => q{
SELECT a.current_query,
extract(EPOCH FROM now()-a.query_start)::bigint,
s.setting
FROM
(SELECT current_setting('autovacuum_max_workers') AS setting) AS s
LEFT JOIN (
SELECT * FROM pg_stat_activity
WHERE current_query LIKE 'autovacuum: %'
) AS a ON true
ORDER BY query_start ASC
},
# field query, still autovacuum_max_workers
$PG_VERSION_92 => q{
SELECT a.query,
extract(EPOCH FROM now()-a.query_start)::bigint,
s.setting
FROM
(SELECT current_setting('autovacuum_max_workers') AS setting) AS s
LEFT JOIN (
SELECT * FROM pg_stat_activity
WHERE query LIKE 'autovacuum: %'
) AS a ON true
ORDER BY a.query_start ASC
}
);
Then, call the query_ver() function, giving the host you want to query, usually $host[0], and the %queries hash :
@rs = @{ query_ver( $hosts[0], %queries ) };
query_ver() will do the job for you and use the appropriate query for the current PostgreSQL release and return the result in the @rs array.
Also, if a probe does not work until a given version, use a derivate of the following code :
is_compat $hosts[0], 'autovacuum', $PG_VERSION_81 or exit 1;
See the code around to look how to support new PostgreSQL versions. Sometimes you have to write a totally different code path to support a new release, as it happened for PostgreSQL 10. See for example check_archiver how it is handled.
One of the key feature of check_pgactivity consists of the ability to store intermediate results in a binary file. That allows to calculate delta values between two calls of the same service.
The underlying implementation uses the Storable library from the Perl language. Thus, you can easily store any Perl data structure into the resulting statistics file.
First, the load call will populate the data structure using the following arguments :
- the host structure ref that holds the "host" and "port" parameters
- the name of the structure to load
- the path to the file storage
As you may guess, there's also a save function to store the data structure into the statistics file with the following arguments :
- the host structure ref that holds the "host" and "port" parameters
- the name of the structure to save
- the ref of the structure to save
- the path to the file storage
See for example the function check_bgwriter to see how to use the functions and how to store your intermediate metrics.
Use the --debug option to enable the debug output.
Use dprint() function to output some specific debugging messages to the developer or the user.