Before You Start

Events are an optional layer on top of evaluation: register a notification channel, or a function call, against a check, and the evaluation engine fires it automatically the moment that check's severity newly crosses into — or above — a floor you choose, with no polling and no separate scheduler needed. Firing an Event on a Severity Change in the Adding Your Own Checks book covers the basics of creating one; this book is the full reference — every parameter, the exact firing rule, the whole lifecycle, and how to debug an event that isn't behaving the way you expected.

This is entirely opt-in. A check with no events registered against it behaves exactly as it did before this feature existed — nothing about collection, evaluation, or severity computation changes.

A check needs somewhere to get a severity from

Events react to a check's confirmed severity, which the evaluation engine only ever sets to 'info', 'warning', or 'critical' — the tiers an event can actually target, see min_severity — when the check actually has something to judge it against: a threshold, or a custom evaluator function. A check with neither always evaluates as 'not_evaluable', which never satisfies any floor an event could be watching for — an event registered against such a check will simply never fire, silently, forever.

This isn't a bug to work around; it's the same "no threshold, no verdict" rule that governs the reporting functions too (see How Threshold Evaluation Works in the User Guide). If an event never fires and you're not sure why, Troubleshooting has this as the very first thing to check.

Continue to Creating an Event.