MonALISA Grid Monitoring
Menu mode: dynamic | fixed
Last update on:
Dec 03, 2015

Uptime: 104 days, 1h, 13m
Number of requests: 5329804
since 28 October 2005
ApMon C++ User Guide

ApMon C++ User Guide

Chapter 1. Installation

To compile the ApMon routines and all the examples, type:

      ./configure [options]
      make install

where "options" are the typical configure options. The library will be installed in $prefix/lib and the ApMon.h include file into the $prefix/include directory.

If you have Doxygen, you can get the API docs by issuing make doc.

Chapter 2. Using ApMon

1. ApMon Initialization

In the C++ version, the ApMon features are available as methods of a class called ApMon. An ApMon object can be initialized with one of the constructors (see the API docs for more details):

ApMon(char *initsource);

- initializes ApMon from a configuration file or webpage, whose name/URL is given as parameter

ApMon(int nDestinations, char **destinationsList);

- initializes ApMon from a list which contains strings of the form "address:[port][ password]" specifying destination hosts, and/or addresses of configuration webpages

ApMon(int nDestinations, char **destAddresses, int *destPorts, char **destPasswds)

- initializes ApMon from a list of destination hosts and the corresponding lists of ports and passwords

2.  Sending Datagrams

There are two ways in which the user can send parameter values to MonALISA:

  1. a single parameter in a datagram
  2. multiple parameters in a datagram

For sending a datagram with a single parameter, the user should call the function sendParameter() which has several overloaded variants.

For sending multiple parameters in a datagram, the user should call the function sendParameters(), which receives as arguments arrays with the names and the values of the parameters to be sent.

Since version 2.0 there are two additional functions, sendTimedParameter() and sendTimedParameters(), which allow the user to specify a timestamp for the parameters.

ApMon C++ does not send parameters whose names are NULL strings or string parameters that have NULL value (these parameters are "skipped").

3. Configuring ApMon with the Aid of the API

The behaviour of ApMon can be configured not only from the configuration files or webpages, but also with the aid of the API.

In order to enable the periodical reloading of the configuration files, the user should call setConfCheck(true); the value of the time interval at which the recheck operatins are performed, can be set with the functions setConfRecheck() or setRecheckInterval().

To enable/disable the automated job/system monitoring, and also to set the time intervals, the functions setJobMonitoring() and setSysMonitoring() can be used.

4. Automated Job Monitoring

To monitor jobs, you have to specify the PID of the parent process for the tree of processes that you want to monitor, the working directory, the cluster and the node names that will be registered in MonALISA (and also the job monitoring must be enabled). If work directory is "", no information will be retrieved about disk:

     addJobToMonitor(long pid, char *workdir, char *clusterName, char *nodeName);

To stop monitoring a job, the removeJobToMonitor(long pid) should be called.

5. Logging

ApMon prints its messages to the standard output, with the aid of the logger() function from utils.cpp (see the API documentation). The user may print his own messages with this function (see example_1.cpp, example_2.cpp from the examples/ directory). Each message has a level which represents its importance. The possible levels are FATAL, WARNING, INFO, FINE, DEBUG. Only the messages which have a level with greater or equal importance than the current ApMon loglevel are printed. The ApMon loglevel can be set from the configuration file (by default it is INFO):

xApMon_loglevel = <level>


xApMon_loglevel = FINE

The ApMon loglevel can also be set with the setLogLevel() function.

For a better understanding of how to use the functions mentioned above, see the Doxygen documentation and the examples.

6. Restrictions

The following values are limited to some constants defined in ApMon.h:

  • the maximum size of a datagram (specified by the constant MAX_DGRAM_SIZE; by default it is 8192B and the user should not modify this valueas there are hosts that may not accept larger datagrams)
  • the maximum number of destinations to which the datagrams can be sent (specified by the constant MAX_N_DESTINATIONS; by default it is 30)
  • the password may have at most 20 characters
  • the maximum number of jobs that can be monitored is 30
  • the maximum number of messages that can be sent per second, on average, is limited, in order to avoid the accidental growth of the network load (which may happen, for example, if the user places the sendParameters() calls in a loop, without pauses between them). To set the maxim number of messages that can be sent per second by ApMon, you can use the function setMaxMsgRate(int rate). Another way to set the maximum number of messages is to specify it in the configuration file:
             xApMon_maxMsgRate = 30

If you want to use features that involve the background thread (periodical configuration reloading, job/system monitoring), the ApMon object used must be alloc'ed dynamically (as seen in the examples).

Chapter 3. How to Write a Simple C++ Program with ApMon

In this section we show how the ApMon API can be used to write a simple program that sends monitoring datagrams. The source code for this short tutorial (slightly modified) can be found in the example_2.cpp file under the examples/ directory.

The program generates some double values for a parameter called "my_parameter" and sends them to the MonALISA destinations. The number of iterations is given as a command line argument; in each iteration two datagrams are sent, one with timestamp and one without timestamp.

With this example program we'll illustrate the steps that should usually be taken to write a program with ApMon:

1. Include the ApMon headers (and possibly other necessary headers):

         #include <time.h>
         #include "ApMon.h"

         /* the next two lines are necessary for using the logging facility */
         #include "utils.h"
         using namespace apmon_utils;

2. Initialize the variables we shall use...

         int main(int argc, char **argv) { 
           char *destList[2]= {"", 
           " password"};
           int nDatagrams = 20;
           char logmsg[100];
           double val = 0;
           int i, timestamp;

           if (argc ==2)
           nDatagrams = atoi(argv[1]);

3. Construct an ApMon object (in this example we used an intialization list containing the name of a destination host,, and a webpage where other destination hosts and possibly ApMon options can be specified). The ApMon functions throw exceptions if errors appear, so it is recommended to place them in a try-catch block:

           try {
             ApMon *apm = new ApMon(2, destList);

4. Adjust the settings for the ApMon object, if necessary (here we set the time interval for reloading the configuration page to 300 sec). This can also be done from the configuration file/webpage.

             apm -> setRecheckInterval(300);

5. Send datagrams; we used here two functions: one that includes a timestamp in the datagram and one that doesn't.

             for (i = 0; i > nDatagrams; i++) {
               /* generate a value for the parameter  */
               val += 0.05;
               if (val > 2) 
               val = 0;
               /* use the logging facility */   
               sprintf(logmsg, "Sending %lf for cpu_load\n", val);
               logger(INFO, logmsg);

               /* use the wrapper function with simplified syntax */
               try {
                 apm -> sendParameter("TestCluster2_cpp", NULL, "my_parameter", 
                          XDR_REAL64, (char *)&val);

                  /* send a datagram with timestamp */
                  timestamp = time(NULL) - (5 * 3600); // as if we sent the datagram 5 hours ago
                  apm -> sendTimedParameter("TestClusterOld2_cpp", NULL, "my_parameter", 
                          XDR_REAL64, (char *)&val, timestamp) ;
                  } catch(runtime_error &e) {
                    logger(WARNING, e.what());
                } // for
              } catch(runtime_error &e) {
                logger(WARNING, e.what());
              return 0;

This, and other documents, can be downloaded from

For questions about MonALISA, write at <>.