To compile the ApMon routines and all the examples,
type:
./configure [options]
make
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.
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
There are two ways in which the user can send
parameter values to MonALISA:
- a single parameter in a datagram
- 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.
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>
e.g.,
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.
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 = "rb.rogrid.pub.ro password, http://lcfg.rogrid.pub.ro/~corina/destinations_2.conf";
int nDatagrams = 20;
ApMon *apm;
double val;
int i, ret, timestamp;
srand(time(NULL));
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, rb.rogrid.pub.ro, 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) {
apMon_free(apm);
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) {
apMon_free(apm);
fprintf(stderr, "\nError sending result");
}
sleep(2);
}
7. Destroy the ApMon structure:
apMon_free(apm);
return 0;
}
