Timeouts & error handling

Per-check timeout

timeout(5) bounds a check at five seconds:

Health::for($team)->monitor(PaymentGatewayCheck::class)
    ->everyMinute()
    ->timeout(5)   // hard abort under CLI with ext-pcntl, post-hoc report elsewhere
    ->save();

On the CLI with ext-pcntl — queue workers included — the check is hard-aborted the moment the budget elapses, via SIGALRM. Elsewhere (web SAPI, Windows) it is a best-effort post-hoc report: the check runs to completion and is marked failed if it overran. A timed-out check flows through the normal failed-result path with a CheckTimedOut exception recorded in meta, plus timed_out_after.

Inside a queue worker the job’s own --timeout alarm is kept: a check budget longer than the time the job has left never extends it, and the worker’s alarm is re-armed after the check.

Exception-safe checks

A check’s check() never needs a try/catch. Any thrown exception is converted into a clean failed result and recorded as a normal alert and run, so a bad check never fails the queue job. An exception message can be huge — a QueryException embeds the SQL — so run and alert rows store at most CheckResult::MAX_STORED_MESSAGE_LENGTH (1000) characters; the full text stays on the returned result and in meta['exception_message']:

Health::define('flaky', function () {
    throw new RuntimeException('upstream exploded'); // becomes CheckResult::failed()
});

// Or build a result from a caught exception yourself:
CheckResult::fromException($e); // status failed, exception class + bounded trace in meta

$alert = $team->alerts()->open()->first();

$alert->message;                    // stored up to CheckResult::MAX_STORED_MESSAGE_LENGTH (1000) characters
$alert->meta['exception'];          // e.g. 'RuntimeException'
$alert->meta['exception_message'];  // 'upstream exploded' — the full text, never shortened
$alert->meta['exception_trace'];    // the first 15 stack frames
$alert->meta['timed_out_after'];    // seconds — present only for timeouts

Only check() itself is guarded. Resolving the check (an unregistered key) or the owner (no HasNotifiablesForAlerts) still throws and fails the job — those are configuration errors you want to see.

Exceptions

All live in RoundlyConsulting\Alerts\Exceptions, apart from the toolkit one: