Heartbeats¶

Argus also supports passive monitoring with the concept of Heartbeats. Other than traditional active monitoring with monitors, heartbeats are a special kind of monitor that expect a HTTP request to be sent in a configurable interval. If the request isn't being received, the monitor is considered down, like a dead man switch.

Use Cases¶

Every task that is periodically executed can be monitored with heartbeats. Think of backups that are running regularly (e.g. once a day) or scheduled tasks (cronjobs) that are executed more frequently, such as every minute.

Configuring heartbeats for these kind of tasks is very simple and only trigger a notification, if the job isn't being executed anymore.

Interval¶

When configuring a heartbeat monitor, you need to specify two fields, an interval and a margin.

The interval is the expected time between two heartbeats. To make it easy for you to configure the interval, you should set it to the exact time you expect to be between two recurring tasks.

The margin is the time that will be added to the interval to make sure to account for any smaller delays due to processing or inaccuracies when executing cron jobs (e.g. when using systemd Timers). The margin is provided in percent and will be added to the interval for our calculations. We recommend to set the margin to at least 10% to have as less false positives as possible.

Heartbeat URL¶

When creating a new heartbeat monitor, you'll get a URL that you can integrate into your recurring task to let Argus know that the task is still being executed on the expected schedule. The URL is publicly reachable from the internet and depending on your setup, there are various ways to integrate it into your task.

The URL has the following format:

https://argus.rescaled.com/heartbeat/{monitor}/{token}

You can dispatch the request with any HTTP method. The token is used to identify you as the correct sender of the request. If you don't want the monitor and token variable to be part of the URL, you can also provide them as header like this.

https://argus.rescaled.com/heartbeat

X-Argus-Monitor: {monitor}
X-Argus-Token: {token}

This can again be done with any HTTP method.

Integration Examples¶

In the following sections, we'll show you how to integrate heartbeats into your existing tasks, applications and infrastructure to give you a better overview of how Argus can be used in your environment.

Linux Crontab¶

The easiest way to integrate heartbeats into an existing Linux cronjob is to use the curl command to send a request to the heartbeat URL, but only if the preceding command was successful.

*/5 * * * * /my/cronjob/script && curl -sSf https://argus.rescaled.com/heartbeat/{monitor}/{token}

Using && makes sure that the heartbeat request is only sent if the preceding command was successful. If the preceding command exits with a non-zero exit code, the heartbeat request will not be sent, thereby triggering a notification once the expected heartbeat interval passes.