Monitor queue health and consumer lag

PgQue exposes three primary observability functions inherited from PgQ, plus a one-stop status() view. All are granted to pgque_reader. This guide explains what each metric means and how to use it for alerting.

Queue health: get_queue_info()

select queue_name, ticker_lag, ev_per_sec, ev_new, last_tick_id
from pgque.get_queue_info('orders');

A healthy queue:

 queue_name | ticker_lag   | ev_per_sec | ev_new | last_tick_id
------------+--------------+------------+--------+--------------
 orders     | 00:00:01.842 |       3.40 |     12 |         1247

Column	Type	Meaning
`queue_name`	text	Queue name
`queue_ntables`	integer	Number of rotation tables (default 3)
`queue_cur_table`	integer	Index of the currently active rotation table
`queue_rotation_period`	interval	How often the hot table rotates
`queue_external_ticker`	boolean	Whether ticking is driven externally
`queue_ticker_paused`	boolean	Whether the ticker is paused
`queue_ticker_max_count`	integer	Force a tick after N events
`queue_ticker_max_lag`	interval	Max wall time between ticks
`queue_ticker_idle_period`	interval	Tick interval when idle (default 1 min)
`ticker_lag`	interval	Wall time since the last tick
`ev_per_sec`	float8	Recent event ingestion rate
`ev_new`	bigint	Events waiting in the current table for the next tick
`last_tick_id`	bigint	Most recent tick id

To inspect all queues at once, call without arguments:

select * from pgque.get_queue_info();

Consumer health: get_consumer_info()

select queue_name, consumer_name, lag, last_seen, pending_events
from pgque.get_consumer_info('orders', 'processor');

A healthy consumer:

 queue_name | consumer_name | lag          | last_seen    | pending_events
------------+---------------+--------------+--------------+----------------
 orders     | processor     | 00:00:00.520 | 00:00:00.201 |              0

A stuck consumer a few hours later:

 queue_name | consumer_name | lag          | last_seen    | pending_events
------------+---------------+--------------+--------------+----------------
 orders     | processor     | 02:15:33.204 | 02:14:59.817 |            847

Column	Type	Meaning
`queue_name`	text	Queue name
`consumer_name`	text	Consumer name
`lag`	interval	Age of the last finished batch — high means falling behind
`last_seen`	interval	Time since the consumer last processed a batch
`last_tick`	bigint	Last tick id the consumer processed
`current_batch`	bigint	Active batch id (null if none open)
`next_tick`	bigint	Next tick id to process (null if up to date)
`pending_events`	bigint	Events waiting for this consumer

Call without arguments to see all consumers across all queues:

select * from pgque.get_consumer_info();

-- Filter to one queue
select * from pgque.get_consumer_info('orders');

Active batch info: get_batch_info()

select * from pgque.get_batch_info(:batch_id);

Column	Type	Meaning
`queue_name`	text	Queue name
`consumer_name`	text	Consumer that opened the batch
`batch_start`	timestamptz	When the batch was opened
`batch_end`	timestamptz	Batch close time (null if still active)
`prev_tick_id`	bigint	Start of the tick window
`tick_id`	bigint	End of the tick window
`lag`	interval	Age of the batch
`seq_start`	bigint	Event sequence start
`seq_end`	bigint	Event sequence end

One-stop health check: status()

select * from pgque.status();

 component  | status      | detail
------------+-------------+----------------------------------
 postgresql | info        | PostgreSQL 17.2 on ...
 pgque      | info        | 0.2.0-rc.1
 pg_cron    | scheduled   | 4 jobs active
 queues     | info        | 3 queues configured
 consumers  | info        | 7 active subscriptions

Run status() first when anything looks wrong.

Red flags to alert on

Signal	Red flag	Check
`ticker_lag`	Growing past `queue_ticker_max_lag` (default 3 s)	Ticker not running — check pg_cron or external scheduler
`lag`	Climbing into minutes or longer	Consumer not finishing batches — check the worker
`last_seen`	Climbing into minutes or longer	Consumer stopped calling `receive` — check the worker process
`pending_events`	Growing without bound while `lag` is high	Stuck consumer also blocks table rotation

Experimental observability

Load sql/experimental/observability.sql for extended monitoring functions. These are not part of the default install and their APIs may change.

\i sql/experimental/observability.sql

Function	Returns
`pgque.queue_stats()`	Per-queue depth, age, DLQ count, rotation stats
`pgque.consumer_stats()`	Per-consumer lag, pending events, active batch info
`pgque.queue_health()`	Operational checks: stuck ticker, rotation lag, DLQ growth
`pgque.otel_metrics()`	OTel-compatible metric export rows
`pgque.stuck_consumers(threshold)`	Consumers idle longer than `threshold` (default 1 hour)
`pgque.in_flight(queue)`	Active batches per consumer with age and estimated event count
`pgque.throughput(queue, period, bucket_size)`	Events/sec bucketed over a time window
`pgque.error_rate(queue, period, bucket_size)`	Retries and dead letters bucketed over a time window

Get Started

Guides

Concepts

Performance

Monitor queue health and consumer lag

Queue health: get_queue_info()

Consumer health: get_consumer_info()

Active batch info: get_batch_info()

One-stop health check: status()

Red flags to alert on

Experimental observability

Build docs developers (and LLMs) love

Get Started

Guides

Concepts

Performance

Documentation Index

​Queue health: get_queue_info()

​Consumer health: get_consumer_info()

​Active batch info: get_batch_info()

​One-stop health check: status()

​Red flags to alert on

​Experimental observability

Build docs developers (and LLMs) love

Queue health: get_queue_info()

Consumer health: get_consumer_info()

Active batch info: get_batch_info()

One-stop health check: status()

Red flags to alert on

Experimental observability