Cronbee Documentation

1. Introduction

1.1 Getting started with Cronbee

Cronbee is a very simple, yet powerful way to monitor jobs running on remote devices.

It helps individuals and teams monitor the status of tasks and processes that might otherwise exist in a black box.

You can integrate Cronbee into your shell scripts, crontabs, take advantage of our CLI package for Debian, or call the API from some popular platforms: PHP, Java, Node .

1.2 Core Concept

A Cronbee monitor is at its core an event listener and notification dispatcher.

When you create a monitor, you set the listener to expect a periodic event signal. If the signal is not received, or does not arrive within configured limits, then notifications are created and sent to communications channels to alert team members of an issue. For more information about use cases, see the F.A.Q.

1.3 Simple Ping vs Workflow monitoring

Cronbee is capable of two modes of operation, suitable for many use cases.

1.3.1 Simple

The simplest form of a Cronbee monitor is to be used as a 'ping' listener, a kind of watchdog.

This means sending an event every time an event starts or finishes. Cronbee will simply display the event in your dashboard, or generate an notification if it didn't.

1.3.2 Advanced

A more advanced way to use cronbee is to signal an arbitrary number of events which are captured by the cronbee API and can be shown in your dashboard. This means that even the most complex of multi-stage tasks can be granularly monitored and measured, and any problematic or long-running stages can be identified.

1.4 Installation

Cronbee is a SaaS platform, so there is no software to install (unless you use the Cronbee CLI). However, there are two essential requirements for use:

An account on cronbee.com
A way to send HTTP requests to the cronbee API (usually from a server or some other remote device)

1.5 Quick start

Each monitor is identified by a unique ID. You can copy the ID by hovering over the monitor name and clicking the copy icon in the UI.

1.5.1 Cronbee API

The cronbee api is always available at https://api.cronbee.com and all monitor related operations should be sent to https://api.cronbee.com/monitor/

1.5.2 Make a request

Using curl, you can ping your monitor (after replacing the ID with your own monitor ID)

# Ping a monitor
curl -fsS --retry 3 https://api.cronbee.com/monitor/43d483a8-6487-4428-82ec-5199d23ba22a/ping

You should see your monitor update in the UI:

ping result

2. Setup guide

Setting up a Cronbee monitor can be incredibly fast. We'll use CURL in our examples to make calls to the Cronbee API.

In all cases you'll need to configure your monitor on the cronbee.com web app.

2.1 Configure a monitor

Sign up for an account at cronbee.com
After signing up and activating your account, you'll see the web app for the first time. Here there's a monitor already created. It's just turned off.
Click the cog icon to open up the monitors settings
Here you can edit several different settings on your monitor including. See monitor settings for an explanation:

It's a good idea to enable your monitor at this point

2.1.1 Monitor Settings Explained

2.1.1.1 Monitor tags and name

These are for organisational purposes and have no impact on the performance of your monitor. You can filter your monitors by their tags in the panel on the left.

2.1.1.2 Expected execution cycle

You should configure your monitor to match the same frequency of execution as your server job or task. Cronbee provides two ways of configuring a monitor: preconfigured or custom cronstring.

2.1.1.2.1 Preconfigured cycles

The simple cycle selector uses pre-configured logical time increments for you to select, from every minute to once every week.

2.1.1.2.2 Custom cron strings

Of course, the Cronbee team recognise that not everyone's tasks will fall into convenient buckets. That's why we provide a way to specify your own custom cron strings.

You can access these settings by selecting the 'cron' button in the selector menu:

cronstring selector

As you write your cronstring, Cronbee will helpfully show you the resulting schedule at the top of the monitor pane, so you can validate your custom cycle:

cronstring config

2.1.1.3 Execution grace period

You can configure a grace period for your monitor. This is a set time in which no alerts will be generated, even if the tasks fails to send a ping or start event signal.

There are many reasons you might find this useful, such as for long running jobs (and you only send an event after it's complete).

2.1.1.4 Server timezone settings

Almost all servers in the world use UTC by default, but for whatever reason your server is using a localised timezone, you can configure it here. This allows Cronbee monitors to function correctly with non-standard server time configurations.

2.2 Basic monitor use

The easiest way to integrate Cronbee and monitor your tasks is part of a shell script. You should have your unique monitor ID ready.

Here we'll use cronbee to say a job started using CURL

# Ping a monitor
curl -fsS --retry 3 https://api.cronbee.com/monitor/43d483a8-6487-4428-82ec-5199d23ba22a/ping && [your job command or script]

You should see your monitor update in the UI:

ping result

2.3 Advanced event monitoring

What if you have a multi-stage workflow, and you'd like to monitor each part of that? Maybe you're making a database backup and then copying it to a cloud object store?

Cronbee really shines here, with its ability to build dynamic workflows and display the status and notify your team when things go wrong.

The secret here is the use of a single task-instance identifier token. If you make a call to a Cronbee monitor API endpoint, but omit the /ping path, you'll start the workflow tracking (a start) event, but you'll also receive back a single instance token.
Further calls to the API should append the /event/[eventname] path and parameter, signifying with event stage is starting

Here's a worked example:


# Get a token and start the workflow
TOKEN=`curl -fsS --retry 3 "https://api.cronbee.com/monitor/43d483a8-6487-4428-82ec-5199d23ba22a"`

# --- script boot ---

curl -fsS --retry 3 "https://api.cronbee.com/monitor/43d483a8-6487-4428-82ec-5199d23ba22a/event/backup?token=$TOKEN"

# --- backup script ---

curl -fsS --retry 3 "https://api.cronbee.com/monitor/43d483a8-6487-4428-82ec-5199d23ba22a/event/sync?token=$TOKEN"

# --- sync script ---

curl -fsS --retry 3 "https://api.cronbee.com/monitor/43d483a8-6487-4428-82ec-5199d23ba22a/event/stop?token=$TOKEN"

You'll be able to see the results of running your monitoring pipeline in the Cronbee web app advanced results