Custom Checks

Send any data as check results.

Preface

Custom checks allow you to gather data from any application, device or system and use this data as check results. Based on your custom checks you can set up rules for alerting.

Add a custom check

Using the web interface, select a host and click on the plus sign of "Custom Check".

Enter a name of the check. The name must not contain white space or special characters. This name is the common prefix of all check results you'll send later. Let's say you want to monitor the success of your backups. So backup is a perfect name for your custom check.

Optionally enter a frequency - minutes or hours - you expect the custom check to send new data. If you enter an expected update interval alerting is automatically enabled if your custom check stops sending data within the expected period. It's highly recommended to use the option. Otherwise your check script may fail completely and you wont notice it. If you perform backups once a day an expected update interval of 25 hours is perfect. Your check execution and our check intervals cannot be synchronised to a second. So put some tolerance.

Custom checks must be created on a host level. Creating global custom checks for a group of hosts or all hosts is not yet possible.

Add a custom check

Sending data

To send results you need to know the name of your custom check, and the unique token of it. You can use any http client to send json-encoded check results. You can send up to 12 key-value-pairs for each custom check.

The data must be sent using HTTP POST to the URL https://hub.cloudradar.io/cct/.

All keys must be prefixed with the name of your custom check, for example backup.success. If the key prefix doesn't belong to the custom check identified by the token, the request is rejected.

Sending data for multiple custom checks within a single request is not allowed, as you can use only one token and only one key prefix in a single request.

Your are free to use any keys as long as they don't contain whitespace or special characters. The key length is limited to 100 bytes and the value is limited to 500 bytes. If you exceed this limit with one of the key-value-pairs the entire request is rejected and your check results are not stored.

A curl example

curl -X POST \
https://hub.cloudradar.io/cct/ \
-H 'X-CustomCheck-Token: uGXgXr2Zy' \
-d '{
"backup.success": 1,
"backup.data_sent_B": 256791,
"backup.num_folders_in_backup": 345,
"backup.target" : "backup.example.com",
"backup.transport": "rsync",
"backup.duration_s": 2569
}'

A python example

custom-check.py
#!/usr/bin/env python
import requests
import json
import sys
token = '1234abc'
url = "https://hub.cloudradar.io/cct/"
payload = {
"backup.success": 1,
"backup.data_sent_B": 256791,
"backup.num_folders_in_backup": 345,
"backup.target" : "backup.example.com",
"backup.transport": "rsync",
"backup.duration_s": 2569
}
headers = { 'X-CustomCheck-Token': token }
response = requests.request("POST", url, data=json.dumps(payload), headers=headers)
if response.status_code != 204:
sys.stderr.write("Sending data failed. " + response.text + "\n" )
sys.exit(response.status_code)
print("All data sent.")
Review the data sent by a custom check

Another example showing how to monitor the size of some files

filemonitoring.py
#!/usr/bin/env python
import requests
import json
import sys
import os
#
# Example how to monitor the size of some files
# and how to trigger an alert or warning
#
# List of files you want to supervise
files = ['/etc/hosts','/etc/passwd','/etc/issue','/tmp/foo']
# Threshold in bytes. If exceeded, an alert is triggered.
threshold = 10000
# Your token of the custom check
token = 'xxxxxxx'
# Name of the custom check. Needs to be created on my.cloduradar.io first!
check = 'files'
# URL of cloudradars data hub. No need to change.
url = "https://hub.cloudradar.io/cct/"
payload = dict()
alerts = []
warnings = []
for file in files:
try:
# Read the file size in bytes
file_size = os.stat(file).st_size
if file_size > threshold:
alerts.append("%s exceedes size of %s" % (file,threshold))
except OSError:
# Set file size to -1 if the file does not exist
file_size = -1
warnings.append("%s file not found" % file)
payload[check+'.'+file] = int(file_size)
if len(alerts) > 0:
# Include alerts that will trigger a message on cloudradar
payload[check+'.alert'] = ",".join(alerts)
if len(warnings) > 0:
# Include warnings that will trigger a message on cloudradar
payload[check+'.warning'] = ",".join(warnings)
headers = { 'X-CustomCheck-Token': token }
response = requests.request("POST", url, data=json.dumps(payload), headers=headers)
if response.status_code != 204:
sys.stderr.write("Sending data failed. " + response.text + "\n" )
sys.exit(response.status_code)
print("All data sent.")