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

Uptime: 104 days, 0h, 59m
Number of requests: 5329797
since 28 October 2005
ApMon Java User Guide

ApMon Java User Guide

Chapter 1. Installation

The ApMon archive contains the following files and folders:

  • apmon/ - package that contains the ApMon class and other helper classes:
  • 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
  •, env_apmon - for building on Linux systems
  • build_apmon.bat - for building on Windows systems
  • 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:

  1. set the JAVA_HOME environment variable to the location where Java is installed
  2. To build ApMon, cd to the ApMon directory and type:
    The ApMon jar file (apmon.jar) and a small Linux library ( 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 (this library only provides one function, mygetpid(), which has the functionality of getpid(). You might want to use it for job monitoring, as in and ). You can adjust the CLASSPATH and LD_LIBRARY_PATH manually or by sourcing the env_apmon script.
  3. To build the ApMon examples, go to the examples/ directory and type:

To build ApMon on Windows systems:

  1. add the directory that contains the apmon package to the CLASSPATH
  2. run build_apmon.bat
  3. 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

Chapter 2. Using ApMon

1. ApMon Initialization

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

ApMon(Vector destAddresses, Vector destPorts, Vector 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:

  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 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:

        void addJobToMonitor(int pid, String workDir, String clusterName, String nodeName);

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>


       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 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):

      import java.util.Vector;
      import java.util.logging.Logger;
      import apmon.*;

2. Initialize the variables we shall use..

      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,, 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:

          destList.add(new String(" password"));
          destList.add(new String(""));
          try {
            apm = new ApMon(destList);
          } catch (Exception e) {
            logger.severe("Error initializing ApMon: " + e);

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
          // this way we can change the logging level

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;
  "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 {
            } catch (Exception e) {}
          } // for

6. Stop ApMon:


This, and other documents, can be downloaded from

For questions about MonALISA, write at <>.