Skip to main content
This guide covers how to instrument @boringnode/queue for monitoring background jobs. You will learn how to:
  • Install and configure the instrumentation
  • Track job dispatch and processing
  • Understand producer and consumer spans
For the full list of required span attributes and what powers the Jobs dashboard, see the Jobs feature page.

​
Installation

npm install @boringnode/queue
The OTel instrumentation is built into @boringnode/queue itself. No additional package is needed.

​
Usage

Create an instance of QueueInstrumentation and call enable(). This must happen before you call QueueManager.init().
instrumentation.ts
import { QueueInstrumentation } from "@boringnode/queue/otel";

const instrumentation = new QueueInstrumentation();
instrumentation.enable();
Once enabled, the instrumentation automatically patches QueueManager.init() to inject tracing wrappers. All job dispatches and worker executions will create spans. If the automatic patching does not work (e.g., ESM hook timing issues), you can register manually:
instrumentation.ts
import * as queue from "@boringnode/queue";

instrumentation.manuallyRegister(queue);
If you are using AdonisJS with the Monocle agent, this instrumentation is configured automatically when @boringnode/queue is installed. No manual setup is needed.

​
Configuration

const instrumentation = new QueueInstrumentation({
  // Messaging system name used in span attributes (default: "boringqueue")
  messagingSystem: "boringqueue",

  // How consumer spans relate to producer spans (default: "link")
  executionSpanLinkMode: "link",
});

​
Span linking vs parenting

By default, consumer spans are linked to the producer span. This means they appear as separate traces connected by a link. Set executionSpanLinkMode: "parent" to make the consumer span a child of the producer, keeping them in the same trace.

​
Spans

​
Producer spans

When you dispatch a job, the instrumentation creates a PRODUCER span named publish {queueName}. Trace context is injected into the job payload so the consumer can link back to the producer. For batch dispatches, a single PRODUCER span is created with a messaging.batch.message_count attribute.

​
Consumer spans

When a worker processes a job, the instrumentation creates a CONSUMER span named process {queueName}. The span captures job metadata, queue wait time, and any errors thrown during processing. If the job is retried, a messaging.retry event is recorded on the span with the next retry timestamp.

​
Internal operation suppression

Internal queue operations (Redis calls, etc.) are automatically suppressed to keep traces clean. Only the high-level dispatch and execution spans are visible.

​
Span attributes

In addition to the standard job attributes, the @boringnode/queue instrumentation emits these attributes:
AttributeDescription
messaging.job.nameJob class name
messaging.job.queue_time_msTime between dispatch and execution start (ms)
messaging.job.group_idJob group ID (if set)
messaging.job.priorityJob priority (if set)
messaging.job.delay_msJob delay in ms (if set)
messaging.message.retry.countNumber of retry attempts