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 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
- 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:
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 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:
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>
e.g.,
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]= {"http://lcfg.rogrid.pub.ro/~corina/destinations_2.conf",
"rb.rogrid.pub.ro 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, rb.rogrid.pub.ro, 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());
}
sleep(2);
} // for
} catch(runtime_error &e) {
logger(WARNING, e.what());
}
return 0;
}
