Getting Started with Heartbeats

Overview

This guide introduces AppStatus Heartbeats and covers:

• Heartbeat creation with unique ping endpoint
• Status lifecycle: waiting → healthy → late → missing
• Grace period configuration to prevent false positives
• Dashboard with stats, ping volume charts, and status distribution
• Integration with cron jobs, Kubernetes CronJobs, CI/CD pipelines
• Incident and alert automation on missed heartbeats

What are AppStatus Heartbeats?

Heartbeats supervise recurring workloads — cron jobs, ETL pipelines, backup scripts, deployment tasks — and produce actionable events when expected execution windows are missed. Each heartbeat generates a unique, public ping endpoint that your job calls on successful completion. If the ping is not received within the expected interval plus grace period, the heartbeat transitions through late → missing states and triggers incidents and alerts.

The system uses a simple contract: your job calls the ping URL after successful completion, and AppStatus monitors the timing. If your job fails, crashes, or takes too long, the ping is never sent, and AppStatus detects the absence. This dead-man's-switch pattern requires no agent installation and works with any scheduler, language, or platform.

Key capabilities:

• Unique ping endpoint per heartbeat (no authentication required)
• Auto-generated unique key: hb_{slug}_{random}, max 32 characters
• Interval presets: 1min, 5min, 15min, 30min, 1h, 6h, 12h, 24h, 7d
• Grace period presets: 1min, 2min, 5min, 10min, 15min, 30min
• Status transitions: waiting → healthy → late → missing
• Late count tracking per heartbeat
• Ping history with source IP and user agent
• Dashboard: total, healthy, late, missing counts with charts
• Ping volume chart (24-hour hourly breakdown)
• Status distribution pie chart
• Auto-refresh every 30 seconds
• TimescaleDB hypertable for ping history (optimized time-series storage)
• Detail drawer with raw pings and daily summaries

Heartbeat Workflows

Each workflow maps to real AppStatus features and API endpoints used in the main app.

Troubleshooting

Operational Guidance

• Tune grace windows to avoid false alarms from normal variance.
• Track repeated late jobs as optimization work items.
• Document manual recovery flow for critical pipelines.

Step-by-Step Setup

A heartbeat is a dead-man's-switch monitor for scheduled work — cron jobs, backups, pipelines, data syncs. Instead of AppStatus checking your job, your job tells AppStatus "I just ran successfully" by hitting a unique URL. If AppStatus does not hear from the job within the expected window, it opens an incident. This catches the silent failure mode that uptime monitors cannot.

1. 1

   Open Heartbeats from the sidebar

   The list shows every heartbeat in the workspace and its current status (Waiting / Healthy / Late / Missing). You can filter by status to find what needs attention.

   WhereSidebar → Heartbeats
2. 2

   Click "+ Create heartbeat"

   Give the heartbeat a clear name that matches the job it represents (e.g. "Nightly database backup"). Future-you will see this name on every alert — make it specific.

   WhereHeartbeats → + Create heartbeat → Name
3. 3

   Set the expected interval

   Pick how often the job is supposed to run. AppStatus uses this to know when the next ping should arrive — and when it should worry. Match the actual cron schedule exactly (e.g. for a job that runs every 6 hours, pick 6 hours).

   WhereForm → Expected interval
4. 4

   Set the grace period

   The grace period is how late the job can be before AppStatus calls it a problem. A 10-minute grace on a daily backup means you only get paged if the backup is 10 minutes late — not the second it misses the exact minute.

   WhereForm → Grace period

   Tip

   Set the grace period based on the job's real-world variance. Slow batch jobs may need 30–60 minutes; precise cron jobs can use 1–5 minutes.

5. 5

   Save and copy the ping URL

   After saving, the heartbeat detail page shows the unique ping URL. It contains a random key — treat this URL like a secret, because anyone who has it can mark the heartbeat as healthy. The "Copy" button puts it on your clipboard.

   WhereHeartbeat detail → Ping URL → Copy
6. 6

   Add the ping to your job

   In your job script or cron entry, add a call to the ping URL after the actual work succeeds. The "Setup snippets" tab on the heartbeat detail page shows ready-to-paste examples for cron, Kubernetes CronJob, GitHub Actions, Python, Node.js and shell scripts — pick the one that matches your stack.

   WhereHeartbeat detail → Setup snippets tab

   Tip

   Always chain the ping after the real work (using && in shell) so a failed job does NOT send a success ping.

7. 7

   Run the job once and watch the status flip to Healthy

   After the first successful ping, the heartbeat status changes from Waiting to Healthy in the dashboard within a few seconds. The detail page shows the timestamp of the last ping.

   WhereHeartbeat detail → Status indicator
8. 8

   Wire the heartbeat into an alert rule

   Open the Alerts → Rules page and create a rule scoped to this heartbeat with condition "Heartbeat missing". Attach the channels you want to be paged on. Now missed pings open incidents and notify on-call automatically.

   WhereAlerts → Rules → + New rule → Scope: this heartbeat → Condition: Heartbeat missing

Configuration Options

Every option you can set, what each choice means, and what to pick. Use this as a reference while you fill in the form.

Feature Reference

Every feature, where to find it in the app, and what it does. Use this when you know what you want to do but not where it lives.

Next Steps

Continue building your monitoring stack: