Welcome to Xymon client’s documentation!¶

Home:	https://github.com/romain-dartigues/python-xymon-client

Contents:

Xymon client - library ¶

Contents

Xymon client - library
- Xymon
  - Examples
- Xymon helpers

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)¶

Examples¶

Main library¶

Queries against a single Xymon server¶

>>> from xymon_client.xymon import Xymon
>>> xymon = Xymon('xymonserver01.example.net')
>>> response = xymon.ping()
'xymond 4.3.18\n'

>>> xymon.query('xymonserver02.example.net', 'fping')
'green Message generated by xymonserver01.example.net at mercredi 12 octobre 2016, 08:42:36 (UTC+0200) (executed every 180 sec)\n'

>>> xymon.ghostlist()
[Ghost(hostname='xyz.example.net', address='10.234.71.190', timestamp=1476254463), Ghost(hostname='abc.example.net', address='10.234.71.189', timestamp=1476254435), Ghost(hostname='Combo_xtradb', address='10.234.72.13', timestamp=1476254444), Ghost(hostname='Combo_logs01Snalert01', address='10.234.72.13', timestamp=1476254444)]

>>> xymon.drop('xyz.example.net', 'http')
''

Queries sample¶

>>> xymon = Xymon('xymonserver01.example.net')

>>> # query the Xymon server for yellow alerts
>>> # on hosts whose name starts with "www"
>>> # and only for the fields: hostname, testname and color
>>> xymon.xymondboard('host=^www color=yellow', 'hostname,testname,color')
[[u'www-portal.example.net', u'info', u'yellow'], [u'www02.example.com', u'http', u'yellow']]

>>> # this works all the same:
>>> xymon.xymondboard(
>>>  fields=('hostname', 'testname', 'color'),
...  criteria={'host': '^www', 'color': 'yellow'})
[[u'www-portal.example.net', u'info', u'yellow'], [u'www02.example.com', u'http', u'yellow']]

Queries to multiple Xymon servers at once¶

>>> from xymon_client.xymon import Xymons # note the subtle difference
>>> xymon = Xymons(['xymonserver01.example.net', 'xymonserver02.example.net'])
>>> response = xymon.ping()
{'xymonserver02.example.net:1984': 'xymond 4.3.18\n', 'xymonserver01.example.net:1984': 'xymond 4.3.18\n'}

Helpers¶

from xymon_client.xymon import Xymon
from xymon_client.helpers import *

# create an object with default hostname and default service
xc = Helper(Xymon('xymon.example.net'), 'www.intra.example.net', 'http')

# add a message
xc+= "I see something wrong, let's make it &yellow\n"
xc+= 'Oops, now &red, something gone pear shaped...\n'

# what is the current error level?
xc.color # should be red

# 1. send the content of the current buffer with text added at the end
# 2. override the global color of the message (from red to yellow)
# 3. clear the buffer
xc.status('but it is not *that* bad', color=yellow)

# now the buffer has been cleared

# send another message, same hostname but different service name
xc.status('do not shoot the messenger!', service='logs')

The CLI¶

A command-line interface is also provided; see: xymon-client -h or python -m xymon_client -h.

Example:

$ xymon-client -s xymon01.example.net query --hostname www-portal.example.net --testname info
'yellow Message generated by c234d183-069b-447e-73ab-84d5 at 2019-01-29T16:14:01\n'

Alternatives¶

skurfer/python-xymon¶

Homepage:	https://github.com/skurfer/python-xymon

Pros:

more mature
Python 3 support
use the Xymon appfeed

Cons:

I didn’t see a way to read responses from the server to passed commands
only one server

Welcome to Xymon client’s documentation!¶

Xymon client - library ¶

Xymon ¶

Examples ¶

Xymon helpers ¶

Examples¶

Main library¶

Queries against a single Xymon server¶

Queries sample¶

Queries to multiple Xymon servers at once¶

Helpers¶

The CLI¶

Alternatives¶

skurfer/python-xymon¶

Indices and tables¶

Xymon client

Navigation

Related Topics

Welcome to Xymon client’s documentation!¶

Xymon client - library¶

Xymon¶

Examples¶

Xymon helpers¶

Examples¶

Main library¶

Queries against a single Xymon server¶

Queries sample¶

Queries to multiple Xymon servers at once¶

Helpers¶

The CLI¶

Alternatives¶

skurfer/python-xymon¶

Indices and tables¶

Xymon client - library ¶

Xymon ¶

Examples ¶

Xymon helpers ¶