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:

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:

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:

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