laravel-schedule-monitor-healthchecksio

Send spatie/laravel-schedule-monitor pings to Healthchecks.io instead of Oh Dear. Works with the hosted service and with self-hosted instances.

How it works

When a scheduled task starts, finishes or fails, spatie/laravel-schedule-monitor calls pingOhDear() on the MonitoredScheduledTask model, which dispatches the job class configured in schedule-monitor.oh_dear.ping_oh_dear_job. php artisan healthchecks:install puts this package's PingHealthchecksJob in that config key, so the same log item is sent to Healthchecks instead.

There's no custom model and no migration. The existing ping_url column on monitored_scheduled_tasks stores the Healthchecks ping URL.

Scheduled task event
  → MonitoredScheduledTask::markAsFinished()
    → pingOhDear($logItem)
      → config('schedule-monitor.oh_dear.ping_oh_dear_job')  ← set to PingHealthchecksJob by `healthchecks:install`
        → PingHealthchecksJob
          → POST {ping_url}[/start|/fail]

Requirements

• PHP 8.3+
• Laravel 11, 12 or 13
• spatie/laravel-schedule-monitor 4.1+ (the first version where the ping job class is configurable)

Installation

composer require wfeller/laravel-schedule-monitor-healthchecksio

Then point the schedule monitor at the Healthchecks job:

php artisan healthchecks:install

This publishes config/schedule-monitor.php if you haven't already, and sets 'ping_oh_dear_job' => \WF\ScheduleMonitorHealthchecks\Jobs\PingHealthchecksJob::class in it. Commit the change. If that entry is something other than a plain Foo::class, null or '' (an env() call, for example), the command leaves the file alone and tells you what to set by hand.

healthchecks:sync refuses to run until this is done. Otherwise upstream's PingOhDearJob would send its pings to the Healthchecks URLs, where they'd fail.

Environment

HEALTHCHECKS_API_KEY=your-project-api-key

That's enough for the hosted service: the API URL defaults to https://healthchecks.io, and each check's ping URL comes from the API response (https://hc-ping.com/<uuid>).

For a self-hosted instance:

HEALTHCHECKS_API_KEY=your-project-api-key
HEALTHCHECKS_API_URL=https://hc.example.com
HEALTHCHECKS_PING_URL=https://hc.example.com/ping

Leave OH_DEAR_MONITOR_ID unset. When it's set, schedule-monitor:sync registers the tasks at Oh Dear and overwrites ping_url with Oh Dear URLs.

Start signals are optional. Turn them on to get execution times and to be alerted when a job runs longer than its grace time:

OH_DEAR_SEND_STARTING_PING=true

Config

Publishing the config is optional:

php artisan vendor:publish --tag="schedule-monitor-healthchecks-config"

Usage

Deploy

php artisan schedule-monitor:sync   # upstream: store the schedule in the database
php artisan healthchecks:sync       # upsert a check per task, store its ping URL

Run both on every deploy, in that order. healthchecks:sync upserts a check for each monitored task (matched on name and tag) and writes the ping URL to monitored_scheduled_tasks.ping_url. It exits non-zero if any task failed to sync. Without an API key it prints a warning and exits successfully, so local and CI environments don't need one.

Checks that carry the configured tag but whose name is no longer in the schedule are deleted. Pass --keep-old to skip that:

php artisan healthchecks:sync --keep-old

If several apps or environments share one Healthchecks project (staging and production, say), give each its own HEALTHCHECKS_TAG. Otherwise they share checks for tasks with the same name, and each sync deletes the others' checks. A separate Healthchecks project per app/environment avoids the question entirely.

The sync owns each check's tags, grace time, schedule and (unless channels is null) integrations, and overwrites them on every run. Don't add tags to synced checks by hand: the check would no longer match on name + tag, and the next sync would create a duplicate.

Excluding tasks

$schedule->command('reports:generate')->daily()->doNotMonitorAtHealthchecks();

doNotMonitorAtHealthchecks() is an alias for doNotMonitorAtOhDear(); they set the same flag.

What gets sent

Output is only included for tasks using upstream's storeOutputInDb(). Healthchecks stores the first 100 kB of each body.

Pings that reach the job after a newer run's events (queue reordering, retries) are dropped:

• a start ping, if the task has since logged a finish or failure. It would leave the check "started" and set off a false alert once the grace time ran out.
• a success ping, if the task has since logged a start, finish or failure. It would mask a newer failure or close a newer run that is still going.

Failure pings are always sent.

A ping that gets a 4xx response other than 408/429 (for example because the check was deleted in Healthchecks) isn't retried: the job fires HealthchecksPingFailed and is marked failed. Other failures are retried 3 times inside the job, and the queue then retries the job for retry_job_for_minutes.

Limitations

• Check names are task names, and Healthchecks limits names to 100 characters. Longer names fail to sync and are reported by healthchecks:sync.
• No run ID (rid) is sent, so Healthchecks pairs a success with the most recent start. That gives the right durations unless runs of the same task overlap.

Events

use WF\ScheduleMonitorHealthchecks\Events\HealthchecksPingFailed;

Event::listen(function (HealthchecksPingFailed $event) {
    // $event->logItem, $event->exception
});

Testing

composer test

API references

• Healthchecks.io Pinging API
• Healthchecks.io Management API v3

License

The MIT License (MIT). Please see LICENSE.md for more information.