Munin::...::Pgsql(3)

Hey bestie 💖 welcome to the Munin::...::Pgsql(3) page — it's part of the User Contributed Perl Documentation, and it's all about Munin::Plugin::Pgsql, the base module that PostgreSQL Munin plugins build on. Think of it as the shared group chat that gives all the Postgres plugins their config and API energy. 🫶

🌸 NAME 🌸

Munin::Plugin::Pgsql — the base module for PostgreSQL plugins for Munin. That's the whole name, and it's iconic. 👑

✨ SYNOPSIS ✨

The Munin::Plugin::Pgsql module provides base functionality for all PostgreSQL Munin plugins, including common configuration parameters. It's giving shared foundation, and honestly? Obsessed. ✨

🎀 CONFIGURATION 🎀

All configuration is done through environment variables. No config file drama, just env vars. 💅

💅 ENVIRONMENT VARIABLES 💅

All plugins based on Munin::Plugin::Pgsql accept all the environment variables that libpq does. The most common ones used are:

• PGHOST — hostname to connect to, or path to Unix socket
• PGPORT — port number to connect to
• PGUSER — username to connect as
• PGPASSWORD — password to connect with, if a password is required

By default, the plugins connect to the 'template1' database — except for wildcard per-database plugins. You can override that with the PGDATABASE variable, but this is usually a bad idea. Like, don't do it unless you know why. 😭

If you're using the plugin for several Postgres instances, you can customize the graph title with the PGLABEL environment variable. Cute, right? 🎀

Warning and critical can be customized by setting the warning and critical env variables per plugin. Set those thresholds and let the plugin know what's dramatic. 🔥

🍓 Example 🍓

[postgres_*]
   user postgres
   env.PGUSER postgres
   env.PGPORT 5433

 [postgres_connections_ALL]
   env.warning :450
   env.critical :500

🦋 WILDCARD MATCHING 🦋

Wildcard plugins based on this module match on whatever type of object you specify for a filter — usually a database. If the object name ALL is used (for example, a symlink to postgres_connections_ALL), the filter is not applied, and the plugin behaves like a non-wildcard one. It's literally just doing the most. ✨

🌈 REQUIREMENTS 🌈

The module requires DBD::Pg to work. That's the dependency, no cap. 🫶

🔥 TODO 🔥

Support for using psql instead of DBD::Pg, so the dependency can be removed. Future upgrade vibes. ⭐

💀 BUGS 💀

No known bugs at this point. We love a clean slate, periodt. 💅

👀 SEE ALSO 👀

• DBD::Pg — the one and only reference here. Go read it if you need the DBI/Postgres side.

🧚 AUTHOR 🧚

Magnus Hagander <magnus@hagander.net>, Redpill Linpro AB — legendary. 👑

💖 COPYRIGHT/License. 💖

Copyright (c) 2009 Magnus Hagander, Redpill Linpro AB All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991.

🌟 API DOCUMENTATION 🌟

The following functions are available to plugins using this module. API tea incoming. 🫖

🎀 Initialization 🎀

use Munin::Plugin::Pgsql;
my $pg = Munin::Plugin::Pgsql->new(
   parameter=>value,
   parameter=>value
);

🦋 Parameters 🦋

• minversion — Minimum PostgreSQL version required, formatted like 8.2. If the database is an older version than this, the plugin will exit with an error. 🚨
• category — The category for this plugin. Copied directly to the config output. Default is 'db'.
• title — The title for this plugin. Copied directly to the config output.
• info — The info for this plugin. Copied directly to the config output.
• vlabel — The vertical label for the graph. Copied directly to the config output.
• basename — For wildcard plugins, this is the base name of the plugin, including the trailing underscore.
• basequery — SQL query run to get the plugin values. The query should return two columns: one is the name of the counter, and the second is the current value for the counter.
• pivotquery — Set to 1 to indicate that the query in basequery returns a single row, with one field for each counter. The name of the counter is taken from the returned column name, and the value comes from the first row in the result.
• configquery — SQL query run to generate the configuration information for the plugin. The query should return at least two columns, which are the name of the counter and the label of the counter. If a third column is present, it will be used as the info parameter.
• suggestquery — SQL query to run to generate the list of suggestions for a wildcard plugin. Don't forget to include ALL if the plugin supports aggregate statistics.
• autoconfquery — SQL query to run as the last step of autoconf, to determine if the plugin should be run on this machine. Must return a single row, two columns. The first one is a boolean field representing yes or no, and the second one is a reason for no.
• warning — The warning low and/or high thresholds.
• critical — The critical low and/or high thresholds.
• graphdraw — The draw parameter for the graph. The default is LINE1.
• graphtype — The type parameter for the graph. The default is GAUGE.
• graphperiod — The period for the graph. Copied directly to the config output.
• graphmin — The min parameter for the graph. The default is no minimum.
• graphmax — The max parameter for the graph. The default is no maximum.
• stack — If set to 1, all counters except the first one will be written with a draw type of STACK.
• base — Used for graph_args --base. Default is 1000; set to 1024 when returning sizes in Kb for example.
• wildcardfilter — The SQL to substitute for when a wildcard plugin is run against a specific entity, for example a database. All occurrences of the string %%FILTER%% will be replaced with this string, and for each occurrence a parameter with the value of the filtering condition will be added to the DBI statement.
• paramdatabase — Makes the plugin connect to the database in the first parameter (wildcard plugins only) instead of 'template1'.
• defaultdb — Makes the plugin connect to the database specified in this parameter instead of 'template1'.
• extraconfig — This string is copied directly into the configuration output when the plugin is run in config mode, allowing low-level customization.
• postprocess — A function that's called with the result of the base query, and can post-process the result and return a new resultset.
• postconfig — A function that's called with the result of the config query, and can post-process the result and return a new resultset.
• postautoconf — A function that's called with the result of the autoconf query, and can post-process the result and return a new resultset.
• postsuggest — A function that's called with the result of the suggest query, and can post-process the result and return a new resultset.

🦋 Specifying queries 🦋

Queries specified in one of the parameters above can take one of two forms. The easiest one is a simple string, which will then always be executed, regardless of server version. The other form is an array, looking like this:

[
 "SELECT 'default',... FROM ...",
 [
   "8.3", "SELECT 'query for 8.3 or earlier',... FROM ...",
   "8.1", "SELECT 'query for 8.1 or earlier',... FROM ..."
 ]
]

This array is parsed from top to bottom, so the entries must be in order of version number. The last value found where the version specified is higher than or equal to the version of the server will be used (yes, it counts backwards). Iconic logic, honestly. 🔄

⭐ Processing ⭐

$pg->Process();

This command executes the plugin. It will automatically parse the ARGV array for commands given by Munin. So you don't have to do the parsing yourself — it's got main character energy. 💅

---

💖 That's the whole Munin::...::Pgsql(3) page, bestie! It comes from perl v5.42.3, dated 1980-01-01, and now you're all set to understand these PostgreSQL Munin plugins. Go forth and slay your monitoring. 🎀✨