In the Perl version, the ApMon features are available
as methods of a class called ApMon. The ApMon
class will start a second process that will verify
periodically the configuration files or webpages for any
changes. The settings are communicated to the main
procress through a local file, stored in temp. This is
because there could be long waiting times for the
downloading and the resolving of the destination hosts
for the udp datagrams. This way, ApMon sendParam* functions will not block.
An ApMon object can be initialized in one of the
following ways (see the manual for details):
passing as parameters a list of locations from
where the configuration will be loaded. These are
strings that represent either a filename, or an URL
address (if they start with http://).
passing as parameter a reference to an array,
containg directly the destinations (host[:port][ pass]). ApMon will send
datagrams to all the valid given destinations (i.e.
hosts that can be resolved), with default options. In
this case, the child process that verifies
configuration files for changes will be not be
started and all function calls refering to this part
will generate an error message.
passing as parameter to the constructor a
reference to a hash. In this case, the keys will be
destinations and the corresponding values will be
references to another hash in which the key is a
configuration option and the value is the value of
that option. Note that in this case, the options
should not be preceded by xApMon_ and options should be 0/1
instead of on/off as in the configuration file. In
this case, the child process that verifies
configuration files for changes will not be started
and all function calls refering to this part will
generate an error message. If system and job
monitoring and general information are disabled, the
child process that performs this monitoring will not
be starting. Any attempts to setMonitorClusterNode or
setJobPID will generate errors.
passing no parameters. In this case, in order to
initialize the destionations for the packets, you
will have to use the setDestinations() function. This
accepts the same parameters as the constructor, as
described above.
2. Sending
Datagrams
To send user parameters to MonALISA, you have the
following set of functions:
Use this to send a set of parameters to all given
destinations. The default cluster an node names will be
updated with the values given here.If afterwards you want
to send more parameters, you can use the shorter version
of this function, sendParams. The parameters to be sent
can be eiter a list, or a reference to a list, a hash or
a reference to a hash with pairs. This list should have
an even length and should contain pairs like (paramName, paramValue). paramValue can be a string, an integer or a
float. Due to the way that Perl interprets functions
parameters, you can put as many parameters in the
function call as you want, not needing to create a list
for this.
sendParams (@params);
Use this to send a set of parameters without
specifying a cluster and a node name. In this case, the
default values for cluster and node name will be used.
See the sendParameters function for more details.
Use this instead of sendParameters to set the time for
each packet that is sent. The time is in seconds from
Epoch. If you use the other function, the time for these
parameters will be sent by the MonALISA serice that
receives them. Note that it is recommended to use the
other version unless you really need to send the
parameters with a different time, since the local time on
the machine might not be synchronized to a time server.
The MonALISA service sets the correct real time for the
packets that it receives.
sendTimedParams ($time, @params);
This is the short version of the sendTimedParameters
that uses the default cluster and node name to sent the
parameters and allows you to specify a time (in seconds
from Epoch) for each packet.
Please see the EXAMPLE file for examples of using
these functions.
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 / webpages, you
should call setConfRecheck($bool,
[$interval]) ; if you want, you can specify the
time interval at which the recheck operatins are
performed.
If you want to disable temporarily sending of
background monitoring information, and to enable it
afterwards, you can use:
enableBgMonitoring ($bool)
If you don't want to have the two background
processes, you can turn them off whenever you want using
the following function:
stopBgProcesses ();
In this case, configuration changes will not be
notified anymore, and no background monitoring will be
performed. To force a configuration check or send
monitoring information about the system and/or jobs, you
can use the following two functions:
refreshConfig ();
sendBgMonitoring ();
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. If work directory is "", no information will be
retrieved about disk:
To change the log-level of the ApMon module, you can
either set it in the configuration file or use the
following function:
setLogLevel(level);
with the following valid log-levels: "DEBUG",
"NOTICE", "INFO", "WARNING", "ERROR", "FATAL"
From the configuration file the log-level can be set
as follows:
xApMon_loglevel = <level>
e.g.,
xApMon_loglevel = FINE
6. Maximum number of
messages
To set the maxim number of messages that can be sent
to a MonALISA service, per second, you can use the
follwing function:
setMaxMsgRate(rate);
By default, it is 50. This is a very large number, and
the idea is to prevent errors from the user. One can
easily put in a for loop, without any sleep, some
sendParams calls that can generate a lot of unnecessary
network load.
You can put this line in the config file:
xApMon_maxMsgRate = 30
The datagrams with general system information are only
sent if system monitoring is enabled, at greater time
intervals (one datagram with general system information
for each 2 system monitoring datagrams).
7. Recreate the ApMon object
If you have to recreate the ApMon object over and over
again, then you should use the following function when
you fininshed using a instance of the ApMon:
free();
This will delete the temporary file and terminate the
background processes. The UDP socket will not be closed,
but if you will reuse ApMon afterwards, it will not open
another socket.
8. Restrictions
The maximum size of a datagram is 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
support UDP datagrams larger than 8KB.
Chapter 3. How to Write a
Simple Perl 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 simple_send.pl file under the examples/ directory.
The program generates values for a few parameters and
sends them to the MonALISA destinations; this action is
repeated in 20 iterations.
With this example program we'll illustrate the steps
that should usually be taken to write a program with
ApMon:
1. Import the ApMon module (and possibly other necessary
modules):
use strict;
use warnings;
use ApMon;
2. Initialize ApMon and possibly set some options (in
this example, we disabled system monitoring). These options
could have also been set from a configuration file, but
here we don't have one.
# Initialize ApMon specifying that it should not send information about the system.
# Note that in this case the background monitoring process isn't stopped, in case you may
# want later to monitor a job.
my $apm = new ApMon({"pcardaab.cern.ch" => {"sys_monitoring" => 0, "general_info" => 0}});
3. Send the datagrams. We used here two functions:
sendParameters, which specifies the cluster name and the
node name (which will be cached in the ApMon object), and
sendParams, which uses the names that were memorized at the
call of the first function.
for my $i (1 .. 20) {
# you can put as many pairs of parameter_name, parameter_value as you want
# but be careful not to create packets longer than 8K.
$apm->sendParameters("SimpleCluster", "SimpleNode", "var_i", $i, "var_i^2", $i * $i);
my $f = (20.0 / $i);
# send in the same cluster and node as last time
$apm->sendParams("var_f", $f, "5_times_f", 5 * $f, "i+f", $i + $f);
sleep(1);
}
