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

Uptime: 104 days, 1h, 38m
Number of requests: 5329816
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 functions that operate on a structure called ApMon. An ApMon structure can be initialized with one of the functions (see the API docs for more details):

ApMon* apMon_init(char *filename);

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

ApMon *apMon_stringInit(char *destinationsList);

- initializes ApMon from a list which contains destination hosts, specified as "address:[port][ password]", and/or configuration webpages; the items of list are placed in a string, separated by commas

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

- initializes ApMon from a list of destination hosts and the correspondong 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 apMon_sendParameter() which has several overloaded variants.

For sending multiple parameters in a datagram, the user should call the function apMon_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, apMon_sendTimedParameter() and apMon_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 apMon_setConfRecheck_d(); the value of the time interval at which the recheck operatins are performed, can be set with the functions apMon_setConfRecheck() or apMon_setRecheckInterval().

To enable/disable the automated job/system monitoring, and also to set the time intervals, the functions apMon_setJobMonitoring() and apMon_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:

       apMon_addJobToMonitor(ApMon *apm, 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.c (see the API documentation). The user may print its own messages with this function (see example_1.cpp, example_2.cpp ). Each message has a level which represent 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 apMon_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 number of destinations to which the datagrams can be sent (specified by the constant MAX_N_DESTINATIONS; by default it is 30)
  • 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 value as some hosts may not accept larger datagrams)
  • 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 apMon_setMaxMsgRate(ApMon *apm, int rate). Another way to set the maximum number of messages is to specify it in the configuration file:
           xApMon_maxMsgRate = 30
    By default, the maximum number of messages per second is 50.

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.c file under the examples/ directory.

The program generates some double values for a parameter called "my_cpu_load" 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 <stdlib.h>
       #include <time.h>
       #include "ApMon.h"

2. Initialize the variables we shall use...

       int main(int argc, char **argv) {
         char *destinationsList = " password,";  
         int nDatagrams = 20;
         ApMon *apm;
         double val;
         int i, ret, timestamp;
         if (argc ==2)
           nDatagrams = atoi(argv[1]);

3. Initialize the ApMon structure (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).

       /* initialize the ApMon structure */
       apm = apMon_stringInit(destinationsList);
       if (apm == NULL)
       apMon_errExit("\nError initializing the ApMon structure");

4. Adjust ApMon's settings, 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.

           apMon_setRecheckInterval(apm, 300);
             nDatagrams = atoi(argv[1]);

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

         for (i = 0; i < nDatagrams; i++) {
           /* add a value for the parameter (random between 0 and 2) */
           val = 2 * (double)rand() / RAND_MAX;  
           printf("Sending %lf for cpu_load\n", val);
           /* use the wrapper function with simplified syntax */
           /* (the node name is left NULL, so the local IP will be sent instead) */
           ret = apMon_sendParameter(apm, "TestCluster2_c", NULL, "my_cpu_load", XDR_REAL64, (char *)&val);

6. For each datagram, check that it was send successfully. The ApMon functions return RET_SUCCESS (0) on success and RET_ERROR (-1) if an error occured.

           if (ret != RET_SUCCESS) {
             fprintf(stderr, "\nError sending result");

           /* now send the datagram with a timestamp */
           timestamp = time(NULL) - (5 * 3600); /* as if it was sent 5 hours ago */
           ret = apMon_sendTimedParameter(apm, "TestCluster2_c_5", NULL, "my_cpu_load", XDR_REAL64, (char *)&val, timestamp);
           if (ret != RET_SUCCESS) {
             fprintf(stderr, "\nError sending result");


7. Destroy the ApMon structure:

         return 0;

This, and other documents, can be downloaded from

For questions about MonALISA, write at <>.