Thresholds

Thresholds are defined against the check only — exactly one threshold record may exist per check, and there is deliberately no per-suite override mechanism: suites decide what runs together; checks own what the results mean. (A deployment that genuinely needs two sensitivities for the same metric copies the check — see Copying an Existing Check — and thresholds the copy independently.)

pghf.clear_threshold(p_check_id text)

Removes a check's threshold.

Parameter	Type	Mandatory	Default	Description
p_check_id	text	Yes	—	Check to clear the threshold for. Must exist.

Returns: nothing. Raises an error if the check doesn't exist, or its namespace/category is inactive; simply does nothing (not an error) if there's no threshold to clear. Only a role explicitly granted permission can call this.

pghf.get_threshold(p_check_id text)

Returns a check's one threshold record.

Parameter	Type	Mandatory	Default	Description
p_check_id	text	Yes	—	Check to look up the threshold for. Must exist.

Returns: the threshold record. Raises an error if the check doesn't exist, or if it exists but has no threshold record.

pghf.list_thresholds(p_check_id text DEFAULT NULL)

Lists threshold records — at most one per check.

Parameter	Type	Mandatory	Default	Description
p_check_id	text	No	empty = every threshold in the catalog	Scope to one check.

Returns: zero or more threshold records. Raises an error only if a given check ID doesn't exist — no threshold configured for an existing check is a legitimate empty result.

pghf.set_threshold(p_check_id text, p_info_value jsonb DEFAULT NULL, p_warn_value jsonb DEFAULT NULL, p_crit_value jsonb DEFAULT NULL, p_bool_breach_severity text DEFAULT NULL, p_value_path jsonpath DEFAULT NULL, p_value_direction text DEFAULT NULL, p_text_pass_pattern text DEFAULT NULL, p_text_breach_severity text DEFAULT NULL, p_delta_kind text DEFAULT NULL, p_evaluator_routine regprocedure DEFAULT NULL, p_min_consecutive_breaches integer DEFAULT 1, p_min_consecutive_window interval DEFAULT NULL, p_min_breaches_in_window integer DEFAULT NULL, p_breach_window_size integer DEFAULT NULL, p_min_consecutive_clears integer DEFAULT 1)

The only way to add or update a threshold — one function for every case: seeding a built-in check's threshold, registering one for a custom check, or later updating either. It's an upsert: calling it again for the same check replaces that record's values in place. Seeded and user-added thresholds are updated identically — there's no protected or built-in state — and this works directly against built-in checks too, since thresholds are explicitly excluded from the update lock described in Catalog: Checks.

Parameter	Type	Mandatory	Default	Description
p_check_id	text	Yes	—	Check this threshold applies to. Must exist and be under an active namespace/category.
p_info_value	jsonb	No	empty	Softest numeric tier (for integer/numeric checks, or a jsonb check with p_value_path).
p_warn_value	jsonb	No	empty	Middle numeric tier.
p_crit_value	jsonb	No	empty	Hardest numeric tier.
p_bool_breach_severity	text	No	empty	Only for boolean checks: 'info', 'warning', or 'critical'.
p_value_path	jsonpath	No	empty	Only for jsonb checks: a path extracting the one scalar to judge from the observed payload (e.g. '$.summary.max_lag'); the numeric tiers then apply to it. Requires p_value_direction and at least one tier. A path matching nothing evaluates not_evaluable.
p_value_direction	text	No	empty	'lower_is_better' or 'higher_is_better' — which direction is bad for the extracted value (jsonb checks carry no direction metadata of their own). Only with p_value_path.
p_text_pass_pattern	text	No	empty	Only for text checks: a POSIX regular expression the value must match (anchor with ^...$ for an exact match) — the text counterpart of the boolean comparator. Set together with p_text_breach_severity.
p_text_breach_severity	text	No	empty	The severity a non-matching text value maps to: 'info', 'warning', or 'critical'.
p_delta_kind	text	No	empty	'absolute' or 'percent': the tiers judge the change since the check's previous collected sample instead of the value itself — direction-aware (improvement never breaches; with no known direction, magnitude either way is judged). No prior sample evaluates not_evaluable.
p_evaluator_routine	regprocedure	No	empty	A custom evaluator function, overriding the default comparator entirely.
p_min_consecutive_breaches	integer	No	1	Strict-consecutive debounce: at-or-above-tier runs required in a row before the breach is confirmed. Mutually exclusive with p_breach_window_size (> 1 on both raises). See Debounce.
p_min_consecutive_window	interval	No	empty = unbounded	Caps how far back (wall-clock) breach debounce and/or hysteresis may look — a prior run older than this can't count toward a streak. Legal with either side enabled — p_min_consecutive_clears > 1 alone is enough, breach debounce doesn't need to be on. Rejected if NEITHER side is enabled (breach debounce off and p_min_consecutive_clears <= 1) — a window with nothing to bound.
p_min_breaches_in_window	integer	No	empty	Windowed-tolerance debounce's "N" — breaches required within the last p_breach_window_size samples. Must be set together with it, and <= it.
p_breach_window_size	integer	No	empty	Windowed-tolerance debounce's "M" — the sample window p_min_breaches_in_window is measured against.
p_min_consecutive_clears	integer	No	1	Symmetric-recovery hysteresis: consecutive clean evaluated runs required to clear a confirmed breach — not a minimum elapsed wall-clock time, so re-running the check manually right after a fix satisfies it just as fast as waiting for the schedule would. 1 = instant clear (original behavior). Independently settable from breach debounce — leaving p_min_consecutive_breaches at 1 while raising this is the supported combination, and what every built-in check ships with by default (see Default Thresholds Reference).

Returns: bigint — the threshold's internal identifier. Only a role explicitly granted permission — whichever should be trusted to author thresholds in your deployment — can call this. On success, also raises an advisory NOTICE (never blocks) if p_min_consecutive_window is set and the check's observed run cadence — across every suite that runs it, since evaluation history is one stream per check — suggests the window may never be satisfiable for breach debounce, hysteresis, or both (checked independently, so a window achievable for one side but not the other still names the side that isn't).

See also pghf.get_debounce_status() for introspecting a check's current progress toward confirming or clearing.

Continue to Events.