Blackouts

One-off wall-clock windows silencing matching checks, in one of two modes: 'run' (collection and evaluation both suppressed — "don't even look") or 'alerting' (the default — evaluation runs completely normally and only reporting is suppressed: the row is stamped not-reportable and no event fires, with a still-broken-afterwards check firing exactly once at the first post-window evaluation). For the narrative version — the two modes, choosing a scope, what a suppression looks like in history, and why no alert is ever lost in a window — see Blackout Windows in the User Guide. The pghf.blackouts table itself is openly readable; all writes go through the three privileged functions below. Unlike thresholds and events, none of these enforce the inactive-catalog guard — a blackout is operational suppression, not catalog authorship, and works even under an inactivated namespace or category.

pghf.create_blackout(p_starts_at timestamptz, p_ends_at timestamptz, p_reason text, p_mode text DEFAULT 'alerting', p_check_id text DEFAULT NULL, p_namespace_code text DEFAULT NULL, p_category_code text DEFAULT NULL)

The only way to add a blackout window. No scope argument at all declares a global window; otherwise scope with exactly one of a check or a category. Overlapping windows union, per mode: any matching in-window row of a mode suppresses that mode's layer.

Parameter	Type	Mandatory	Default	Description
p_starts_at	timestamptz	Yes	—	Window start (inclusive).
p_ends_at	timestamptz	Yes	—	Window end (exclusive — the window is half-open). Must be after the start.
p_reason	text	Yes	—	Recorded verbatim into every suppression this window produces. Must be non-blank — a reasonless blackout is exactly the silent gap this table exists to prevent.
p_mode	text	No	'alerting'	'alerting' = suppress reporting only (evaluation runs normally); 'run' = suppress collection and evaluation — the stronger, explicit action.
p_check_id	text	No	empty	Scope to one check. Must exist. Mutually exclusive with the category arguments.
p_namespace_code	text	No	empty	With p_category_code: scope to one category. Must be given together.
p_category_code	text	No	empty	See above. The category must exist.

Returns: bigint — the new blackout's identifier. Only a role explicitly granted permission — whichever should own your maintenance calendar — can call this.

pghf.update_blackout(p_blackout_id bigint, p_starts_at timestamptz DEFAULT NULL, p_ends_at timestamptz DEFAULT NULL, p_reason text DEFAULT NULL)

Shifts an existing window and/or amends its reason (leave a parameter empty to keep its current value). Scope and mode are immutable — changing either is a delete plus a create. Ending one early while keeping its row is p_ends_at => now().

Parameter	Type	Mandatory	Default	Description
p_blackout_id	bigint	Yes	—	Blackout to update. Must exist.
p_starts_at	timestamptz	No	unchanged	New start.
p_ends_at	timestamptz	No	unchanged	New end. The resulting window must not be empty or inverted.
p_reason	text	No	unchanged	New reason; cannot be blanked.

Returns: nothing. Only a role explicitly granted permission can call this.

pghf.delete_blackout(p_blackout_id bigint)

Permanently deletes a blackout window — like events, there's no soft-retire state. The suppressions it already recorded stay in history untouched.

Parameter	Type	Mandatory	Default	Description
p_blackout_id	bigint	Yes	—	Blackout to delete. Must exist.

Returns: nothing. Only a role explicitly granted permission can call this.

pghf.get_blackout(p_blackout_id bigint)

Returns one blackout record; raises an error if it doesn't exist.

pghf.list_blackouts(p_active_at timestamptz DEFAULT NULL, p_mode text DEFAULT NULL)

Lists blackout windows, ordered by start time.

Parameter	Type	Mandatory	Default	Description
p_active_at	timestamptz	No	empty = every window	Only windows covering that instant (pass now() for "currently active").
p_mode	text	No	empty = both modes	Filter to 'run' or 'alerting' windows.

Returns: zero or more blackout records. An empty result is a legitimate answer, not an error.

pghf.is_blacked_out(p_check_id text, p_mode text DEFAULT NULL, p_at timestamptz DEFAULT clock_timestamp())

Whether this check is inside a matching blackout window at the given instant — of the given mode, or of either mode when left empty. The exact predicate the engine gates use.

Parameter	Type	Mandatory	Default	Description
p_check_id	text	Yes	—	Must exist.
p_mode	text	No	empty = either mode	'run' or 'alerting' to test one mode specifically.
p_at	timestamptz	No	now	Instant to test.

Returns: boolean. Raises if the check doesn't exist or the mode is invalid. Callable by anyone.