The monet monitoring tool

monet is a flexible monitoring tool, suitable for network monitoring, host performance tracking, and for the instrumentation of complex systems, among others.

Original version of this documentation at LFCIA lab, University of A Coruña, Spain

Mirror at SourceForge

monet is written in Erlang. Erlang is a functional language developed at Ericsson, with nice fault-tolerancy features, inherent distribution, and soft realtime capabilities. It also makes heavy use of OTP, the Open Telecom Platform: a set of applications and libraries that provide support for SNMP, HTTP, ASN.1 and lots of other useful protocols and functionality. See the open-source erlang site or your closest mirror for more information.

At its current stage, monet is certainly not for the faint of heart. It works, but an alpha version is an alpha... Standard disclaimer about you being the only responsible if your cat dies and your network switches blow up because of using this software applies.

Because of legal issues, it has been almost completely reimplemented. Right now it's quite more primitive than the original monet, but I hope it will evolve quickly.

monet is released to the public under the terms of the General Public License (GPL), version 2 or later.

How does it work? (an overview)

On startup, monet starts the Mnesia database, the EVA alarm handler, the MESH measurement and event handler, and the System Architecture Support Libraries (SASL), all part of OTP. Then it starts the Measurement Responsible Processes (MRPs) specified in the config files, and sends messages to each MRP to create the configured Measurement Objects (MOs).

Measurement Objects are responsible for reading values from external resources (ie, performing measures) and then reporting them to MESH. They can also throw alarms at EVA upon errors from the resources they monitor.

An adaptation can be installed on EVA in order to receive and process the system alarms. By default, monet installs the main_handler adaptation, which calls user-defined alarm handlers. The syslog_adapt adaptation, which logs all events and alarms to the unix syslog can also be started.

Measurement reports and alarm deassertions, among others, generate events. EVA receives and logs them. Measurement values are logged separately.

Installation

First, download monet-0.1.tgz, gunzip and untar it. You will get a monet-0.1 directory with erlang files inside, a README file and a Makefile. Of course, read the README file first (don't you always?) and type make. At this point, you will either:

get a bunch of .beam files. Now, launch an erlang node and run monet:start() in it, either manually or from the unix shell (say, erl -sname monet0 -s monet). Monet should spew several screenfuls of very verbose output and start up.
erlc: command not found. You DO have the erlang runtime installed, don't you?
get strange errors. I want to hear about it, please email me

Now, configure it according to the following sections.

Basic configuration

Before proceeding, please note the erlang notation: terms between curly braces {} denote tuples, ie., like a record on a database. Terms between brackets [] denote a list. A list can have arbitrary length.

In erlang, strings are represented between double quotation marks, "So, this is a sample string". Atoms are identifiers, and they can be denoted with arbitrary strings as long as they use only a restricted set of characters (letters, numbers, underline). They can't begin with an uppercase letter, so thisIsAValidAtom but ThisIsNotAValidAtom. In case one needs to use an atom whose textual representation would be invalid (atoms including spaces, for instance) they can be enclosed between simple quotation marks, so 'this is a valid atom with spaces'.

Basic configuration is spread across three files:

monitors.config defines the Measurement Types (MTs) and Measurement Objects (MOs) through a list of tuples with the following syntax:
```
{meastype, TypeName, "Description of this measurement type",
     ModuleName, MaxInstances}.
{measobject, ObjectName, TypeName, "Description of this Measurement
     Object", Resource, started, [argslist]}.
{threshold, [ {ObjectName, ThresholdType, Value} ...]}.
  ... 
```
In the description above, meastype and measobject identify whether the tuple defines a measurement type or a measurement object.
TypeName in a type definition and ObjectName in a MO definition name the type or object being defined. TypeName in a MO definition is the type this object belongs to.

The ModuleName is the erlang module where the type is implemented, and MaxInstances is the maximum number of MOs allowed for this type. For the MOs, Resource is the resource it should monitor or get measurements from; it's up to each MO to interpret its meaning. Similarly, [argslist] is a list of arguments that will be passed to this MO. Finally, started is the state into which the MO will be created; for now, only this value is valid.

As well as measurement types and individual measurements of each type, maximum and minimum value thresholds for each measurement can also be defined in monitors.config, with tuples {threshold, [ List_of_Thresholds ]}, where the List_of_Thresholds is made of tuples {MeasurementObject, ThresholdType, Value}. MeasurementObject is the object to keep track of, and ThresholdType can be either the atom 'upper' or 'lower'. If any of these thresholds are ever exceeded an alarm will be generated (more on alarms and events later).
handlers.config defines alarm handlers (to be managed by main_handler, see above). The syntax is as follows:
```
  { exttesthandler, "/path/to/handler.sh" }.
  { testhandler, { module, function } }.
  ...
```
Each tuple is formed by a handler name and a handler definition. The definition can be either a string with a unix path - any executable - or a pair {Module,Function} - ie, an erlang function. Both will be called with the name, sender, severity and class of the alarm.
The exact calling convention is:
- External executables are called as exthandler -n alarmname -s sender -g severity -c alarmclass when an alarm is raised, or exthandler -n alarmname -s sender -g severity -c alarmclass -u when an alarm is cleared.
- Erlang functions are called as module:function(Sense,AlarmRecord,Class), where:
  - Sense defines the alarm edge, either up (alarm being raised) or down (alarm being cleared)
  - AlarmRecord is an erlang record defined as -record(alarm, {index, fault_id, name, sender, cause, severity, time, extra}). It is defined in eva.hrl; add the corresponding -include_lib("eva/include/eva.hrl"). line to the handler code to be able to correctly use it.
  - Class is the alarm class.
destinations.config defines where each event and alarm should be sent to, ie., which handler should receive them. It follows the structure:
```
{ Condition, Handler }.
...
```
Condition selects an erlang function which should return a boolean value when applied to an alarm, and if it returns true then the corresponding handler will be called. The general form of Condition is:
```
{Node,Module,Function,ArgumentList}
```
For instance, {'agent@node14',scmodule,testfun,[]}.
The Node can be left out if it's the local node. There are alternative, simpler valid syntaxes:
```
{Module,Function}.
{Function,ArgumentsList}.
```
In the first case, arguments are assumed to be an empty list (ie., no arguments). In the second, the module is taken by default (several common functions are provided in the stddeps module). Even, for these common functions, the syntax:
```
{Function}.
```
is valid.

Some of the common functions provided in the stddeps module are:
- never(Anything) - it is always false
- always(Anything) - it is always true
- raised(AlarmName) - true if the given alarm name is currently active
- raise(AlarmName) - true if the given alarm name is being raised
- lower(AlarmName) - true if the given alarm name is being cleared (lowered)
- name(AlarmName) - true if the given alarm name is being toggled (either rising or clearing)
- sender(Sender) - true if the originator of the alarm being processed is Sender
- severity(Severity) - true if the alarm being processed is of severity Severity
- class(Class) - true if the alarm being processed is of class Class
- neg(Condition) - true if Condition is false
- any(ListOfConditions) - logical OR of the ListOfConditions, ie., true if any of them is true.
- all(ListOfConditions) - logical AND of the ListOfConditions, ie., true if all of them are true.
Note that any() is not strictly a boolean OR because it may crash if a condition expression evaluation crashes. Note that all handlers that match will be called.

Valid classes are: communications,qos,processing,equipment, and environmental.
Valid severities are: indeterminate,critical,major,minor,warning.
As a sample, consider the following destinations.config:
```
{ always, exttesthandler}.
{ {class, [processing]}, testhandler}.
{any, [ {always},{never,[]}], handlerA}.
{all, [ {always,[]},{never}], handlerB}.
```
In this example:
- exttesthandler will be called whenever an alarm is raised or cleared.
- testhandler will be called when the alarm class is processing
- handlerA will be called always (because somehow either always() or never() are true :-))
- handlerB will never be called
Defining Measurement Objects
In order to define a new MO you must register a measurement type, create a Measurement Responsible Process (MRP) and then spawn the MO. However, as a lot of code is more or less common across many measurement types - and to make life easier - two generic measurement types are provided: the generic erlang type and the generic external type.
The generic erlang measurement type (generlmon) implements all the code needed for most simple measurements. You just have to provide him with a function of arity 2 that will be called as module:function(ResourceId, [ParamList]). In order to configure a monitor with generlmon, just add it to the monitors definition file; it should receive the following list of arguments:
```
[module,ModuleName,function,FunctionName,period,TimeInSecs,monargs,[ListOfArgs]]
    
```
The ModuleName and FunctionName values point at your module:function() developed in erlang. The TimeInSecs period is the time between sucessive invocations of the function, and the ListOfArgs is the list of arguments that will be passed to your erlang monitor. See the examples in the sample config files.

The generic external measurement type (extmon) acts as a bridge between monet and external monitoring scripts such as those used by mon. In fact, it can use mon scripts without change. These monitoring scripts will be called as
```
monitor args resource-id
```
They should return nothing on stdout if everything is ok, or the resource-id in case of error (for compatibility with mon)

Miguel Barreiro
Last modified: Thu May 10 14:38:58 CEST 2001
This page served from

The monet monitoring tool

How does it work? (an overview)

Installation

Basic configuration

Defining Measurement Objects