AlertBee

Introduction

AlertBee is a SaaS application that allows you to monitor cron jobs, background tasks, queue systems, IoT devices and more via a push, rather than poll, mechanism. You use the AlertBee Dashboard to create a monitor and then configure your job to ping AlertBee when it runs.

If your job ever misbehaves, AlertBee will send you a notification via the method(s) that you've configured.

Monitors and Conditions

Monitors are the core component of AlertBee and they represent the "thing" that you are looking to get notifications about. Monitors consist of conditions, which are rules that decide when to send a notification, and notification methods, which are the actual methods AlertBee will use to notify you when a condition is triggered.

Conditions come in two flavors, value based and run based. Value based conditions are concerned with a specific piece of data, which can be numbers or strings, that your job sends to AlertBee.

Run based conditions are concerned with when and if your job is running and checking in with AlertBee. All run based conditions are initialized by their first check-in, which is the time that it will use to consider if subsequent runs are normal or need to trigger a notification.

More information about each type of condition can be found below.

AlertBee currently supports 3 core notification methods: Email, SMS and Webhook. We are working to add additional methods like PagerDuty, Slack, HipChat and more.

Value: Equality / Inequality

Equality and Inequality conditions are used when you want to know if your job is sending, or not sending, a specific value. This value can be a number or a string.

Associated Conditions:

  • Received value equals
  • Received value does not equal

For example, say you have a cron job that runs once a day and ensures there are files in a directory. If there are, it sends the value "populated" to AlertBee. If, however, the directory is empty it sends the value "empty" to AlertBee. You can configure a monitor in AlertBee that will trigger if the received value is "empty" so that you get a notification when this is the case.

# m h dom mon dow    command
*/5 * * * * curl -m 10 https://ping.alertbee.io/xc4ab7ab/55$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/55',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);import requests

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/55',
    timeout=10
)require 'open-uri'

open(
    'https://ping.alertbee.io/xc4ab7ab/55',
    :read_timeout=>10
)

Value: Greater Than / Less Than

Greater Than and Less Than conditions are used when you want to know if a received value is above or below a specific value. This value has to be a number.

Associated Conditions:

  • Received value is less than
  • Received value is greater than

For example, say you have a queue system in your application that is consumed by workers. You want to ensure that items in this queue are being processed successfully and in the expected amount of time. If you know that your queue normally stays below 50 items, you can configure a monitor in AlertBee that will alert you if there are ever more than 50 items in the queue. Then, in your worker you just need to ping AlertBee with the current number of items in the queue. If you ever need to change the alert threshold, it's as simple as editing the monitor in AlertBee to change the trigger value.

# m h dom mon dow    command
*/5 * * * * curl -m 10 https://ping.alertbee.io/xc4ab7ab/55$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/55',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);import requests

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/55',
    timeout=10
)require 'open-uri'

open(
    'https://ping.alertbee.io/xc4ab7ab/55',
    :read_timeout=>10
)

Value: Inside / Outside Range

Inside / Outside Range conditions are used to ensure that a value falls within, or outside of, a certain range of values. This value has to be a number.

Associated Conditions:

  • Received value is between A and B
  • Received value is not between A and B

For example, say you have a temperature probe attached to a microcontroller. You want to ensure that the temperature being read by the probe is between 40 and 70 degrees. You can configure a monitor in AlertBee that will trigger if the value it receives is less than 40 or greater than 70 so that you receive a notification when the temperature is outside the range specified range.

# m h dom mon dow    command
*/5 * * * * curl -m 10 https://ping.alertbee.io/xc4ab7ab/55$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/55',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);import requests

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/55',
    timeout=10
)require 'open-uri'

open(
    'https://ping.alertbee.io/xc4ab7ab/55',
    :read_timeout=>10
)

Run: Missed Check-in

Missed Check-in conditions are used to ensure that your job is running when it is expected to.

Associated Conditions:

  • No ping received in

For example, say you have a cron job to backup your database that runs once a day at 3 AM. You want to ensure that this cron job is running as expected, so you configure a monitor in AlertBee that will trigger if it doesn't get a ping from the cron job once every 24 hours.

You don't need to tell AlertBee that the job runs at 3 AM because the time it runs is set the first time it checks in. AlertBee will then alert if the elapsed time between now and the most recent check in is more than 24 hours.

# m h dom mon dow    command
*/5 * * * * curl -m 10 https://ping.alertbee.io/xc4ab7ab ; sh my_cron_task.sh$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);

# Do Stuffimport requests

requests.get(
    'https://ping.alertbee.io/xc4ab7ab',
    timeout=10
)

# Do Stuffrequire 'open-uri'

open(
    'https://ping.alertbee.io/xc4ab7ab',
    :read_timeout=>10
)

# Do Stuff

Run: Runtime too Long / Short

The Runtime too Long / Short conditions are used in conjunction with the start and complete endpoints to trigger notifications if your job completes in an abnormal length of time.

Associated Conditions:

  • Completed in less than
  • Completed in more than

For example, say you have a cron job to backup your database and you know that it usually takes this job an hour to run. You could create a monitor in AlertBee for a completed in less than, say, 30 minutes and another for, say, completed in more than 90 minutes.

These monitors would alert you if something went wrong with your backup (ran less than 30 minutes) or if your backups are getting larger than expected (ran more than 90 minutes).

# m h dom mon dow    command
*/5 * * * * curl -m 10 https://ping.alertbee.io/xc4ab7ab/start ; sh my_cron_script && curl -m 10 https://ping.alertbee.io/xc4ab7ab/complete$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/start',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);

# Do Stuff
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/complete',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);import requests

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/start',
    timeout=10
)

# Do Stuff

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/complete',
    timeout=10
)require 'open-uri'

open(
    'https://ping.alertbee.io/xc4ab7ab/start',
    :read_timeout=>10
)

# Do Stuff

open(
    'https://ping.alertbee.io/xc4ab7ab/complete',
    :read_timeout=>10
)

Run: Failed to Start

The Failed to Start condition is used in conjunction with the start endpoint to trigger an alert if a job fails to ping the start endpoint at the expected time.

Associated Conditions:

  • No start event received in

For example, say you have a job that you want to ensure runs at least once every 3 hours. You would create a monitor in AlertBee that will trigger if it has been more than 3 hours since the last start event was received.

# m h dom mon dow    command
*/5 * * * * curl -m 10 https://ping.alertbee.io/xc4ab7ab/start ; sh my_cron_task.sh$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/start',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);

# Do Stuffimport requests

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/start',
    timeout=10
)

# Do Stuffrequire 'open-uri'

open(
    'https://ping.alertbee.io/xc4ab7ab/start',
    :read_timeout=>10
)

# Do Stuff

Run: Failed to Complete

The Failed to Complete condition is used in conjunction with the complete endpoint to trigger an alert if a job fails to ping the complete endpoint at the expected time.

Associated Conditions:

  • No complete event received in

For example, say you have a job that runs at least once every 3 hours and you want to ensure that it is finishing. You would create a monitor in AlertBee that will trigger if it has been more than 3 hours since the last complete event was received.

# m h dom mon dow    command
*/5 * * * * sh my_cront_task.sh && curl -m 10 https://ping.alertbee.io/xc4ab7ab/complete# Do Stuff

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://ping.alertbee.io/xc4ab7ab/complete',
    CURLOPT_TIMEOUT => 10
));

curl_exec($curl);import requests
# Do Stuff

requests.get(
    'https://ping.alertbee.io/xc4ab7ab/complete',
    timeout=10
)require 'open-uri'
# Do Stuff

open(
    'https://ping.alertbee.io/xc4ab7ab/complete',
    :read_timeout=>10
)

Endpoints

Endpoints are the unique URL's available to your monitor. They allow you to ping the endpoint, send values and signal the start / completion / failure of the job associated with your monitor.

Ping Endpoint

The ping endpoint is the base endpoint for a monitor. It is used simply to signal that a job is alive.

Example: https://ping.alertbee.io/xc4ab793

Value Endpoint

The value endpoint is used to send a value to AlertBee to be evaluated. This value can be a number or a string.

Example: https://ping.alertbee.io/xc4ab7ab/55

Start Endpoint

The start endpoint is used to trigger the start of the job associated to a monitor.

Example: https://ping.alertbee.io/xc4ab793/start

Complete Endpoint

The complete endpoint is used to signal the completion of the job associated to a monitor.

Example: https://ping.alertbee.io/xc4ab793/complete

Notification Methods

There are currently 4 notification methods avaiable with more being worked on. The four available notifiation methods are email, SMS, webhook and Slack.

Email

AlertBee currently supports sending failure and resolved notifications via email to a single email address.

SMS

AlertBee currently supports sending failure and resolved notifications via SMS to a single number.

Webhook

Webhook notifications will send an HTTP GET request to your specified webhook url containing a JSON body. If AlertBee does not receive a 2xx response from your webhook endpoint it will try 10 more times at 10 minute intervals before it gives up. The body will contain the following fields:

Attributes

name:
string The name assigned to the monitor.
id:
string The ID of the monitor.
status:
string "resolved" or "failed" depending on the state of the monitor.
occurred:
string The ISO 8601 date and time in UTC that the condition occurred.
failing_conditions:
list A list of the conditions that are failing.
{
    "name": "Database Backup",
    "id": "xc4ab793",
    "status": "failed",
    "occurred": "",
    "failing_conditions": [
        "No start event received in 24 hours"
    ]
}

Errors

There are a few different error responses that you might get when pinging your monitor's endpoint(s). The endpoint returns JSON as well as an appropriate HTTP status code.

Attributes

success:
string Boolean indicating if the request was sucessful.
message:
string A message with details about the error.
202 Accepted - Your ping has been accepted for processing

400 Bad Request - There was something wrong with your request as indicated in the message

500, 502, 503, 504 Server errors

Slack

It only takes a minute to get AlertBee integrated with Slack.

First, Log into the AlertBee Dashboard and click Settings link in the left menu.

Next, click on Integrations at the top of the page. You should see the "Add to Slack" button. Go ahead and click it. This will open up the Slack authorization screen asking if you want to link AlertBee to your Slack team.

Select the channel you want AlertBee messages to show up in and press "Authorize". This will direct you back to the AlertBee dashboad and show the message "Slack integration successful." at the top.

Now you can configure any of your monitors to send notifications to Slack by checking the "Send notifications to the "#[your-channel-name]" Slack channel." checkbox when creating a new alert or modifying an existing alert.

If you have any questions or problems, send an email to [email protected] and we will be happy to help!