Queue Trace

Queue trace provides per-item execution tracing, performance metrics, payload dead-letter capture (DLQ), execution batch grouping, and retry observability for Drupal queues.

By decorating Drupal core's QueueWorkerManager, Queue Trace offers complete visibility into queue processing without requiring alterations to your existing queue workers or queue backend storage.

Features

• Non-invasive architecture: Decorates plugin.manager.queue_worker using standard Drupal service decoration. Does not modify core queue backends.
• Per-item observability: Records status (processing, success, failed, requeued, reprocessed_success, reprocessed_failed), execution duration in milliseconds, worker class, and throwable error traces (with file and line).
• Dead-Letter Queue (DLQ) capture: Preserves JSON-encoded payloads for failed items to allow zero-data-loss inspection and replay.
• One-click retry & re-enqueue:
  • Re-enqueue failed items back into their active Drupal queue.
  • Execute failed items synchronously from the UI for immediate debugging.
  • Batch re-enqueue all failed items visible on the current view.
• Execution & batch grouping: Dynamically extracts batch or execution context from payload keys or entity lookups (e.g., Campaign #12, Sync Batch #45) with configurable idle windows.
• Active queues overview: Real-time dashboard of all registered workers, waiting item count, and in-flight item count.
• Zero-impact failure model: All tracing writes are isolated in try/catch blocks; tracer issues will never interrupt core worker execution.

Requirements

• Drupal 10.3+ or Drupal 11.x
• Core Views module

Installation

Install via Composer:

composer require 'drupal/queue_trace:^1.0@alpha'

Enable the module via Drush or the administrative UI:

drush en queue_trace

Configuration

Navigate to Reports > Queue Trace > Settings (/admin/reports/queue-trace/settings):

• Trace Mode:
  • Only configured queues (recommended): Only traces queues explicitly enabled in the settings table.
  • All site queues: Automatically traces every registered QueueWorker across the site.
• Per-Queue Settings: Enable tracking, select payload keys for batch ID and item ID, enable entity lookup for readable labels, and define the idle window for batch grouping.

User Interface

Access the live dashboard and logs under Reports > Queue Trace (/admin/reports/queue-trace). Filter by queue name, batch label, status, or date, and trigger retries directly from the operations column.

API & Extensibility

Queue Trace provides hooks to customize execution context and item label extraction:

hook_queue_trace_extract_execution_context(string $queue_name, mixed $data): ?array
hook_queue_trace_extract_item_label(string $queue_name, mixed $data): ?string