MonAMI by example

Table of Contents

1. Introduction
2. Simple periodic monitoring
3. Selecting and merging available data
4. Caching and named samples
5. On-demand monitoring
6. Plotting data with Ganglia
7. Using Nagios to trigger alerts
8. Writing data into MySQL

1. Introduction

This tutorial aims to teach you how to configure MonAMI. It is split into different sections, each exploring a specific example configuration file. The example files start off simple, but they get more complex as you proceed. If you find you are having difficulty, try rereading the previous section: you might have missed something there.

The subject of this tutorial is MonAMI: a data-collection framework that can provide monitoring information for different monitoring systems. MonAMI consists of a daemon and a set of plugins. The plugins provide the useful functionality, such as collecting monitoring information about resources or sending that information to monitoring systems. This will help you monitor your computer resources, allowing you to provide a reliable service.

MonAMI works in collaboration with existing monitoring systems. It collects data describing your services and sends it to a monitoring system, or multiple systems. MonAMI itself does not draw pretty graphs, provide trend analysis, or alert you if a service is looking suspicious. This is deliberate: there are many monitoring packages that provide these features already. Instead, it concentrates on getting information out of whatever services you are running.

Since MonAMI is designed not to favour a particular monitoring system, this tutorial will begin by concentrating on the basics without requiring any particular monitoring system. Later on, the sections will concentrate on using MonAMI in more specific situations. These section may use specific applications or monitoring systems. Wherever possible, alternatives are given.

Typographical conventions

This tutorial uses symbols and different typeface to label the different material. Sections that contain contents of a file use a slightly smaller mono-spaced font and are contained within a box.

With most file contents included, there are some small circled numbers. When copying the text files, don't copy them! They are not part of the file's contents, but are to draw your attention to specific points of interest. These points are explained immediately below the text.

The following is an example shell script. The text also includes some circled numbers:

#!/bin/sh ❶
#❷  A simple example script 

echo❸ "Hello, world."

the shell to run; in this case, the Borne shell.

comment lines start with a hash symbol (#) and are ignored.

the echo command produces some output.

Other sections display typical output from running a program. They are also displayed in a mono-spaced font within a box. For example, here is the result of running the above script:

paul@donachain:~$ ./
Hello, world.

Extra notes...

Throughout the tutorial there are several notes. These are separate short sections, marked with this quill pen icon. These notes contain additional information that give a greater breadth of understanding, but are extra: you can skip them if you want to.


For this tutorial, you need:

  • A computer with MonAMI installed. MonAMI itself does not need root access for any monitoring activities: it can run quite happily as a normal user. Perhaps the easiest way of getting started is to install one of the binary packages, available from the MonAMI webpage.

  • The ability to edit the MonAMI configuration files. The packaged version of MonAMI uses files in the /etc directory and have permission settings that require root privileges to edit. If you are running a version of MonAMI you have compiled for yourself then the location of the configuration files may differ and you may be able to edit these files without root privileges.

  • about 15 minutes of spare time per section. This is an estimate of how long going through an example will take. If you have more time, you are encouraged to try altering the example configuration and seeing what happens.

  • Various sections have specific requirements:

    Section 5

    KSysGuard or telnet. KSysGuard is a standard part of the KDE desktop and is available for GNU/Linux and Macintosh computers. There are instructions for using telnet instead of KSysGuard, allowing people who don't have KSysGuard to appreciate on-demand monitoring.

    Section 6
    Ganglia. This section is based on using MonAMI with Ganglia.
    Section 7
    Nagios. This section shows how to configure MonAMI to generate alerts within Nagios.
    Section 8
    MySQL. This section shows how to store data within a MySQL database. You will need an account (username and password) that has CREATE and INSERT privileges for some existing database within MySQL.

Installing MonAMI

As it says above, this tutorial assumes you have installed MonAMI on some computer, so the tutorial does not provide detailed information on how to install MonAMI. However, for the sake of completeness, some comments are included.

You can download MonAMI from the SourceForge download area. There are links to there from the MonAMI home page. You should find the latest version available as binary and source RPMS, along with a compressed tar file containing the source.

The binary RPMs are split into a core RPM, several plugin RPMs and a documentation RPM. The core RPM provides basic infrastructure and a collection of plugins with no external dependencies. The various plugin RPMs provide additional functionality, but also include some dependencies on other libraries. The documentation RPM contains PDF and HTML versions of the User Guide.

There is also a yum and apt repository for these RPMs. These are hosted at ScotGrid. To use the yum repository, copy the following text as /etc/yum.repos.d/monami.repo.

name=MonAMI -- your friendly monitoring daemon
#  Use either "308" or "44" below.

Configuration files

With the prepackaged version of MonAMI, configuration is held in the /etc/monami.d directory. In the following examples, you should create a file /etc/monami.d/example.conf. Each example is self-contained, so you should overwrite this file for each example.

Each section is based around a theme and each theme is usually based around a specific example configuration file. This section is no exception. However, this section's configuration file is rather boring as it will have no effect: MonAMI will run identically either with or without this file. It will run until told to stop.

If you do create the example configuration file, save the content as /etc/monami.d/example.conf, but make sure you don't copy the circled numbers: they indicate points of interest.

 ##  MonAMI by Example, Section 1
 ##  This file does nothing.

Here are some points of interest:

Comments can be added by starting a line with a hash symbol (#). These comment lines are ignored. If a line starts with any other character, then it is not a comment line and will be processed.

Completely blank lines are also allowed. They, too, are completely ignored, so you can include them anywhere within a configuration file.

Starting and stopping MonAMI

MonAMI will normally detach itself from the shell and redirect its output somewhere (to syslog by default). This is desirable behaviour for a daemon; but, for the purposes of these tutorial exercises it is better if MonAMI runs both without detaching from the shell and providing more verbose messages.

To achieve this, run the MonAMI executable directly use the command /usr/bin/monamid -fv. You can stop MonAMI by typing Ctrl+C.

When starting MonAMI, you will see output like:

paul@donachain:~$ /usr/bin/monamid -fv
 Loading configuration file /etc/monami.conf
         plugin apache loaded
         plugin amga loaded
There will be many similar lines.
         plugin tcp loaded
         plugin tomcat loaded
 Starting up...

When MonAMI is shutting down, you will see the following:

 Waiting for activity to stop...
 Shutting down threads...

Usually, when told to shutdown, MonAMI isn't doing anything. If so, then MonAMI will quickly exit. If MonAMI is collecting data when told to shutdown, you may see a slight delay between the “waiting for activity to stop...” and “shutting down threads...” messages. This delay is expected, and will last only for as long as MonAMI needs to finish the current activity. If the data source is slow, it may take a few seconds.

If shutting down takes longer than a minute, MonAMI will assume something has gone wrong and a bug within MonAMI or one of the plugins has been found. If this happens, it will record some debugging information and try harder to stop. Naturally, you should never see this happen!

Getting more information

The information here aims to be self-complete. However, you may be left wondering about some specific aspect and want to know more. You can get more information from:

  • The packaged versions of MonAMI include manual pages for how to run monamid and the MonAMI configuration file format: monamid(8) and monami.conf(5).

  • The MonAMI User Guide contains a wealth of information about MonAMI, including documentation on all the plugins and how to configure MonAMI. It is available in PDF and HTML formats, both as an RPM package and from the MonAMI home page.

  • If you have a question that isn't answered by any of these references, feel free to join the MonAMI users mailing list and ask it there.