The ApMon archive contains the following files and
folders:
apmon/ -
package that contains the ApMon class and other
helper classes:
XDRDataOutput and
XDROutputStream, which
are a part of a library for XDR
encoding/decoding, provided under the LGPL
license - see http://java.freehep.org
lib/ -
directory which will contain, after building, the
libraries needed in order to use ApMon
examples/
examples for using the routines
lesser.txt -
the LGPL license for the XDR library
destinations.conf - contains
the IP addresses or DNS names of the destination hosts
and the ports where the MonaLisa modules listen
build_apmon.sh,
env_apmon - for building on Linux
systems
build_apmon.bat - for
building on Windows systems
README
Doxyfile -
for generating Doxygen documentation
There is an additional directory, ApMon_docs, which contains the
Doxygen documentation of the source files.
To build ApMon on Linux systems:
set the JAVA_HOME environment variable to the
location where Java is installed
To build ApMon, cd to the ApMon directory and type:
./build_apmon.sh
The ApMon jar file (apmon.jar) and a small
Linux library (libnativeapm.so) are now
available in the lib/ directory. In order
to use ApMon, the CLASSPATH must contain the path to
apmon.jar and,
optionally, the LD_LIBRARY_PATH must contain the path
to libnativeapm.so (this
library only provides one function, mygetpid(), which
has the functionality of getpid(). You might want to use it for
job monitoring, as in Example_x1.java and Example_x2.java ).
You can adjust the CLASSPATH and LD_LIBRARY_PATH
manually or by sourcing the env_apmon script.
To build the ApMon examples, go to the examples/
directory and type:
./build_examples.sh
To build ApMon on Windows systems:
add the directory that contains the apmon package
to the CLASSPATH
run build_apmon.bat
when running the examples, the directory apmon\lisa_host\Windows
must be in the library path (the system.dll library from
this directory will be used). This can be done by
using the option -Djava.library.path:
java -Djava.library.path=<path to apmon\lisa_host\Windows> exampleSend_1a
In the Java 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(String filename);
- initializes ApMon from a configuration file whose
name is given as parameter
ApMon(Vector destList);
- initializes ApMon from a vector which contain
strings of the form "address:[port][ password]"
specifying destination hosts, and/or addresses of
configuration webpages
- 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,
apMon_sendTimedParameter() and
sendTimedParameters() , which
allow the user to specify a timestamp for the
parameters.
IMPORTANT: When the ApMon object is no longer in use,
the stopIt() method should be
called in order to close the UDP socket used for sending
the parameters.
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(int pid) should be
called.
5. Logging
ApMon prints its messages to a file called apmon.log,
with the aid of the Logger
class from the Java API. The user may print its own
messages with the logger (see the examples). The ApMon
loglevels are FATAL (equivalent to Level.SEVERE),
WARNING, INFO, FINE, DEBUG (equivalent to Level.FINEST).
The ApMon loglevel can be set from the configuration file
(by default it is INFO):
xApMon_loglevel = <level>
e.g.,
xApMon_loglevel = FINE
When setting the loglevel in the configuration file,
you must use the ApMon level names rather than the Java
names (so that the configuration file be compatible with
the other ApMon versions).
The loglevel can also be set with the function setLogLevel() from the ApMon
class.
6. 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 Java 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.java
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. Import the ApMon package (and possibly other
necessary packages):
public class Example_2 {
private static Logger logger = Logger.getLogger("apmon");
public static void main(String args[]) {
Vector destList = new Vector();
int nDatagrams = 20;
ApMon apm = null;
double val = 0;
int i, timestamp;
if (args.length == 1)
nDatagrams = Integer.parseInt(args[0]);
3. Construct an ApMon object (in this example we used an
intialization list containing the name of a destination
host, ui.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:
4. Adjust the settings for the ApMon object, if
necessary (here we set the time interval for reloading the
configuration page to 300 sec, and we change the logging
level to DEBUG). This can also be done from the
configuration file.
// set the time interval for periodically checking the
// configuration URL
apm.setRecheckInterval(300);
// this way we can change the logging level
apm.setLogLevel("DEBUG");
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 - 1; i++) {
val += 0.05;
if (val > 2)
val = 0;
logger.info("Sending " + val + " for cpu_load");
try {
/* use the wrapper function with simplified syntax */
apm.sendParameter("TestCluster2_java", null, "my_cpu_load",
ApMon.XDR_REAL64, new Double(val));
/* now send a datagram with timestamp (as if this was 5h ago) */
long crtTime = System.currentTimeMillis();
timestamp = (int)(crtTime / 1000 - (5 * 3600));
apm.sendTimedParameter("TestClusterOld2_java", null, "my_cpu_load",
ApMon.XDR_REAL64, new Double(val), timestamp);
} catch(Exception e) {
logger.warning("Send operation failed: " + e);
}
try {
Thread.sleep(1000);
} catch (Exception e) {}
} // for