OneCheck Probe APIs


This section summarizes the use of OneCheck probes, allowing quck checks on a single element of your infrastructure. The last subsection provides a small working Python example how to make more complex requests.

The table below lists currently available probes:

Probe nameDecription
digUses the dig command to resolve a DNS record.
httpMakes HTTP requests with the HTTPClient of the Tornado library.
lighthouseMake Google Lighthouse report for a website
muninExecutes various munin checks.
nslookupResolves host name to IP or IP to host name.
pgsqlChecks the availability of PostgreSQL server and allows execution of queries.
pingPings a distant host.
sslChecks TLS certificate validity, expiry date and commonName/aliases.

Most probes support a mode, which can be specified as a suffix to the probe name. For instance, http-code would call the http probe with mode='code' as argument. This is an exhaustive list of all the common probe arguments:

modestring Mode of the probe. Its implementation is strictly probe specific.
timeoutinteger Timeout of the test in seconds.
_cidstring Test identifier.
formatstring One of simple, text or json. Specifies the output format of a POST request.
tabbool 1 or 0. Indicates formatted table output when using text format.

Scheduling tests#

Requests to the probes can be done in three separate ways. The first one is the most complete. It consists of a POST request to the probe that describes all the tests one wants to run, thus allows the execution of multiple tests. The format of this description may be either a JSON object or plain text. The following examples represent respectively the JSON and plain text request formats:

  "probes" : [
             {"cmd" : "ping", "args" : [""], "kwargs" : {"timeout" : "3"}},
             {"cmd" : "ping", "args" : [""], "kwargs" : {"timeout" : "3", "_cid" : "google_com_ping"}},
             {"cmd" : "http-code", "args" : [""], "kwargs" : {"follow_redirects" : "1"}},
             {"cmd" : "http-header", "args" : [""], "kwargs" : {"method" : "GET", "header" : "Content-Type"}},
             {"cmd" : "http-duration", "args" : [""]}
ping timeout=3
ping timeout=5 _cid=google_fr
http-code follow_redirects=1
http-header method=GET header=Content-Type

And here is how to execute the request:

host: "" path: "/" theme: clouds-midnight editor_theme: clouds_midnight method: POST body: | { "probes" : [ {"cmd" : "ping", "args" : [""], "kwargs" : {"timeout" : 3}}, {"cmd" : "ping", "args" : [""], "kwargs" : {"timeout" : 3, "_cid" : "google_com_ping"}}, {"cmd" : "http-code", "args" : [""], "kwargs" : {"follow_redirects" : 1}}, {"cmd" : "http-header", "args" : [""], "kwargs" : {"method" : "GET", "header" : "Content-Type"}}, {"cmd" : "http-duration", "args" : [""]} ] }

To execute a simple test, let's say get Ping RTT, the following syntax can be used:

$ curl

Writing a program#

The API's versatile HTTP interface makes it suitable for embedding into both client and server side applications. The following Python example send a bunch of checks contained within one request at retrieves the results as a table.

#!/usr/bin/env python

import json
import sys

# Use Tornado HTTPClient class. This can be substituted with the requests library.
from tornado.httpclient import HTTPClient
from urllib.parse import urlencode

# Describe the checks
PROBES = ['ping timeout=3', 'ping timeout=5 _cid=google_fr',
          'http-code follow_redirects=1',
          'http-header method=GET header=Content-Type',

# Here we specify text table format.
FMT = 'text'
TAB = '1'

if __name__ == '__main__':
    if len(sys.argv) > 1:
        # As argument to the program you can specify the name of a probe
        host = sys.argv[1]+''
        host = ''
    print("Sending request to {host}".format(host=host))
    # Create the request body
    data = "\n".join(PROBES).encode('utf-8')
    # Encode the query string parameters
    query_string = urlencode({'format': FMT, 'tab': TAB})
    client = HTTPClient()
    # Make the actual request
    response = client.fetch('http://'+host+'/?'+query_string, method='POST',
                            headers={'Content-Type': 'text/plain'}, body=data) #, validate_cert=False)
    if FMT == 'json':
        # If the response is a JSON, pretty-print it
        obj = json.loads(response.body.decode('utf-8'))
        print(json.dumps(obj, indent=4))
        # Otherwise it comes pre-formatted from the probe.