Docs

Appearance

Heartbeat Monitoring ​

Overview ​

Pingniner offers a simple and reliable way to monitor your scheduled tasks. This can be easily integrated with cronjobs, inside shell scripts, or directly into your app. This helps you ensure that your scheduled tasks run smoothly and on time. Here’s how you can set it up and use it effectively:

Adding a Heartbeat Monitor ​

  1. Sign in to your Pingniner account.
  2. Navigate to Heartbeats (main menu) and click on "Add Heartbeat Monitor".
  3. Fill in the details: Set a friendly name, fill in the scheduled task frequency, expressed in minutes and the allowed grace time, also in minutes. Optionally, you can attach the monitor to a group, add some tags or notes.
  4. Integrate Our system will generate a unique ping URL which you can integrate into your systems.

INFO

Grace time defines how much time should we allow for a ping to be received before an alert is sent. For example, for a heartbeat with a 5-minute frequency and a 3-minute grace time, if a ping is not received in 8 minutes, an alert will be created.

Integrating the Ping URL ​

Here are some examples on how you can integrate heartbeat monitoring into your systems.

Cronjobs ​

sh
* * * * * echo "Hello World" && curl -fsS -m 10 --retry 5 -o /dev/null https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

* * * * * echo "Hello World" - is your actual cronjob
&& curl -fsS -m... - is simply appended to your existing cron job

PHP (Generic) ​

php
@file_get_contents("https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID");

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

TIP

Make sure your script stops executing on error or that some kind of logic is added so that the request isn't made even if the script/job failed.

PHP (Laravel) ​

In Laravel you can use thenPing() in your scheduler. Add ->thenPing('https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID') to any command that you wish to monitor.

Where the scheduler lives depends on your Laravel version.

php
// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune')
    ->daily()
    ->thenPing('https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID');
php
// app/Console/Kernel.php
class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule): void
    {
        $schedule->command('telescope:prune')
            ->daily()
            ->thenPing('https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID');
    }
}

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

INFO

Laravel takes care of execution logic and runs thenPing() only on success. Use pingOnSuccess() and pingOnFailure() if you want to route the two outcomes to different heartbeat monitors.

Python ​

In Python you can use the requests library to make a Ping to our API.

python
import requests
requests.get("https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID")

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

TIP

Make sure your script stops executing on error or that some kind of logic is added so that the request isn't made even if the script/job failed.

Ruby ​

In Ruby you can use net/http library to make a Ping to our API.

ruby
require 'net/http'
require 'uri'
Net::HTTP.get(URI.parse('https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID'))

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

TIP

Make sure your script stops executing on error or that some kind of logic is added so that the request isn't made even if the script/job failed.

NodeJS ​

In NodeJS you can use the built-in functions from https to make a Ping to our API.

javascript
var https = require('https');
https.get("https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID");

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

TIP

Make sure your script stops executing on error or that some kind of logic is added so that the request isn't made even if the script/job failed.

Perl ​

In Perl you can use the LWP::Simple library to make a Ping to our API.

perl
use LWP::Simple;
get("https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID");

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

TIP

Make sure your script stops executing on error or that some kind of logic is added so that the request isn't made even if the script/job failed.

Bash (shell scripts) ​

Using cUrl

sh
curl --retry 3  https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID

Using Wget

sh
wget -O /dev/null  https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID

Replace YOUR_HEARTBEAT_ID with the ID of your monitor.

Providing runtime, memory and message ​

You can optionally provide runtime, memory usage, and a message in the heartbeat URL as GET parameters.

https://ingest.pingniner.com/api/heartbeat/YOUR_HEARTBEAT_ID?runtime=100&memory=100&message=Hello+World
  • runtime - numeric
  • memory - numeric
  • message - URL encoded string

You can choose to pass along just one of these items or all of them at once, all are optional.

TIP

Sending runtime and/or memory will automatically activate the performance graphs on the heartbeat monitor dashboard.

Viewing & Managing Heartbeat Monitors ​

To view or manage a heartbeat monitor, click on Heartbeats (main menu) and then click on the desired heartbeat monitor.

Overview ​

The overview dashboard offers a bird's-eye view of the heartbeat monitor with:

  • Real-time status
  • Runtime graph (if runtime is reported)
  • Memory graph (if memory is reported)
  • Uptime
  • Tips on how to integrate

Edit ​

This section can be used to update the monitor's details. All details can be updated if required, including the frequency and grace time.

History ​

Here you can check and export the historical data of received pings.

Runtime, Memory and message are available here, if reported, for each received ping.

INFO

Historical data is available for the last 30 days for subscribed accounts and 1 day for free accounts.

Triggers ​

In this tab, you can manage the active checks and triggers for the current monitor.

For heartbeat monitors, the following triggers are available:

  • Grace Time Exceeded: This trigger is active by default and is used to fire an alert if a ping is not received in the allowed time frame.
  • Runtime: If you are reporting runtime you can activate this trigger to receive an alert if the reported runtime exceeds your threshold. Inactive by default, with a threshold of 60.
  • Memory: If you are reporting memory you can activate this trigger to receive an alert if the reported memory exceeds your threshold. Inactive by default, with a threshold of 600.

INFO

While updating a trigger, you can set the contacts that get notified, the threshold value (where applicable), and the sensitivity (occurrences) of the trigger.

TIP

Grace Time Exceeded has no occurrences setting. A missed ping is already conclusive — the grace time is what absorbs a job that runs a little late, so there is nothing further to tune there.

Runtime and Memory do use occurrences, defaulting to 3. Raise it if a single slow run is not worth an alert.

Maintenance ​

Heartbeat monitors support maintenance periods. Schedule one when you know a job will not run — during a deployment freeze, for example — and no alert is raised for the missed pings.

See Triggers & Incidents for how occurrences, impact and repeating notifications work across all monitor types.

Monitoring done right.

Copyright © Pingniner