Module development

Note: this documentation is currently only relevant for resmon 1 modules. For resmon 2, a number of things have changed. Until this page has been updated, you can look at the lib/Core/Sample.pm module that comes with resmon for an example.

One of resmon's strengths is the ease of creating new modules for specific tasks that are not covered by the built in modules. The quickest way to see how a module is created is probably to look at existing modules (in the lib/Resmon/Module/ dir) and see how they work.

  • handler method
    • evey module has this method, called once per check
    • has a single argument passed to it, a hash containing the configuration of the object:
      • $arg/$self
        • $arg->{'object'}
          • This contains the name of the individual check (the left hand side of a configuration entry
        • $arg->{'arg1'}
          • Other arguments on the right hand side of the check are contained in here also
    • return status, "message"
      • Status can be one of:
        • BAD
        • WARNING
        • OK
      • Message is a text description of the result
        • Note: if the check has a numeric output (such as memory in use), it is a good idea to include this at the very beginning to allow automated tools to detect and make use of this value.
        • You can also return an array ref for the message, with two elements. The first element is the message itself, the second is a character denoting the type of the message. For example:
          return "OK", ["99", "i"]
          
          The possible types are as follows. Any other value gets changed to '0':
          • 0 - autodetect (this is the default)
          • i - signed 32 bit integer
          • I - unsigned 32 bit integer
          • l - signed 64 bit integer
          • L - unsigned 64 bit integer
          • n - double
          • s - string
        • This adds a 'type' attribute to the message in the xml output, allowing external tools to extract information from the message.
    • running external commands
      • Very often, a check may need to make use of another command. The cache_command function will run a command and cache the output so the command is only run as often as needed:
        • cache_command("/path/to/command", timeout)

An alternative to writing a full blown module is to make use of the SCRIPT module. This module runs a simple script and take the check status from the script's output. This is most useful if you have an already existing script, where the only change required is the output format.

testmod script

A simple script is available for testing modules in development. When run, it will load a module, run its check once, and print the status to stdout. This is often quicker than restarting resmon every time a change is made, and can be used alongside a running resmon server without disturbing it.

  • Download from https://labs.omniti.com/resmon/branches/testmod
  • Edit the testmod script, filling in the values for $module and %kvs
    • $module - the module name to load
    • $kvs{'object'} - the name of the check from the left hand side of the config file. The same value that would get stored in $arg{'object'} read by your module.
    • $kvs{'other'} - add extra arguments as needed.
  • Place your module in the Resmon/Module/ directory.
  • Run the script
  • If an error occurs loading the module, you can try running the module directly as a script (perl Resmon/Module/MODULENAME.pm). This will usually pick up any syntax errors and give a more meaningful error than if run via resmon or the testmod script.