Function Reference: Monitoring and Operations¶
The functions that report on queue health and that the Processor itself calls. See also Channels and Events and Fleet Control, Options, and Registry.
Monitoring functions¶
pgrelay.queue_stats(p_minutes, p_order_by)¶
Returns one row per (action_type, channel) pair that either has undispatched queue rows or had log activity within the last p_minutes minutes. An empty result means the queue is fully clear and there has been no recent activity.
| Parameter | Type | Default | Description |
|---|---|---|---|
p_minutes |
int |
1 |
Log lookback window, in minutes. Controls the processed, expired, and errors columns. |
p_order_by |
text |
'action' |
'action' sorts by action_type, channel; 'count' sorts by pending DESC, action_type, channel. Any other value falls back to 'action'. |
Returns: a table with columns action_type, channel, pending, future, pending_restricted, oldest_pending, processed, expired, errors — see Managing Channels in the User Guide for what each column means.
EXECUTE is revoked from PUBLIC. This function is not included in grant_relay() or grant_user() — grant it explicitly to monitoring roles:
Example — alert if any channel has had events pending for more than 30 seconds:
SELECT action_type, channel, oldest_pending
FROM pgrelay.queue_stats()
WHERE oldest_pending > interval '30 seconds';
pgrelay.health_report(p_limit, p_reference, p_request_type) (v1.3)¶
Returns pgrelay.processor_health rows — the answers to Processor health snapshot requests — newest first.
| Parameter | Type | Default | Description |
|---|---|---|---|
p_limit |
integer |
100 |
Maximum rows returned. |
p_reference |
text |
NULL |
Exact-match filter on the caller-supplied reference; NULL means no filter. |
p_request_type |
text |
NULL |
Exact-match filter on the request type (e.g. 'os_metrics'); NULL means no filter. |
Returns: SETOF pgrelay.processor_health. Granted by grant_user().
Processor and operational functions¶
pgrelay.queue_has_work()¶
Returns true if at least one pending, eligible row exists in the queue. The Processor calls this every second as a cheap probe. Superuser access is not needed to call this.
Returns: boolean.
pgrelay.queue_pending_ids()¶
Returns (id, action_type) pairs for the pending, eligible rows this Processor is allowed to dispatch (node-pinned rows only on their own node; unrestricted rows according to the --mode ownership rules — see the Multi-Master Deployment book; on a single node, everything qualifies), restricted to at most one candidate per exclusivity group — always the oldest eligible row in that group — according to each channel's concurrency_mode (see Per-channel dispatch concurrency). For 'concurrent' channels (and unregistered channels), every row is its own group, so nothing is filtered out. Rows are ordered by action_types.run_order (NULLs last), then run_at, then queued_at — so lower run_order action types dispatch first within a batch. Uses FOR UPDATE OF queue SKIP LOCKED, so concurrent Processors each get a disjoint set. Because this runs as a single autocommitted statement, the brief row locks it takes are released the instant it returns.
Returns: a table of (id bigint, action_type text).
pgrelay.process_one(p_id)¶
Claims and processes one queue row. Called once per event by each Processor worker. This is a SECURITY INVOKER function — the action SQL runs as the calling role (the pgrelay role).
| Parameter | Type | Description |
|---|---|---|
p_id |
bigint |
The queue row ID to process. |
Returns: a table of (channel text, outcome text, log_id bigint).
outcome values: skipped, ok, expired, invalid, retry_scheduled, unsupported_action_type, error.
pgrelay.preflight()¶
Startup self-check. Returns one row per check. Called by the Processor before it begins polling; can also be called manually.
Returns: a table of (check_name text, status text, detail text).
status values: ok, warn, error. The Processor refuses to start if any row has status = 'error'.
Since v1.1, the checks are scoped by the application registry: when pgrelay.pg_relay_applications contains a pg_relay_notifier row, three notifier:* checks verify the notifier schema, its four interface functions, and the pgrelay role's EXECUTE grant on them. These are always warnings, never errors — a broken companion application must never stop ordinary SQL event processing. Two error-class grant checks cover the v1.1 operating functions queue_probe() and request_reload().
Continue to Function Reference: Fleet Control, Options, and Registry.