MonALISA Grid Monitoring
Menu mode: dynamic | fixed
  HOME       CLIENTS       REPOSITORIES       DOWNLOADS       LOOKING GLASS       FAST DATA TRANSFER  
Last update on:
Dec 03, 2015

Uptime: 147 days, 3h, 1m
Number of requests: 5618350
since 28 October 2005
ApMon Perl User Guide

ApMon Perl User Guide


Chapter 1. Installation

The ApMon archive contains the following files in the ApMon module:

  • ApMon.pm - main ApMon module. It can be instantiated by users to send data.
  • ApMon/Common.pm - contains common functions for all other modules.
  • ApMon/XDRUtils.pm - contains functions that encode different values in XDR format
  • ApMon/ProcInfo.pm - procedures to monitor the system and a given application
  • ApMon/ConfigLoader.pm - manages configuration retrieval from multiple places
  • ApMon/BgMonitor.pm - handles the background monitoring of system and applications
  • README
  • example/* - a set of examples with the usage of the ApMon module.
  • example/destinations.conf - a sample destinations file, for url/file configuration
  • MAN - a short description and API functions

To install this module type the following:

      perl Makefile.PL
      make
      make test
      make install
   

DEPENDENCIES:

This module requires these other modules and libraries:

      Data::Dumper
      LWP::UserAgent
      Socket
      Exporter
   

Chapter 2. Using ApMon

1. ApMon Initialization

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:

        sendParameters ( $clusterName, $nodeName, @params);
     

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.

        sendTimedParameters ($clusterName, $nodeName, $time, @params);
     

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:

        addJobToMonitor ($pid, $workDir, $clusterName, $nodeName);
     

To stop monitoring a job, just call:

        removeJobToMonitor ($pid);
     

5. Logging

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);
      }
   

This, and other documents, can be downloaded from http://monalisa.cacr.caltech.edu/

For questions about MonALISA, write at <support@monalisa.cern.ch>.