kfront
Introduction
kfront is a python library that provides an interface to Knowledge Front's REST API.
This library had been tested for compatibility with Python 2.7 and 3.6. Support for other versions of Python is not guaranteed or supported.
Installation
This package is available on PyPI. If you want the latest version, you can install it via the usual method:
$ pip3 install kfront
To upgrade:
$ pip3 install --upgrade kfront
Use in rpm projects
When using this module with another python package that's to be installed as an rpm, it is recommended you vendor it with the rest of your modules, to avoid conflicts / alternate versions.
Just include it in your requirements.txt:
# requirements.txt
kfront
For the latest development version (not recommended):
git+https://github.com/Stealthii/python-kfront.git@master
Documentation
There is only one class, KnowledgeFront. This provides a client interface
for using Knowledge Front's API service, to work with your monitors.
Authentication
You can initialize the client with a username & password like so:
>>> from kfront import KnowledgeFront
>>> sesh = KnowledgeFront('username', 'password')or, you can use netrc authentication (recommended):
$ cat ~/.netrc
machine api.knowledgefront.com
login username@example.com
password buongiorno>>> from kfront import KnowledgeFront
>>> sesh = KnowledgeFront()Alert Status Summary
You can get a quick summary of the status of your alerts with get_status():
>>> from kfront import KnowledgeFront
>>> sesh = KnowledgeFront()
>>> status = sesh.get_status()
>>> status['global_alert_active']
False
>>> status['monitor_list']
>>> from pprint import pprint
>>> pprint(status['monitor_list'])
[{u'alert_active': False,
u'id': u'3974cd4117d892b20e3becdc239bc6394f499b60e3ed542c90ce5147',
u'label': u'Example Monitor 1',
u'type': u'SMTP Email Monitor (Mailive!)'},
{u'alert_active': False,
u'id': u'453a562176c84935ce4dbf47123fa4540b43785c3e311c5dcf2546e4',
u'label': u'Example Monitor 2',
u'type': u'SMTP Email Monitor (Mailive!)'}]global_alert_active will be true if any of your configured alerts are
active.
There are also properties for the above, if preferred:
>>> sesh.global_alert_active
False
>>> sesh.status
[same as above]Monitors
You can get, add, modify, and remove monitors using the API. Let's look for monitors matching some text in a label:
>>> monitors = sesh.get_monitors()['monitor_list']
>>> [monitor for monitor in monitors if 'example_cust' in monitor['label']]
[{u'description': None, u'message_format': u'text/plain', u'ttl': 0, u'type': u'SMTP', u'alerts': [u'aad4c7a73e6cbe72c3c19b69e7566a839f5b4d34bc48ae1932102844'], u'test_account': u'mailive@knowledgefront.com', u'time_zone': u'US/Pacific', u'timer': 5, u'label': u'example_cust - DC1', u'use_tls': u'auto', u'custom_subject': u'', u'custom_body': u'', u'attachment': None, u'ipv6': False, u'ip_address': u'mk0b.example.com', u'id': u'58115b485816f1cc814cba12b44c3bf84adc7081febceefb89a85911', u'data_label': u'seconds'}, {u'description': None, u'message_format': u'text/plain', u'ttl': 0, u'type': u'SMTP', u'alerts': [u'e3cd86258283a5750b62def8507f126bb929e330fa7b88a38a6c78c9'], u'test_account': u'mailive@knowledgefront.com', u'time_zone': u'US/Pacific', u'timer': 5, u'label': u'example_cust - DC2', u'use_tls': u'auto', u'custom_subject': u'', u'custom_body': u'', u'attachment': None, u'ipv6': False, u'ip_address': u'mx0a.example.com', u'id': u'707579177586b34cfc3c5afa75f45f8c46aa8fdc296c0bd132f85428', u'data_label': u'seconds'}]Creating a monitor:
>>> example = sesh.create_monitor(
... label="Bill & Ted - DC1",
... timer=5,
... time_zone="US/Pacific"
... ip_address="mx0c.excellent.com",
... test_account="mailive@knowledgefront.com"
... )
>>> example['monitor']
{u'description': None, u'message_format': u'text/plain', u'ttl': 0, u'type': u'SMTP', u'alerts': [], u'test_account': u'mailive@knowledgefront.com', u'time_zone': u'US/Pacific', u'timer': 5, u'label': u'Bill & Ted - DC1', u'use_tls': u'off', u'custom_subject': u'', u'custom_body': u'', u'attachment': None, u'ipv6': False, u'ip_address': u'mx0c.excellent.com', u'id': u'538fbd75275a1e2d2fb5547e5ef27b44542be2524e6db4043954c84e', u'data_label': u'seconds'}modify_monitor() works in very much the same way, except you provide the
monitor id argument.
delete_monitor() only takes the monitor id.
Alerts
You can get, add, modify, and remove alerts using the API. Let's look for alerts matching some text the initial subject:
>>> alerts = sesh.get_alerts()['alert_list']
>>> [alert for alert in alerts if 'babes' in alert['subject_init']]
[{u'message_init': u'babes - DC1 email testing failing. View reports at https://www.knowledgefront.com', u'repeat': True, u'monitor': u'c52c12600e6070d7f8d59fc116b3b4887b7dcdffec918ed85d3e843f', u'alert_destinations': [], u'subject_init': u'babes - DC1 not responding to email tests', u'subject_term': u'babes - DC1 responding to email tests', u'message_term': u'babes - DC1 is responding normally to Knowledge Front email testing', u'timeout': 10, u'down_only': False, u'type': u'up-down', u'id': u'7eb87fe58f0d14ea8759dc3ecd954b378f01082fccfc723d71c41ea4'}, {u'message_init': u'babes - DC2 email testing failing. View reports at https://www.knowledgefront.com', u'repeat': True, u'monitor': u'660a8ec2c6911944b4159a498d8814fc6e99d4eb268740bff49a924c', u'alert_destinations': [], u'subject_init': u'babes - DC2 not responding to email tests', u'subject_term': u'babes - DC2 responding to email tests', u'message_term': u'babes - DC2 is responding normally to Knowledge Front email testing', u'timeout': 10, u'down_only': False, u'type': u'up-down', u'id': u'd324e95d50a4dab17721e05956eeda84bb769cdffa90733fc1a29d72'}]Creating an alert for one of our esteemed customers:
>>> excellent_monitors = [monitor for monitor in sesh.monitors if "Bill & Ted" in monitor['label']
>>> excellent_monitors[0]['id']
u'7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7'
>>> for monitor in excellent_monitors:
... sesh.create_alert(
... monitor=monitor['id'],
... subject_init="Excellent!",
... subject_term="Bogus.",
... timeout=10
... )
...
{u'path': u'/v1/Config/Alert/', u'error': None, u'alert': {u'message_init': u'', u'repeat': True, u'monitor': u'7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7', u'alert_destinations': [], u'subject_init': u'Excellent!', u'subject_term': u'Bogus.', u'message_term': u'', u'timeout': 10, u'down_only': False, u'type': u'up-down', u'id': u'4f635a64b45a87919ed335a7cae75ac556d9119f23332a9d7bcb575b'}}modify_alert() works in very much the same way, except you provide the
alert id argument.
delete_alert() only takes the alert id.
Pause Alerting
>>> sesh.paused_alerts
[]
>>> sesh.pause_alert('7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7', seconds=600)
{u'seconds': 600, u'path': u'/v1/Pause/Alert/7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7/', u'alert_list': [u'4f635a64b45a87919ed335a7cae75ac556d9119f23332a9d7bcb575b'], u'error': None}
>>> sesh.paused_alerts
[{u'seconds': 588, u'id': u'4f635a64b45a87919ed335a7cae75ac556d9119f23332a9d7bcb575b'}]
>>> sesh.enable_alert('7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7')
{u'path': u'/v1/Pause/Alert/7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7/', u'alert_list': [u'4f635a64b45a87919ed335a7cae75ac556d9119f23332a9d7bcb575b'], u'error': None}
>>> sesh.paused_alerts
[]Alert Destinations
>>> pprint(sesh.alert_destinations)
[{u'destination': u'bill@wyldstallyns.com',
u'id': u'773a644f43580c5f768ff1da38f725ab9c6a8a9e39f49f4e82f9f76f',
u'label': u'Bill S. Preston',
u'subscribed': True,
u'type': u'EMAIL'},
{u'destination': u'ted@wyldstallyns.com',
u'id': u'f309d00de2189528681f146382947c60c12396d283b3eff90031d558',
u'label': u'Ted "Theodore" Logan',
u'subscribed': True,
u'type': u'EMAIL'}]Monitor Data
>>> sesh.get_monitor_data('7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7')
{u'begin': 1503408469, u'end': 1503412069, u'monitor': u'7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7', u'data': [{u'time': u'2017-08-22T06:54:57', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503410097, u'utc_time': u'2017-08-22T13:54:57'}, {u'time': u'2017-08-22T06:59:57', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503410397, u'utc_time': u'2017-08-22T13:59:57'}, {u'time': u'2017-08-22T07:04:58', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503410698, u'utc_time': u'2017-08-22T14:04:58'}, {u'time': u'2017-08-22T07:09:57', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503410997, u'utc_time': u'2017-08-22T14:09:57'}, {u'time': u'2017-08-22T07:14:57', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503411297, u'utc_time': u'2017-08-22T14:14:57'}, {u'time': u'2017-08-22T07:19:57', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503411597, u'utc_time': u'2017-08-22T14:19:57'}, {u'time': u'2017-08-22T07:24:57', u'alert_matches': [], u'value': 1000.0, u'failed': False, u'location': u'3', u'samples': 1, u'error': None, u'failures': None, u'utc_mktime': 1503411897, u'utc_time': u'2017-08-22T14:24:57'}], u'error': None, u'path': u'/v1/Data/Monitor/7b326136af5ce3037aa32dd20737d6d8ee7b9533055f721be7a768f7/', u'monitor_label': u'Bill & Ted - DC1'}
