Heartbeat Checks

Created on 24 November, 2024 • Docs • 207 views • 3 minutes read

Heartbeat checks ensure that your scheduled or automated tasks, such as cron jobs or application scripts, run as expected.

By monitoring the execution of these tasks, you can quickly identify failures, prevent downtime, and maintain system reliability.

Why Heartbeat Checks Are Important

Key Benefits:

Automation Monitoring:

  1. Ensures that cron jobs or scripts execute at the expected intervals.
  2. Identifies issues with skipped, delayed, or failed tasks.

Proactive Issue Detection:

  1. Alerts you before users notice problems caused by missing or failed tasks.

Improved System Reliability:

  1. Helps maintain operational consistency by catching silent failures in automation.

Integration Flexibility:

  1. Easily integrate with cron jobs, server tasks, or custom codebases.

How Heartbeat Checks Work in Pingtr

Set Up a Heartbeat URL:

  1. Pingtr generates a unique URL for each heartbeat check. For example:
https://pingtr.com/webhook-heartbeat/76240afd8be9904f4a0511e2d35109b2

Define Monitoring Rules:

  1. Expect a Heartbeat Every: Set the expected interval (e.g., every 10 minutes or every hour).
  2. Grace Period: Specify the approximate time your task takes to execute. This gives the task leeway before raising an alert.

Trigger Alerts:

  1. If Pingtr doesn't receive a ping within the defined period (including grace time), it raises an alert through your configured notification channels (e.g., email, Slack).

Setting Up a Heartbeat Check

Create a New Heartbeat Check:

  1. Visit the Pingtr Heartbeat Creation Page.
  2. Set the parameters:
  3. Name: Give your heartbeat check a descriptive name (e.g., "Database Backup Cron").
  4. Expect a Heartbeat Every: Define how frequently the task should run (e.g., 1 hour).
  5. Grace Period: Approximate the task’s execution time (e.g., 5 minutes).

Save and Retrieve the Heartbeat URL:

  1. Pingtr will provide a unique URL that you’ll use to send pings:
https://pingtr.com/webhook-heartbeat/76240afd8be9904f4a0511e2d35109b2

Integrate the Heartbeat URL with Your Task:

  1. Add a command to your cron job or script to ping the URL whenever it runs.

Example Use Cases

1. Monitoring Cron Jobs

Cron jobs are essential for running scheduled tasks, such as database backups, report generation, or cache clearing. A heartbeat check ensures these jobs execute as expected.

Example Cron Job:

A cron job to ping the heartbeat URL after completing a backup:

0 * * * * /usr/bin/backup-database && curl -fsS --retry 3 https://pingtr.com/webhook-heartbeat/76240afd8be9904f4a0511e2d35109b2 > /dev/null

Explanation:

  1. The cron job runs every hour (0 * * * *).
  2. After completing the backup (/usr/bin/backup-database), it sends a ping to the Pingtr URL.

2. Monitoring a Codebase Integration

Heartbeat checks can be integrated into application code to monitor the execution of specific tasks, such as data synchronization or API calls.

Example Python Integration:

import requests

def sync_data():
try:
# Perform the task
print("Data synchronization started...")
# Simulate task execution
# sync_data_logic_here()

# Send a heartbeat ping
heartbeat_url = "https://pingtr.com/webhook-heartbeat/76240afd8be9904f4a0511e2d35109b2"
requests.get(heartbeat_url)
print("Heartbeat sent successfully!")

except Exception as e:
print(f"Error during task: {e}")

# Run the function
sync_data()
  1. Explanation:
  2. After completing the sync_data function, the script sends a ping to the Pingtr heartbeat URL.
  3. If the script fails to execute or is delayed, Pingtr will raise an alert.

3. Monitoring Website Maintenance Scripts

A maintenance script runs nightly to clean up logs and temporary files. Integrating a heartbeat ping ensures the task completes successfully.

Example Shell Script:

#!/bin/bash

# Perform the maintenance task
echo "Starting maintenance..."
rm -rf /tmp/*

# Send a heartbeat ping
curl -fsS --retry 3 https://pingtr.com/webhook-heartbeat/76240afd8be9904f4a0511e2d35109b2 > /dev/null
echo "Maintenance completed and heartbeat sent."

Explanation:

  1. After cleaning up temporary files, the script pings the heartbeat URL to confirm execution.

4. Monitoring API Key Refresh Scripts

An automated task refreshes an API key every 24 hours. A heartbeat check ensures the task runs on schedule.

Example Node.js Integration:

const axios = require('axios');

async function refreshApiKey() {
try {
console.log("Refreshing API key...");
// Simulate API key refresh logic
// await refreshKeyLogic();

// Send a heartbeat ping
const heartbeatUrl = "https://pingtr.com/webhook-heartbeat/76240afd8be9904f4a0511e2d35109b2";
await axios.get(heartbeatUrl);
console.log("Heartbeat sent successfully!");
} catch (error) {
console.error("Error refreshing API key:", error);
}
}

// Run the function
refreshApiKey();

Tips for Effective Heartbeat Monitoring

Set Realistic Expectations:

  1. Match the expected interval and grace period to your task's actual schedule and execution time.

Retry Failed Pings:

  1. Use retry logic in case of transient network issues to ensure the ping reaches Pingtr.

Test Regularly:

  1. Simulate task failures to verify that Pingtr alerts are working as expected.

Combine with Alerts:

  1. Use Pingtr’s notification system (e.g., Slack, email) to receive instant alerts if a heartbeat is missed.

By integrating heartbeat checks into your automated tasks and codebases, you can monitor and maintain the reliability of your systems, ensuring smooth operations and minimizing potential disruptions.