mamonsu: monitoring agent for PostgreSQL

mamonsu is an active agent for collecting PostgreSQL instance and operating system metrics that can interact with Zabbix.

---

Build status

<img alt="" src="documentation/images/mamonsu_header.png" align="right" />

---

License

Development version, available on GitHub, released under BSD 3-clause.

---

Compatibility

Python 3.3+

Supported platforms:

• Linux;
• FreeBSD;
• Windows;

Supported Zabbix server versions: 4.0.44 - 6.4.13

Supported PostgreSQL versions: 12 - 18

---

Table of Contents

• mamonsu: concepts
• Requirements
• Features
  • Metrics
  • Zabbix Screens
  • Tools
• Build
• Installation
• Usage
  • Configuration
  • Template creation and upload
  • Run
  • Template update
  • Best practices
• Additional chapters

mamonsu: concepts

Based by Zabbix, mamonsu provides an extensible cross-platform solution that can collect and visualize multiple PostgreSQL/PostgresPro and system metrics. mamonsu has about 90 PostgreSQL metrics and about 40 system metrics. The agent collects metrics such as database availability, number of connections, locks, WAL problems, checkpoints, background writer activity, memory problems and many others. Unlike many monitoring agents configured to collect PostgreSQL metrics, mamonsu uses a single database connection, which minimizes performance impact on the monitored system. mamonsu also contains a number of tools for interacting with the Zabbix API, obtaining system information and information about collected metrics.
mamonsu is written entirely in Python 3 and has a plugin architecture. It is an active agent, which means that it sends the data to the Zabbix server once it is collected. Pre-configured to monitor multiple PostgreSQL and system metrics out of the box, mamonsu can be extended with your own custom plugins to track other metrics crucial for your system.
mamonsu can be installed on the same server where the DBMS we are going to monitor is located or on remote server, but:

NOTE: While mamonsu can collect PostgreSQL metrics from a remote server, system metrics are only collected locally. If you choose to collect PostgreSQL metrics remotely, make sure to disable collection of system metrics to avoid confusion, as they will be displayed under the same host in Zabbix.

A template generated by mamonsu must be bound to the Zabbix host to receive and display metrics.

<p align="center"> <img width="640" alt="mamonsu default scheme" src="documentation/images/mamonsu_default_scheme.png" /> </p>

mamonsu can be easily customized. You can configure such parameters as the data collection interval for each plugin (by default it is 60 seconds), the size of the message queue for the Zabbix server, optionally disable/enable various components.

Requirements

Only Python3.3+ and any text editor.

Features

Metrics

mamonsu by default has 3 plugin groups and all of them are active:

• common: mamonsu own metrics such as availability, plugin errors;
• system: contains *nix and windows metric sets. For example, on UNIX-based platforms you can collect specific metrics such as load average, open files count, CPU nice/idle/system time, etc.;
• pgsql: PostgreSQL/PostgresPro specific metrics;

<p align="center"> <img width="640" alt="mamonsu PG metrics" src="documentation/images/mamonsu_PG_plugins.png" /> </p>

mamonsu not only collects metrics, but provides triggers and graphs.
See details in chapter called "Metrics".

Zabbix Screens

Since mamonsu 3.0 template contains screens:

• Overview
  Contains graphs representing general important metrics: PostgreSQL connections, shared buffers size and usage, autovacuum, tuples, checkpoint, background worker, system CPU and memory.

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_overview.png" alt="mamonsu Overview"/> </details>

• PostgreSQL Instance
  Contains information about Instance availability

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_pg_instance.png" alt="mamonsu PostgreSQL Instance"/> </details>

• PostgreSQL Locks

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_pg_locks.png" alt="mamonsu PostgreSQL Locks"/> </details>

• PostgreSQL Transactions

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_pg_transactions.png" alt="mamonsu PostgreSQL Transactions"/> </details>

• PostgreSQL WAL
  Contains information about WAL size, archiving

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_pg_wal.png" alt="mamonsu PostgreSQL WAL"/> </details>

• System
  Contains information about state of the system

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_system.png" alt="mamonsu System"/> </details>

• mamonsu Dashboard (only for Zabbix 6.0+)
  Pretty dashboard containing all necessary PostgreSQL and system information.

  <details> <summary>Click to view</summary> <img src="documentation/images/mamonsu_dashboard.png" alt="mamonsu Dashboard"/> </details>

Tools

mamonsu provides the command-line interface for updating some Zabbix server settings, as well as getting an overview of the monitored system configuration and tuning PostgreSQL and system settings on the fly. Also it provides tool to generate a detailed report on the hardware, operating system, memory usage and other parameters of the monitored system. List of mamonsu commands and options:

mamonsu agent [agent_action] [-c | --config]  
mamonsu bootstrap [-M mamonsu_user] [-x | --create-extensions] [-c | --config] [connection_options]  
mamonsu export {template | config} filename [export_options]  
mamonsu report [report_options] [connection_options]  
mamonsu tune [tuning_options] [connection_options]  
mamonsu upload [upload_options]  
mamonsu zabbix {template | host | hostgroup} server_action  
mamonsu zabbix item {error | lastvalue | lastclock} host_id  
mamonsu zabbix dashboard upload [template_name]  
mamonsu zabbix version  
mamonsu --version  
mamonsu --help

For all details, see the chapter called “Tools".

Build

Build deb:

$ apt-get install make dpkg-dev debhelper python3-dev python3-setuptools
$ git clone ... && cd mamonsu && make deb && dpkg -i mamonsu*.deb

Build rpm:

$ yum install make rpm-build python3-devel python3-setuptools
$ git clone ... && cd mamonsu && make rpm && rpm -i mamonsu*.rpm

Build win32 exe:

$ git clone ... && cd mamonsu && py setup_win32.py py2exe
$ copy dist\mamonsu.exe c:\mamonsu
$ copy dist\service_win32.exe c:\mamonsu
$ c:\mamonsu\mamonsu.exe -w c:\mamonsu\agent.conf
$ c:\mamonsu\service_win32.exe -install
$ net start mamonsu

or

$ pyinstaller --onefile mamonsu_win32.spec
$ pyinstaller --onefile service_win32.spec

Build NSIS installer:

$ git clone ... && cd mamonsu && py setup_win32.py py2exe
$ makensis packaging\win\mamonsu.nsis

Installation

To use mamonsu, you must create a Zabbix account and set up a Zabbix server as explained in Zabbix documentation. Naturally, you must also have a PostgreSQL instance up and running if you are going to monitor PostgreSQL metrics.
Pre-built mamonsu packages are provided in official Postgres Pro repository: repo/mamonsu

Install from repository using script:

$ wget https://repo.postgrespro.ru/mamonsu/mamonsu/keys/pgpro-repo-add.sh
$ sudo chmod 700 ./pgpro-repo-add.sh
$ sudo ./pgpro-repo-add.sh

Install package

• for RH-like:

  $ yum install mamonsu
  

• for SLES:

  $ zypper install mamonsu
  

• for Debian, Ubuntu, AltLinux, AltlLinux-spt:

  $ apt-get update
  $ apt-get install mamonsu
  

For Windows:
Pre-Build packages for Windows: Windows installer

Build and install from source code:

git clone ... && cd mamonsu && python3 setup.py build && python3 setup.py install

Usage

Configuration

1. Optionally, bootstrap mamonsu
   If you omit this step, metrics can only be collected on behalf of a superuser, which is not recommended.
   • Create a non-privileged database user for mamonsu. For example:

   CREATE USER mamonsu_user WITH PASSWORD 'mamonsu_password';
   

   • Create a database that will be used for connection to PostgreSQL. For example:

   CREATE DATABASE mamonsu_database OWNER mamonsu_user;
   

   • Run the following command to bootstrap mamonsu:

   mamonsu bootstrap [-M mamonsu_user] [-x | --create-extensions] [-c | --config] [connection_options]
   

   For details of usage, see “Tools".
   As the result of this operation, monitoring functions are created in the mamonsu_database in mamonsu schema, and the right to execute them is granted to the mamonsu_user. Thus, a superuser connection is no longer required. mamonsu also creates several tables in the specified database. Do not delete these tables