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 using csender

Starting with cagent version 1.2.8 a handy command line utility called csender is included. With csender you can send your custom check data with easy. Csender is included in all versions of cagent (Windows and Linux). Using the installer packages (DEB, RPM, MSI) the csender or csender.exe binary is in your path. You can execute without specifying the full path.

Examples

Create a custom check called backup and copy the token to your clipboard.

A custom check called "backup"

Now execute csender to submit any data

csender -t GXXXXOBN \
-n backup \
-s 1 \
-a "This text triggers an alert. Optional" \
-w "This text triggers a warning. Optional" \
any_number=1 \
any_float=0.1245 \
any_string="Put your check result here"

This example shows a single command spread over multiple lines. On Linux the backslash \ is used at the end of the line. On the Powershell use a backtick ` On the cmd.exe prompt use the ^ sign.

Specifying -t <TOKEN> and -n <NAME OF CHECK> is mandatory. The rest is optional. -a is for sending an optional alert message. It triggers an immediate alert and will be sent to all recipients. If you omit the alert message all previous alerts will be recovered. -w is for sending an optional warning message. It triggers an immediate warning and will be sent to all recipients. If you omit the warning message all previous alerts will be recovered. -s is for specifying the success of your custom check as number, where 1 is considered success and 0 as failure. Sending 0 triggers an alert that is sent to all recipients.

You can append any key-value-pairs separated by an equal sign.

Sending data using a script

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.")