> ## Documentation Index
> Fetch the complete documentation index at: https://checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating A Heartbeat Monitor
> Step-by-step guide to set up your first heartbeat monitor in Checkly. Learn about configuration, timing, alerts, and best practices.
Learn more about all the [Heartbeat Monitor capabilities](/detect/uptime-monitoring/heartbeat-monitors/overview) in the general overview.
Follow this comprehensive guide to create your first heartbeat monitor in Checkly. We'll walk through each configuration step and explain the best practices to ensure your monitoring is effective.
Before creating your heartbeat monitor, make sure you have:
* A Checkly account with Team or Enterprise plan
* A scheduled job, script, or automated process you want to monitor
* Access to modify the code/script that runs your task
## Step 1: Basic Configuration
Start by giving your monitor a descriptive name and relevant tags and description. Choose something descriptive that clearly identifies what the monitor is tracking, like "Nightly Database Backup" or "Weekly Reports Job".
Use tags to group related monitors and make them easier to find and manage.
## Step 2: Timing Configuration
The timing configuration is the heart of your heartbeat monitor. You need to specify when you expect pings and how much flexibility to allow.
### Period Setting
The **period** defines how often your task should ping Checkly:
* **Daily jobs**: Set to 1 day
* **Weekly jobs**: Set to 7 days
* **Hourly jobs**: Set to 1 hour
### Grace Period
The **grace period** provides extra time before alerting, compensating for natural variance in job execution times:
**Common grace period examples:**
* **Daily backup at 2 AM** with 30-minute grace → Alert if no ping by 2:30 AM
* **Weekly report on Fridays** with 4-hour grace → Alert if no ping by end of Friday
* **Hourly sync job** with 5-minute grace → Alert if ping is more than 5 minutes late
Grace periods compensate for natural variance in job execution times. For example:
* **Daily backup at 2 AM** with 30-minute grace → Alert if no ping by 2:30 AM
* **Weekly report on Fridays** with 4-hour grace → Alert if no ping by end of Friday
* **Hourly sync job** with 5-minute grace → Alert if ping is more than 5 minutes late
Choose grace periods based on:
* Normal variance in your job execution time
* Acceptable delay before you need to know about failures
* Time needed for any retries or recovery processes
The heartbeat timer works predictably:
* **First ping starts the timer** - When you send the first ping, monitoring begins
* **Each ping resets the timer** - Every successful ping resets the countdown
* **Alerts also reset the timer** - After an alert fires, the timer restarts
* **Deactivation resets everything** - Pausing and resuming a monitor restarts timing
This means if your job is supposed to run every 6 hours but runs late at hour 7, the next ping will be expected at hour 13 (7 + 6), not hour 12.
**Consider Your Job Variance**
* How much does your job's runtime vary?
* Account for network delays and system load
* Include time for any retry logic
**Balance Speed vs. False Alerts**
* Too short: False alerts during normal delays
* Too long: Slower failure detection
* Start conservative, adjust based on experience
## Step 3: Alert Configuration
Connect your heartbeat monitor to [alert channels](/communicate/alerts/) to be notified when pings are missing.
### Choosing Alert Channels
**For immediate awareness:**
* **Email notifications** - Good for individual monitoring
* **Slack or Teams** - Great for team coordination and visibility
**For critical production jobs:**
* **PagerDuty** - Escalation and on-call management
* **Webhooks** - Custom integrations with your systems
**For different severity levels:**
* **Low priority**: Email only
* **Medium priority**: Slack + Email
* **High priority**: PagerDuty + Slack + Email
### Alert Timing
Configure when alerts should fire:
* **Immediate**: Alert as soon as grace period expires
* **Delayed**: Wait for multiple missed pings before alerting
* **Escalation**: Start with email, escalate to PagerDuty after delays
## Step 4: Ping URL and Implementation
Once created, your heartbeat monitor provides a unique ping URL. Your tasks should make an HTTP `GET` or `POST` request to this URL when they complete successfully.
## Step 5: Testing Your Setup
Before deploying to production, test your heartbeat monitor:
### Manual Testing
You can manually send pings through the Checkly interface to:
* Test your monitor setup before deployment
* Start the timer for a newly created monitor
* Reset alerts during maintenance windows
* Verify alert configurations are working
Manual pings are available both on the monitor detail page and in the quick actions menu from your monitors list.
You can also send manual pings directly from your monitors list using the quick actions menu:
## Common Configuration Patterns
```typescript theme={null}
import { HeartbeatMonitor } from 'checkly/constructs'
new HeartbeatMonitor('daily-backup-monitor', {
name: 'Daily Database Backup',
period: 24,
periodUnit: 'hours',
grace: 30,
graceUnit: 'minutes',
tags: ['backup', 'database', 'daily', 'production']
})
```
```typescript theme={null}
import { HeartbeatMonitor } from 'checkly/constructs'
new HeartbeatMonitor('weekly-report-monitor', {
name: 'Weekly Analytics Report',
period: 7,
periodUnit: 'days',
grace: 4,
graceUnit: 'hours',
tags: ['reports', 'analytics', 'weekly', 'marketing']
})
```
```typescript theme={null}
import { HeartbeatMonitor } from 'checkly/constructs'
new HeartbeatMonitor('hourly-sync-monitor', {
name: 'Hourly Customer Data Sync',
period: 1,
periodUnit: 'hours',
grace: 10,
graceUnit: 'minutes',
tags: ['sync', 'data', 'hourly', 'critical']
})
```
## Best Practices for Pings
**Always include timeout and retry options:**
```bash theme={null}
# Good: With timeout and retries
curl -m 5 --retry 3 https://ping.checklyhq.com/your-id
# Bad: No timeout or retry protection
curl https://ping.checklyhq.com/your-id
```
**Position pings correctly in your code:**
```python theme={null}
# Good: Ping only after success
try:
run_backup()
upload_to_s3()
# Only ping if everything succeeded
requests.get(ping_url, timeout=5)
except Exception as e:
# Don't ping on failure - let heartbeat alert
log_error(e)
```
**Use source headers for tracking:**
```bash theme={null}
curl -H "Origin: backup-server-01" https://ping.checklyhq.com/your-id
```