Introducing Heartbeats

What are heartbeats?

Heartbeats let you monitor applications which are behind firewalls or are not accessible via the internet.

With a heartbeat you send periodic heartbeats (read GET or POST request) to a specified endpoint. If a specified amount of time passes without receiving a heartbeat from your application, we will send out a notification letting you know.

This is often used to monitor cronjobs or is placed at the end of periodic tasks to ensure they are running with the desired frequency.

You are also able to send custom data to the heartbeat endpoint which we will graph out for you over time.

How can I send a heartbeat?

Requests should be JSON formatted and contain a flat JSON dictionary passed in the ‘data’ attribute.

{"data": <<FLAT_JSON_DICTIONARY>>}

As a practical example, in Python 3 you can achieve this with the requests package

import requests

# A vanilla heartbeat
requests.post(
    'https://heartbeat.uptimetoolbox.com/my-unique-url/',
    timeout=(3.05, 4)
)

# A heartbeat with a custom metric
requests.post(
    'https://heartbeat.uptimetoolbox.com/my-unique-url/',
    json={"data": {"custom_field": 45}},
    timeout=(3.05, 4)
)

On linux systems you can make use of curl or the httpie package

Using httpie

http --timeout=4 POST https://heartbeat.uptimetoolbox.com/my-unique-url/ data:='{"custom_field": 45}'

Best Practices

It’s highly recommend to always include a timeout when making calls to your heartbeat endpoint (or any other internet-based service).

Additionally, as there are many reasons why a single request over the internet can fail, to avoid false positives you should either

• Delay for a few seconds and retry if the first request fails
• Set an expected delay following the formula (frequency_of_function + time_for_function_to_run) * 2

In practice, our heartbeat service is most useful for applications with a run frequency between 1 minute and 8 hours.