Custom checks

You can't make sure all systems that you maintain are running well, unless you monitor thoroughly. With MonitLab's support for custom monitoring checks, you can easily set up checking of anything you need.

What is a custom check?


A custom check is a way to monitor anything that doesn't fit with the specialized checks that we provide (website monitoring, network monitoring, etc.).

By using a custom check, MonitLab can provide you both with monitoring (and notifications) and with graphing of custom values (see below).

Setting up a custom checks necessitates that you do some programming.

Here's a few examples of custom things you may wish to monitor (and graph):

  • number of available items in your inventory
  • number of pending orders for your ecommerce shop
  • last update time of something that needs to be kept updated often
  • temperature values coming from some sensor
  • number of email messages your email server sent (relayed) in the last X hours


Setting up an HTTP JSON endpoint


The way custom checks work is that you provide us a URL that returns status information and MonitLab makes sure to check that periodically and consume the result.

The URL needs to return a JSON response, which describes the current state of the service being monitored.
You can write whatever logic is needed (in whatever programming language you like) to determine what the state is.

Your code could be inspecting video camera imagery, reading temperature sensors over the intranet, communicating with remote servers, etc. MonitLab only cares about the result.

The JSON result that you provide needs to have the following fields:

  • state (string) - the state that you've determined the service to be in (one of "ok", "failing", "undetermined")
  • message - (string) a friendly message that describes the current state (e.g. "OK. Sensor value: 68F")
  • metrics - (dictionary/hashmap, optional field) - some metrics that you wish to report to MonitLab for graphing purposes (e.g. temperature = 68.5, humidity = 32)

Here's an example in JSON:

    "state": "ok",
    "message": "Sensor value: 68F",
    "metrics": {
        "temperature": 68.5,
        "humidity": 32


Hooking that to MonitLab


Once you have your code in place, you can set up an HTTP JSON check in MonitLab's user interface, pointing it to the URL that responds with that JSON (e.g.

MonitLab will ask your server for the state every once in a while and will alert you in case:

  • you report that state = failing
  • your server returns an invalid JSON response
  • your server is completely unreachable

A custom check is just like any other MonitLab check - you choose the checking interval, people to notify, reminder notifications configuration, etc.

The difference is that in this case you get to tell us what the monitoring state is and you get the complete freedom to monitoring anything you want in any way you wish.


Automatic graphing for your custom metrics


Not only does MonitLab check and notify you, but it will also graph custom metrics that you provide in the JSON response (up to 30 different metrics).

We don't just graph too. You get to see the actual raw values.