Asynq Queue Prometheus Metrics

This document describes the queue-level Prometheus metrics exported by metrics.NewQueueMetricsCollector.

All metrics have a queue label to identify the queue. For example:

asynq_queue_latency_seconds{queue="critical"}

asynq_tasks_enqueued_total reports the current task count for each state. The following state values are exported:

This metric is the sum of tasks in these states:

pending + active + scheduled + retry + archived + completed + aggregating

To monitor tasks currently waiting for worker execution, prefer:

asynq_tasks_enqueued_total{state="pending"}

rather than asynq_queue_size.

increase(asynq_tasks_failed_total[5m])

sum(increase(asynq_tasks_failed_total[5m]))
/
sum(increase(asynq_tasks_processed_total[5m]))

When using this expression in an alert, handle a zero denominator so that periods with no task processing do not produce meaningless results.

asynq_tasks_enqueued_total{state="pending"}

asynq_queue_paused_total == 1

asynq_queue_latency_seconds > 300

• Use rate() or increase() with asynq_tasks_failed_total and asynq_tasks_processed_total to observe changes over time; their instantaneous absolute values do not represent current load.
• Although their names end with _total, asynq_tasks_enqueued_total and asynq_queue_paused_total are implemented as Gauges. Read their current values directly; do not use rate() or increase() with them.
• asynq_queue_latency_seconds is based only on the oldest pending task. Tasks waiting for a future scheduled or retry time do not increase this metric.
• The values are snapshots of Redis queue state at collection time. Collection frequency affects the freshness of dashboards and alerts.

• Metric names, labels, and Prometheus types: x/metrics/metrics.go
• Queue states and the Size calculation: inspector.go and internal/rdb/inspect.go