Amsterdam Alert 2.0-RC1 API

The Alert framework documentation.

See:
Description

Packages

org.backsource.alert	Toplevel package for alert.
org.backsource.alert.agent
org.backsource.alert.sender
org.backsource.alert.util

The Alert framework documentation.

The Alert framework

The alert framework is a simple system to set up guards of other systems, such as web-, application- or FTP-servers, or other cind of services one want to monitor for healt. It is based on ant and JUnit, and is set upp by installin the alert package, writing an XML-file defining the services to monitor and is then run from a cron job. Every run will be saved as an HTML report, and any Errors and Warnings will also be sent to the Senders defined in XML-file.

Setting up alert

Setting up alert is easy. Get the distribution for alert and unpack it. The next thing to do is define the services one wants to monitor and the senders one want to get any errors sent to. Monitoring in alert is done by something called Agents. An agent is a specialized JUnit TestCase. There are a number of ready built Agents available in org.backsource.alert.agent.

When setting up an alert, one defines one or more instances of an agent that should be run. This is done in an XML-file that follows the alert.dtd. An alert XML files start with an alert element. This is followed by an agents element and a senderselement. The agents element may contain one or more agent elements. Each agent element represents a uniue check/test to be made, with a unique configuration. An agent element must be given a code attribute pointing to the class implementing the agent, a method to invoke on that class to run the test and a name witch uniquely identifies the agent in the XML-file. The agent may also contain zero or more property elements containg unique properties for the particular agent configuration. If a alert.properties file is given when running the alert, one may use ant style property references in the XML file. Here is an example of an ftp agent:

<alert>
  <!-- Agents is the tests that will check a certain cervice -->
  <agents>
    <!-- Check old and number of files on ftp host -->
    <agent
      code="org.backsource.alert.agent.FtpAgent"
      method="testFtpFiles"
      name="FtpOldFiles">
      <property name="agent.ftp.timeout">${agent.ftp.timeout}</property>
      <property name="agent.ftp.host">${agent.ftp.host}</property>
      <property name="agent.ftp.dir">${agent.ftp.dir}</property>
      <property name="agent.ftp.user">${agent.ftp.user}</property>
      <property name="agent.ftp.pwd">${agent.ftp.pwd}</property>
      <property name="agent.ftp.fileage">${agent.dir.fileage}</property>
      <property name="agent.ftp.no.files">${agent.ftp.no.files}</property>
    </agent>
  </agents>
  <!-- Senders is the components that deliver alerts -->
  <senders>
  </senders>
</alert>

I this case the propertys would also have to be specifyed in a property file, like this:

# FTP test
# 20 seconds
agent.ftp.timeout=20000
agent.ftp.host=pra.tim.se
agent.ftp.dir=.
agent.ftp.user=user
agent.ftp.pwd=pwd
agent.dir.fileage=300000
agent.ftp.no.files=3

The senders follow the same pattern. The available senders are in org.backsource.alert.sender. The senders element may contain one or more sender elements. The sender element must contain the attribute code pointing the the class implementing the sender. Like agents it may also contain any number of propery elements.Here is a mail sender:

   <senders>
    <sender
      code="org.backsource.alert.sender.MailSender">
       <property name="mail.smtp.host">${mail.smtp.host}</property>
       <property name="mail.from">${mail.from}</property>
       <property name="mail.debug">${mail.debug}</property>
       <property name="mail.to.error">pra@tim.se</property>
    </sender>

  </senders>

Like for alerts the real properties would be in a properties file:

# Mail
mail.smtp.host=pumba.tim.se
mail.from=pra@tim.se
mail.debug=false
# Space separated list of mailadresses
mail.to.error=pra@tim.se instant.alarm@tim.se
mail.to.warning=pra@tim.se

An alert is run by running the provided run-alert.xml ant script and invoking the run target. A number of things will then happen.Date specific directorys will be created for the repports, all agents will be run, any errors or warning will be sent to the configured senders and an HTML report will be generated that shows how that particular round went. It is possible to run alert from inside its own directory like this:

cd bin
sh build.sh -file ../resources/run-alert.xml run

This is however not recomended, since it will place loggin output in tmp/logs and will use the alert.xml in resources without any property expansion. The prefered way is to set up an cron jobb and specify a number of system properties. These are:

• alert.xml, points to the XML alert definition file containg the agents and sender definitions.
• alert.properties, point to an optional java properties style file wich contains proerty definitions used when exanding propery references in alert xml.
• log.dir, a directory where the logs will be placed. There will be two subdirectories produced there: run and html. The former containing an XML log of each round of alert check and the latter an HTML version. In each subdirectory logs is placed in a directory of the current date and under that in a directory with the same name as the time was when the alert was run.
• sms.lockfile, my be used by any Sender to signal that is has send an alarm and that it will not send any more until someone has removed the lockfile.
• plugin.dir, of developing Agents or Senders that are not part of alert its is possible to pack these classes into a jarfile and drop that jarfile into a directory. By specifying that directory in plugin.dir alert will pick it up and ad it to the classpath.

Here is a typical example of a cron entry:

ALERT = /home/in/dist/alert-1.0/
0,15,30,45 7-23 * * * cd $ALERT/bin;sh build.sh -file ../resources/run-alert.xml -Dalert-xml=/home/in/etc/alert/hermes.xml -Dalert.properties=/home/in/etc/alert/hermes.properties -Dlog.dir=/home/in/var/alert/logs -Dsms.lockfile=/home/in/var/alert/lock/sms.lockfile run >> /home/in/var/alert/logs/cron/alertcron 2>&1

And here is a typical tree look of the html directory where the logfiles is produced (its recomended to make them available through a webserver):

logs/html/
`-- 20021031
    |-- 12:27:38
    |   |-- TESTS-TestSuites.xml
    |   |-- allclasses-frame.html
    |   |-- index.html
    |   |-- overview-frame.html
    |   |-- overview-summary.html
    |   |-- se
    |   |   `-- tim
    |   |       `-- alert
    |   |           |-- AlertCase.html
    |   |           |-- package-frame.html
    |   |           `-- package-summary.html
    |   `-- stylesheet.css
    `-- 12:33:56
        |-- TESTS-TestSuites.xml
        |-- allclasses-frame.html
        |-- index.html
        |-- overview-frame.html
        |-- overview-summary.html
        |-- se
        |   `-- tim
        |       `-- alert
        |           |-- AlertCase.html
        |           |-- package-frame.html
        |           `-- package-summary.html
        `-- stylesheet.css

Developing new Agents and Senders

To test a new type of service or send to sender that does not yet exist rquires development of new Agents and Senders. If its not possible, for example by not having access to the source of alert, or if the agent are tyed to a specific application, one may develop external Agents and Senders. By specifyining a -Dplugin.dir when running alert it is possible to get those jars available in the alert runtime.

To develop a new Agent one must follow the api given in Agent. An Agent is also a JUnit test case, and must thefore follow the pattern for these objects, i.e: having a constructor that takes a string and calls super with that string. There is a baseclass for writing agens one may use BaseCase.

To develop a new Sender one has to implement the Sender api.

.