madrisan / pyxymon

A simple Python module for writing xymon external scripts

PyXymon

PyXymon is a simple Python module that can help you write Xymon external scripts in Python. PyXymon provides some methods for rendering the messages you want to display in the Xymon web page and for sending them to the Xymon server. PyXymon reads the required informations from the Xymon environment variables, so you do not need to add any extra configuration file.

Installation

Just copy the file pyxymon.py in the xymon ext directory.

Usage

Create a script yourcheck.py using the following schema:

#!/usr/bin/python

import os
import sys
import pyxymon as pymon

CHECK_NAME = 'yourcheck'
CHECK_VERSION = 1

def run_check():
    """Check the status of whatever you want..."""
    xymon = pymon.XymonClient(CHECK_NAME)
    check_script = os.path.basename(__file__)
    # do your logic...
    # you can set the criticity of the final xymon message by using:
    #    xymon.color = pymon.STATUS_WARNING
    # or
    #    xymon.color = pymon.STATUS_CRITICAL
    # The default criticity is set to 'pymon.STATUS_OK' 
    # Optionally you can set the LIFETIME (in minutes) using:
    #    xymon.lifetime = 15
    xymon.title('Title in the xymon check page')
    xymon.section('Section Title',
                  'Text containing the lines you want to display')
    # You can add here other sections, if required.
    xymon.footer(check_script, CHECK_VERSION)
    xymon.send()

def main():
    run_check()

if __name__ == '__main__':
    main()
    sys.exit(0)

Configure your extension module in the file $XYMONCLIENTHOME/etc/xymonclient.cfg.

[yourcheck]
        ENVFILE $XYMONCLIENTHOME/etc/xymonclient.cfg
        CMD $XYMONCLIENTHOME/ext/yourcheck.py
        LOGFILE $XYMONCLIENTLOGS/yourcheck.log
        INTERVAL 10m

You can find a full example here.

Note

If you need to run your Python check with root privileges, just prefix the CMD directive in xymonclient.cfg with the sudo command:

    CMD sudo $XYMONCLIENTHOME/ext/yourcheck.py

By default sudo does not preserve the environment variables exported by Xymon. To preserve the variables required by PyXymon, add the following lines to the sudo configuration:

 Defaults env_keep:xymon += "XYMSRV"
 Defaults env_keep:xymon += "XYMONDPORT"
 Defaults env_keep:xymon += "MACHINE"

pyxymon's Issues

LGTM errors "Explicit export is not defined"

LGTM reports some errors of type "Explicit export is not defined".
These seems to be false positives, but can be perhaps resolved by reorganizing the code.

Add lifetime option for status

currently there's no mechanism to add a LIFETIME to the status report. It defaults to 30 Minutes. Is it possible to add this option?

(From the xymon man page)
status[+LIFETIME][/group:GROUP] HOSTNAME.TESTNAME COLOR
This sends in a status message for a single test (column) on a single host. TESTNAME is the name of the column where this test will show up; any name is valid except that using dots in the testname will not work. COLOR must be one of the valid colors: "green", "yellow", "red" or "clear". The colors "blue" and "purple" - although valid colors - should not be sent in a status message, as these are handled specially by the Xymon server. As a special case (for supporting older clients), "client" can be used as the name of the color. This causes the status message to be handled by Xymon as a "client" data message, and the TESTNAME parameter is used as the "collector id".
The "additional text" normally includes a local timestamp and a summary of the test result on the first line. Any lines following the first one are free-form, and can include any information that may be useful to diagnose the problem being reported.
The LIFETIME defines how long this status is valid after being received by the Xymon server. The default is 30 minutes, but you can set any period you like. E.g. for a custom test that runs once an hour, you will want to set this to at least 60 minutes - otherwise the status will go purple after 30 minutes. It is a good idea to set the LIFETIME to slightly longer than the interval between your tests, to allow for variations in the time it takes your test to complete. The LIFETIME is in minutes, unless you add an "h" (hours), "d" (days) or "w" (weeks) immediately after the number, e.g. "status+5h" for a status that is valid for 5 hours.
The GROUP option is used to direct alerts from the status to a specific group. It is currently used for status generated from the Xymon clients' data, e.g. to direct alerts for a "procs" status to different people, depending on exactly which process is down.