Sign In

Heartbeat Monitoring

Heartbeat monitors work inversely to HTTP monitors. Instead of Upstat checking your endpoint, your systems send periodic pings to Upstat. If a ping doesn’t arrive within the expected window, the monitor fails and triggers alerts.

When to Use Heartbeats

Heartbeats are designed for processes that run on a schedule:

Cron jobs - Database backups, log rotation, cleanup tasks Scheduled tasks - Report generation, data syncs, batch processing Background workers - Queue processors, email senders, import jobs Health checks - Self-reporting from internal services

Any process that should run regularly can send a heartbeat to confirm successful completion.

How Heartbeats Work

Each heartbeat monitor has a unique URL:

Your process sends an HTTP request to this URL after completing its work. Upstat tracks when pings arrive and alerts you if one is missed.

Success and Failure

A heartbeat is successful when a ping arrives within the expected interval plus grace period.

A heartbeat fails when no ping arrives within that window. The monitor status changes to failed and configured alerts trigger.

Example Timeline

For a heartbeat with a 5-minute interval and 2.5-minute grace period:

  1. 12:00 - Ping received, status: success
  2. 12:05 - Ping received, status: success
  3. 12:10 - No ping received
  4. 12:12:30 - Grace period expires, status: fail, alerts trigger
  5. 12:15 - Ping received, status: success, recovery alerts sent

Key Settings

Expected Interval

How often your process should send a ping. Available intervals:

Interval Use Case
30 seconds High-frequency health checks
1-5 minutes Queue workers, real-time syncs
15-30 minutes Regular background jobs
1-4 hours Hourly batch processes
6-24 hours Daily scheduled tasks

Choose an interval that matches your process schedule. A cron job running every hour should have a 1-hour interval.

Grace Period

Additional time allowed before marking a heartbeat as failed. By default, Upstat calculates this as 50% of the expected interval.

Grace periods accommodate:

  • Variable execution times
  • Network delays
  • Clock drift between systems

For a 5-minute interval, the default 2.5-minute grace period means the total window is 7.5 minutes.

Dashboard Metrics

The heartbeat detail page shows:

Metric Description
Status Current state (success or fail)
Uptime/Downtime Duration in current state
Last Heartbeat Time since most recent ping
Consecutive Failures Count of missed pings in a row
Grace Period Configured additional time window
Success Rate Percentage of pings received on time

Charts

Success Rate Bar Chart - Visual timeline showing received vs missed pings. Green indicates all pings received, yellow indicates partial success, red indicates all pings missed.

Success Rate Trend - Line chart showing success percentage over time. Useful for spotting degradation patterns.

Received vs Missed - Comparison chart showing ping counts over time.

Integration Patterns

Simple Ping

Add a curl command at the end of your script:

Conditional Ping

Only send heartbeats on successful completion:

Application Integration

Call the heartbeat URL from your application code:

Heartbeats vs HTTP Monitors

Aspect Heartbeat HTTP Monitor
Direction Your system pings Upstat Upstat checks your endpoint
Best for Scheduled processes Always-on services
Failure detection Missed ping Failed health check
Check frequency Defined by your process Configured in Upstat

Use heartbeats when your process initiates the check. Use HTTP monitors when you need external verification that a service responds correctly.