Heartbeat

Heartbeat monitoring sends periodic HTTP pings to Better Stack. If pings stop arriving within the expected interval, Better Stack marks your service as down and sends alerts through your configured channels (email, Slack, Discord, etc.).

Better Stack setup

Plugin configuration

Add the heartbeat URL to your plugin config:

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id'
	}
}

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id'
	}
}

Options

Custom interval

The default interval is 5 seconds (5000ms). Adjust it to match your Better Stack monitor settings:

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id',
		interval: 30_000 // 30 seconds
	}
}

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id',
		interval: 30_000 // 30 seconds
	}
}

Debug mode

Enable debug to log each heartbeat ping. This is useful for verifying your setup:

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id',
		debug: true
	}
}

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id',
		debug: true
	}
}

Each ping logs a message like Sending heartbeat... 2025-10-27T12:00:00.000Z. Turn this off once you've confirmed the setup — it generates a log entry every interval.

How it works

The plugin starts a setInterval timer during the start lifecycle hook (src/robo/start.ts). Each tick sends a fetch request to the heartbeat URL. The response is ignored — only the request matters.

If a fetch fails (network error, DNS issue, etc.), the error is logged at debug level and the interval keeps running. Transient failures don't stop the heartbeat system.

When the Robo stops or restarts, the interval is cleared to prevent memory leaks.

Heartbeat only

You can use heartbeat monitoring without log integration. Just omit sourceToken:

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id'
	}
}

export default {
	heartbeat: {
		url: 'https://uptime.betterstack.com/api/v1/heartbeat/your-heartbeat-id'
	}
}

Troubleshooting

• Monitor shows as down — Verify the heartbeat.url is correct and your Robo has internet access. Enable debug: true to confirm pings are being sent.
• False alerts during restarts — The heartbeat stops during Robo restarts. If your restart time exceeds the expected interval in Better Stack, the monitor triggers. Increase the expected interval in Better Stack to account for restart time.
• Too many log entries — Disable debug mode. When enabled with a short interval, it generates a log line every few seconds.

Next Steps