OneCheck Probe APIs

Introduction#

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 name Decription
dig Uses the dig command to resolve a DNS record.
http Makes HTTP requests with the HTTPClient of the Tornado library.
lighthouse Make Google Lighthouse report for a website
munin Executes various munin checks.
nslookup Resolves host name to IP or IP to host name.
pgsql Checks the availability of PostgreSQL server and allows execution of queries.
ping Pings a distant host.
ssl Checks 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:

Parameter Description
mode string Mode of the probe. Its implementation is strictly probe specific.
timeout integer Timeout of the test in seconds.
_cid string Test identifier.
format string One of simple, text or json. Specifies the output format of a POST request.
tab bool 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" : ["8.8.8.8"], "kwargs" : {"timeout" : "3"}},
             {"cmd" : "ping", "args" : ["www.google.com"], "kwargs" : {"timeout" : "3", "_cid" : "google_com_ping"}},
             {"cmd" : "http-code", "args" : ["http://scaleflex.cloud"], "kwargs" : {"follow_redirects" : "1"}},
             {"cmd" : "http-header", "args" : ["http://scaleflex.cloud"], "kwargs" : {"method" : "GET", "header" : "Content-Type"}},
             {"cmd" : "http-duration", "args" : ["http://scaleflex.cloud"]}
             ]
}
ping 8.8.8.8 timeout=3
ping www.google.fr timeout=5 _cid=google_fr
http-code http://scaleflex.cloud follow_redirects=1
http-header http://scaleflex.cloud method=GET header=Content-Type
http-duration http://scaleflex.cloud

And here is how to execute the request:

host: "http://de2.probe.onecheck.io" path: "/" theme: clouds-midnight editor_theme: clouds_midnight method: POST body: | { "probes" : [ {"cmd" : "ping", "args" : ["8.8.8.8"], "kwargs" : {"timeout" : 3}}, {"cmd" : "ping", "args" : ["www.google.com"], "kwargs" : {"timeout" : 3, "_cid" : "google_com_ping"}}, {"cmd" : "http-code", "args" : ["http://scaleflex.cloud"], "kwargs" : {"follow_redirects" : 1}}, {"cmd" : "http-header", "args" : ["http://scaleflex.cloud"], "kwargs" : {"method" : "GET", "header" : "Content-Type"}}, {"cmd" : "http-duration", "args" : ["http://scaleflex.cloud"]} ] }

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

$ curl http://de3.probe.onecheck.io/ping?ip=8.8.8.8

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 8.8.8.8 timeout=3', 'ping www.google.fr timeout=5 _cid=google_fr',
          'http-code http://scaleflex.cloud follow_redirects=1',
          'http-header http://scaleflex.cloud method=GET header=Content-Type',
          'http-duration http://sample.li/boat.jpg'
]

# 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]+'.probe.onecheck.io'
    else:
        host = 'probe.onecheck.io'
    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))
    else:
        # Otherwise it comes pre-formatted from the probe.
        print(response.body.decode('utf-8'))