Xymon client - library

Xymon

a minimalist Xymon client library in Python

Examples

Queries to one Xymon server:

>>> x = Xymon('xymonserver01.example.net')
>>> x.ping()
'xymond 4.3.18\n'
class xymon_client.xymon.Ghost

Bases: xymon_client.xymon.Ghost

class xymon_client.xymon.Xymon(server='localhost', port=1984, sender=None)

Bases: object

thin library over Xymon protocol

Attempt to reflect xymon(1) [1].

[1]http://xymon.sourceforge.net/xymon/help/manpages/man1/xymon.1.html

General concepts

Colors:Valid colors are defined in color_map.
Times:Called “duration”, “lifetime”. If given as a number followed by s/m/h/d, it is interpreted as being in seconds/minutes/hours/days respectively. For “until OK”, use -1.
client(hostname, ostype, collectorid=None, hostclass=None)
clientlog(hostname, *sectioname)
config(filename)
data(hostname, dataname, text='')
disable(hostname, testname='*', duration=-1, text='')
Parameters:
  • hostname (str) –
  • testname (str) – use an asterisk (*) to disable all tests
  • duration (integer or str) –
  • text (str) –
download(filename)
drop(hostname, testname=None)

remove all data stored about this status

When removing an hostname as whole, it is assumed that you have already deleted the host from the hosts.cfg configuration file.

Parameters:
  • hostname (str) –
  • testname (str) –
enable(hostname, testname)

re-enables a test that had been disabled

Parameters:
  • hostname (str) –
  • testname (str) –
ghostlist()

list of ghost clients seen by the Xymon server

Ghosts are systems that report data to the Xymon server, but are not listed in the hosts.cfg file.

https://www.xymon.com/help/manpages/man1/ghostlist.cgi.1.html

Return type:list(Ghost)
headline
hostinfo(criteria=None)
Parameters:criteria (str) –
Return type:list(list(str))
modify(hostname, testname, color, source, cause)
notes(filename)
notify(hostname, testname, text='')
ping()

ping the server which should return it’s version

Return type:str
pullclient()
query(hostname, testname)

query the Xymon server for the latest status reported for this particular test

Parameters:
  • hostname (str) –
  • testname (str) –
rename(old, new, hostname=None)
schedule(timestamp=None, command=None)

schedule command for execution at a later time

E.g. used to schedule disabling of a host or service at sometime in the future. If no parameters are given, the currently scheduled tasks are listed in the response.

Parameters:
  • command (str or None) – a complete Xymon command such as the ones listed above or ‘cancel JOBID’ to cancel a previously scheduled command
  • timestamp – the Unix epoch time when the command will be executed
  • timestamp – int or None
status(hostname, testname, color, text='', lifetime=None, group=None)
Parameters:
  • hostname (str) –
  • testname (str) –
  • color (str) –
  • text (str) –
  • lifetime (None or integer or str) – defines how long this status is valid after being received by the Xymon server
  • group (str or None) – direct alerts from the status to a specific group
usermsg(identifier)
xymondack(hostname, service, validity=60, message='', user=None)

acknowledge a test in error

Parameters:
  • hostname (str) –
  • testname (str) –
  • validity (int) – ack duration in minutes
  • message (str) – ack message
  • user (str) – acking user
xymondboard(criteria=None, fields=None)
Parameters:
  • criteria (str or dict or list) – (example: color=red)
  • fields (str or list) – (example: hostname,testname,cookie,ackmsg,dismsg)
Return type:

list
xymondlog(hostname, testname)
Parameters:
  • hostname (str) –
  • testname (str) –
Return type:

str
Returns:

status as received (example: may contain HTML)
xymondxboard(criteria=None, fields=None)

Same as xymondboard() :rtype: str :return: the board XML serialized

xymondxlog(hostname, testname)
Parameters:
  • hostname (str) –
  • testname (str) –
Return type:

str
Returns:

status in XML
class xymon_client.xymon.Xymons(servers, port=1984, sender='build-8467708-project-64104-python-xymon-client', thread=False)

Bases: object

xymon_client.xymon.joiniterable(obj, sep=', ')

join obj with sep if it is a non-string iterable

Parameters:
  • obj (mixed) – object to be joined
  • str (sep) –
Return type:

str

Xymon helpers

helpers for the Xymon Python-based library

class xymon_client.helpers.Color

Bases: float

describe a Xymon color (status)

name = None

textual representation of the color

class xymon_client.helpers.Helper(xymon, hostname=None, testname=None)

Bases: object

Examples:

# create an object with default hostname and default service
>>> x = Helper(Xymon('xymon.example.net'), 'www.intra.example.net', 'http')
# add a message
>>> x+= '&red something gone pear shaped\n'
# send the content of the current buffer with text added at the end
# override the global color of the message (from red to yellow)
# clear the buffer
>>> x.status('but it is not *that* bad', color=yellow)
# now the buffer has been cleared
# send another message, same hostname but different service name
>>> x.status('do not shoott the messenger!', service='logs')
color

current highest level color or clear if none found

get_colors(text, default=None)

extract all colors from text

Parameters:
  • text (str) –
  • default (None or Color) –
Return type:

list(Color)
r_color = <_sre.SRE_Pattern object>

extract status identifiers

status(message='', **kwargs)