Repository files navigation

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

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

Python 3.3+

Supported platforms:

• Linux;
• FreeBSD;
• Windows;

Supported Zabbix server versions: 4.0.44 - 6.4.13

Supported PostgreSQL versions: 12 - 17

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

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 collectsmetrics 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 oftools 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 owncustom 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: Whilemamonsu 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 bymamonsu must be bound to the Zabbix host to receive and display metrics.

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.

Only Python3.3+ and any text editor.

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;

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

Sincemamonsu3.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.

  Click to view

  

• PostgreSQL Instance
  Contains information about Instance availability

  Click to view

  

• PostgreSQL Locks

  Click to view

  

• PostgreSQL Transactions

  Click to view

  

• PostgreSQL WAL
  Contains information about WAL size, archiving

  Click to view

  

• System
  Contains information about state of the system

  Click to view

  

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

  Click to view

  

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 ofmamonsu 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 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

To usemamonsu, you must create a Zabbix account and set up a Zabbix server as explained inZabbix documentation. Naturally, you must also have a PostgreSQL instance up and running if you are going to monitor PostgreSQL metrics.
Pre-builtmamonsu 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

1. Optionally, bootstrapmamonsu
   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 formamonsu. For example:

   CREATEUSERmamonsu_user WITH PASSWORD'mamonsu_password';

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

   CREATEDATABASEmamonsu_database OWNER mamonsu_user;

   • Run the following command to bootstrapmamonsu:

   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 themamonsu_database inmamonsu schema, and the right to execute them is granted to themamonsu_user. Thus, a superuser connection is no longer required.mamonsu also creates several tables in the specified database. Do not delete these tables as they are required formamonsu to work.
2. Configuremamonsu
   Edit theagent.conf configuration file.
   Configure Zabbix-related settings. The address field must point to the running Zabbix server, while the client field must provide the name of the Zabbix host. You can find the list of hosts available for your account in the Zabbix web interface under Configuration > Hosts.

   [zabbix]; enabled by defaultenabled =Trueclient =zabbix_host_nameaddress =zabbix_server

   By default,mamonsu will collect both PostgreSQL and system metrics. If required, you can disable metrics collection of either type by setting the enabled parameter to False in the [postgres] or [system] section of theagent.conf file, respectively.

   [system]; enabled by defaultenabled =True

   If you are going to collect PostgreSQL metrics, specify connection parameters for the PostgreSQL server you are going to monitor. In the user, password and database fields, you must specify themamonsu_user,mamonsu_password and themamonsu_database used forbootstrap, respectively. If you skipped thebootstrap, specify a superuser credentials and the database to connect to.

   NOTE:mamonsu stores passwords as plain text in its configuration file, so control access to this file. By default configuration fileagent.conf should have read/write permissions formamonsu user only.

   [postgres]; enabled by defaultenabled =Trueuser =mamonsu_userdatabase =mamonsu_databasepassword =mamonsu_passwordport =5432

   These are the mainmamonsu settings to get started. You can also fine-tune othermamonsu settings as explained in the chapter called "Configuration file".

1. Generate a template that defines how to visualize collected metrics on the Zabbix server:

   mamonsuexport template template.xml

   mamonsu generates thetemplate.xml file in your current directory. By default, the name of the template that will be displayed in the Zabbix account ismamonsu PostgreSQL OS, whereOS is the name of your operating system. To get a template with a different display name, you can run the above command with the--template-name option.

2. Optionally, specify your Zabbix account settings in the following environment variables on your monitoring system:

   • Set the ZABBIX_USER and ZABBIX_PASSWD variables to the login and password of your Zabbix account, respectively.
   • Set the ZABBIX_URL tohttp://zabbix/

   If you skip this step, you will have to add the following options to allmamonsu zabbix commands that you run:

   --url=http://zabbix/ --user=zabbix_login --password=zabbix_password

3. Upload the template.xml to the Zabbix server

   mamonsu zabbix templateexport template.xml

   Alternatively, you can upload the template through the Zabbix web interface: log in to your Zabbix account and select Templates > Import.

4. Link the generated template to the host to be monitored
   In the Zabbix web interface, select your host, go to Templates > Add, select your template, and click Update. If you would like to link a template with a new Zabbix host, you can do it from the command line usingmamonsu zabbix commands. See the section called "Zabbix cli" for details.

On UNIX-like systems:

$ service mamonsu start

or by hand:

$ mamonsu -d -a /etc/mamonsu/plugins -c /etc/mamonsu/agent.conf -p /var/run/mamonsu.pid

In order to correctly update the template after minor update and save all the data, it is necessary to generate the same template and application names. You can find your current template name in the Zabbix web interface under Configuration > Templates and application name in Configuration > Templates > Applications.
After getting current template and application names, you should generate template like this:

mamonsuexport template template.xml --template-name="CURRENT_TEMPLATE_NAME" --application="CURRENT_APPLICATION_NAME"

Next, upload new template to the Zabbix server. You can do it via command line interface:

mamonsu zabbix templateexport template.xml

Or through the Zabbix web interface:

NOTE: While uploading through the Zabbix web interface, you must setDelete missing parameter to true for Value mappings, Template dashboards, Items, Discovery rules, Triggers and Graphs.

Zabbix host setup only withmamonsu zabbix cli

1. Generate a template

   mamonsuexport template template.xml

2. Set Zabbix variables

   export ZABBIX_USER=Adminexport ZABBIX_PASSWD=zabbixexport ZABBIX_URL=http://zabbix/

3. Upload template

   mamonsu zabbix templateexport template.xml

4. Create host and link template

   mamonsu zabbix host create"pg-host"$(mamonsu zabbix hostgroup id"Linux Servers")$(mamonsu zabbix template id"mamonsu PostgreSQL Linux")"10.10.0.4"

   This snippet shows how to create Zabbix host calledpg-host with mamonsu template in hostgroupLinux Servers with address10.10.0.4.

mamonsu setup with remote PostgreSQL

1. Generate and upload template

   mamonsuexport template template.xml; mamonsu zabbix templateexport template.xml

2. Add remote PostgreSQL host

    mamonsu zabbix host create"remote-pg-1"$(mamonsu zabbix hostgroup id"Linux servers")$(mamonsu zabbix template id"mamonsu PostgreSQL Linux")"45.45.200.5"

3. Setup agent.conf

    [postgres]enabled =Trueuser =mamonsupassword =mamonsudatabase =postgreshost =45.45.200.5port =5432application_name =mamonsuquery_timeout =10  [zabbix]enabled =Trueclient =remote-pg-1address =127.0.0.1port =10051re_send =False

mamonsu setup with remote PostgreSQL via SSH tunnel

1. Generate and upload template

   mamonsuexport template template.xml; mamonsu zabbix templateexport template.xml

2. Add remote PostgreSQL host

    mamonsu zabbix host create"remote-pg-1"$(mamonsu zabbix hostgroup id"Linux servers")$(mamonsu zabbix template id"mamonsu PostgreSQL Linux")"45.45.200.5"

3. Setup SSH tunnel

   ssh -L 63333:localhost:5432 user@45.45.200.5

4. Setupagent.conf

    [postgres]enabled =Trueuser =mamonsupassword =mamonsudatabase =postgreshost =localhostport =63333application_name =mamonsuquery_timeout =10  [zabbix]enabled =Trueclient =remote-pg-1address =127.0.0.1port =10051re_send =False

Major update
If you want to upgrademamonsu to a version that is not compatible with the previous one, what you must do to continue using the application depends on whether you need to retain the metrics data collected.
If you do not need to retain the collected data, just unlink old template and link a new one.

If you need to retain the collected data, do the following:

1. Install the new version ofmamonsu.
2. Generate a new template for the Zabbix server.
3. If you performed a bootstrap using the previous version ofmamonsu, run the bootstrap command again.
4. Upload the new template to the Zabbix server.
5. Rename the host for which you want to retain the collected data and leave the old template linked to that host.
6. Create a new host for the same system and link the new template to it.
7. Restartmamonsu. It will collect data for the new host. The old host will no longer be used, but the data collected will be available.

The difficulty is that Zabbix cannot massively rename hosts.
We offer the following recommendations:

1. If you have access to the Zabbix database:
   Mass rename hosts via SQL:

   zabbix=# SELECT host, name FROM hostszabbix-# WHERE host LIKE'%local-pg%';-[ RECORD 1 ]----host| local-pg-2name| local-pg-2-[ RECORD 2 ]----host| local-pg-3name| local-pg-3zabbix=# UPDATE hostszabbix=# SET host = host || ' OLD-mamonsu',zabbix=#     name = name || ' OLD-mamonsu'zabbix=# WHERE host LIKE '%local-pg%';UPDATE 2zabbix=# SELECT host, name FROM hostszabbix=# WHERE host LIKE '%local-pg%';-[ RECORD 1 ]----------------host| local-pg-2 OLD-mamonsuname| local-pg-2 OLD-mamonsu-[ RECORD 2 ]----------------host| local-pg-3 OLD-mamonsuname| local-pg-3 OLD-mamonsu

2. Using Zabbix API:
   API query:

   curl -H"Content-type: application/json-rpc" -X POST http://zabbix/api_jsonrpc.php -d'{    "jsonrpc": "2.0",    "method": "host.update",    "params": {        "hostid": "HOST_ID",        "host": "local-pg-3 OLD-mamonsu",        "name": "local-pg-3 OLD-mamonsu"    },    "auth": "AUTH_TOKEN",    "id": 1}'

   Script

   #!/bin/bash ZABBIX_URL="http://zabbix/"ZABBIX_USER="Admin"ZABBIX_PASSWORD="zabbix"ZABBIX_PATTERN=""ZABBIX_SUFFIX="OLD"forparameterin"$@"docase$parameterin    -u=*|--url=*)# zabbix url    ZABBIX_URL="${parameter#*=}"shift    ;;    -U=*|--user=*)# zabbix user    ZABBIX_USER="${parameter#*=}"shift    ;;    -P=*|--password=*)# zabbix password    ZABBIX_PASSWORD="${parameter#*=}"shift    ;;    -p=*|--pattern=*)# zabbix host pattern    ZABBIX_PATTERN="${parameter#*=}"shift    ;;    -s=*|--suffix=*)# zabbix host suffix    ZABBIX_SUFFIX="${parameter#*=}"shift    ;;*)# unknown option    ;;esacdone# get Zabbix auth tokenauth_token=$(curl -H"Content-type: application/json-rpc" -X POST${ZABBIX_URL}api_jsonrpc.php -d'{    "jsonrpc": "2.0",    "method": "user.login",    "params": {    "user": "'${ZABBIX_USER}'",    "password": "'${ZABBIX_PASSWORD}'"    },    "id": 1}'| python3 -c"import sys, json; print(json.load(sys.stdin)['result'])")# get array of Zabbix hosts to renamereadarray -t hosts<<(mamonsu zabbix --url=${ZABBIX_URL} --user=${ZABBIX_USER} --password=${ZABBIX_PASSWORD} host list| awk'{ print "\""$0"\""}'| grep${ZABBIX_PATTERN})hosts=("${hosts[@]//\"/}") hosts_dict={}# create dict from array (id:name)forhostin"${hosts[@]}"do    hosts_dict[$(mamonsu zabbix --url=${ZABBIX_URL} --user=${ZABBIX_USER} --password=${ZABBIX_PASSWORD} host id"${host}")]=$hostdoneforkeyin"${!hosts_dict[@]}";doif [${key}-ne 0 ];theneval'curl -H "Content-type: application/json-rpc" -X POST ${ZABBIX_URL}api_jsonrpc.php -d'\''{    "jsonrpc": "2.0",    "method": "host.update",    "params": {        "hostid": "'${key}'",        "host": "'${hosts_dict[$key]}''${ZABBIX_SUFFIX}'",        "name": "'${hosts_dict[$key]}''${ZABBIX_SUFFIX}'"    },    "auth": "'${auth_token}'",    "id": 1}'\'''fidone

   Script usage example:

   ./rename_zabbix_hosts.sh --url=http://localzabbix/ --pattern="local-pg" --suffix="OLD-mamonsu"

• Adding custom plugins
• Configuration file
• Metrics
• Tools