Table of Contents
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.
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 ( | |
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.sh Hello, world. paul@donachain:~$
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:
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.
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.
[monami] name=MonAMI -- your friendly monitoring daemon # Use either "308" or "44" below. #baseurl=http://monami.scotgrid.ac.uk/scientific/308/$basearch/ baseurl=http://monami.scotgrid.ac.uk/scientific/44/$basearch/ enabled=1
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
( | |
Completely blank lines are also allowed. They, too, are completely ignored, so you can include them anywhere within a configuration file. |
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... paul@donachain:~$
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!
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.