Managing Events¶

Listing what's registered¶

Two dedicated read functions cover listing and looking up events. The underlying table still has open read access for everyone, like every other catalog table in this framework, if you'd rather query it directly — but the functions save you the lookup from check ID to the check's internal identity, and raise a clear error for a check or event that doesn't exist instead of silently returning nothing:

-- every event registered against one check
SELECT * FROM pghf.list_events(p_check_id => 'PGHF11-009');

-- only its active ones
SELECT * FROM pghf.list_events(p_check_id => 'PGHF11-009', p_only_active => true);

-- everything registered, across every check
SELECT * FROM pghf.list_events();

-- one event by id — raises if it doesn't exist
SELECT * FROM pghf.get_event(<event_id>);

Updating, and activating/inactivating¶

SELECT pghf.update_event(
    p_event_id, p_event_type, p_min_severity, p_is_active,
    p_channel_name => ..., p_routine => ..., p_function_args => ...
);

Updating an event is a full replace — the same convention the check-update function uses, and for the same reason: an empty value is legitimate for several of these fields (a 'notify' event's routine, a 'function' event's channel name), so there's no way to distinguish "leave this field alone" from "clear it" without requiring every value on every call. Re-supply everything, not just what changed.

Whether the event is active is how you activate or inactivate it — there is no separate toggle function. This is deliberate: activation is just one more field in the same full-replace call, not a special operation.

-- stage an event, dormant, before its consumer is ready
SELECT pghf.create_event('X01-001', 'notify', 'critical', p_channel_name => 'x01_pager', p_is_active => false);

-- ... later, once the consumer is confirmed listening ...
SELECT pghf.update_event(<event_id>, 'notify', 'critical', true, p_channel_name => 'x01_pager');

Important: activating a previously-inactive event does not retroactively fire it just because the check happens to already be breaching at the moment you turn it on. Transition detection only ever looks at the check's own evaluation history — never at when the event itself was activated — so an event you just turned on fires on the next genuine transition (the check recovering and later re-breaching), not immediately. If you need an immediate signal for a check that's already breaching right now, query the reporting functions directly instead of waiting on an event.

Creating or updating an event raises an error if the target check's namespace or category has been inactivated — the same guard that applies to creating a check or setting a threshold. See Inactivating a Namespace or Category in the User Guide.

Deleting¶

SELECT pghf.delete_event(<event_id>);

A genuine, permanent deletion — there is no soft-retire state for events the way checks have a retired flag. If you want an event to stop firing but keep its configuration around for later, use the update function with the active flag set to false instead; if you're sure you're done with it, deleting removes the row outright. Unlike creating or updating an event, deleting one is not blocked by an inactivated namespace or category — the same exemption inactivating a check itself has, so cleanup stays possible even in the middle of winding down something else.

Continue to Permission Model.