@unhandled/instrumentation-bullmq
v0.1.15
Published
BullMQ queue, flow and worker tracing for Unhandled
Readme
@unhandled/instrumentation-bullmq
OpenTelemetry tracing for BullMQ 5: jobs added through queues and flow producers, and jobs run by workers.
Install
pnpm add @unhandled/instrumentation-bullmqbullmq >= 5.0.0 is a peer dependency.
Register
With the AdonisJS agent, add the integration. Nothing is traced until it is listed.
import { defineConfig } from '@unhandled/agent-adonisjs'
import { bullmq } from '@unhandled/instrumentation-bullmq/integration'
export default defineConfig({
integrations: [bullmq({ useProducerSpanAsConsumerParent: true })],
})The integration uses the agent's sampling callback for every worker execution. Pass bullmq({ sampling }) to use a different callback for BullMQ jobs only, or bullmq({ enabled: false }) to turn it off.
Without the agent, create and enable the instrumentation before bullmq is imported:
import { BullMQInstrumentation } from '@unhandled/instrumentation-bullmq'
new BullMQInstrumentation().enable()Both CommonJS require and ESM import are hooked; ESM needs the import-in-the-middle loader hook registered before bullmq loads. When a bundler or loader order defeats the hooks, patch the module yourself:
import * as bullmq from 'bullmq'
const instrumentation = new BullMQInstrumentation()
instrumentation.patch(bullmq)
// later: instrumentation.unpatch(bullmq)Standalone use does no job sampling.
Options
| Option | Default | Effect |
| --------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| emitCreateSpansForBulk | true | One Job.addJob span per job in Queue.addBulk. |
| emitCreateSpansForFlow | true | One Job.addJob span per job in FlowProducer.add, and per flow in FlowProducer.addBulk. |
| requireParentSpanForPublish | false | Producer spans are created only when a span is already active. |
| useProducerSpanAsConsumerParent | false | The worker span joins the producer's trace as its child instead of starting a new trace with a link. |
| enabled | true | Integration only. false registers nothing. |
| sampling | agent callback | Integration only. Sampling callback for BullMQ jobs. |
Spans
| Operation | Kind | Name |
| -------------------------- | -------- | -------------------------- |
| Queue.add | PRODUCER | Queue.add {queue} |
| Queue.addBulk | INTERNAL | Queue.addBulk {queue} |
| each job of a bulk or flow | PRODUCER | Job.addJob {queue} |
| FlowProducer.add | INTERNAL | FlowProducer.add {queue} |
| FlowProducer.addBulk | INTERNAL | FlowProducer.addBulk |
| worker job execution | CONSUMER | Worker.run {queue} |
The producer's trace context is written to the job's opts.telemetry.metadata (the field BullMQ itself uses for propagation, stored in Redis as tm). Jobs added with telemetry.omitContext: true carry no context. If BullMQ's own telemetry is also configured, this package's context wins.
A failed execution records the exception and sets ERROR status. Rescheduling errors (DelayedError, WaitingError, WaitingChildrenError, RateLimitError) are not failures.
Attributes
Every span has messaging.system=bullmq and messaging.operation.type: send on Queue.add and the bulk and flow parents, create on Job.addJob, process on Worker.run. All but FlowProducer.addBulk carry messaging.destination.name.
| Attribute | Spans |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| messaging.job.name, messaging.bullmq.job.name | single-job spans |
| messaging.message.id | single-job spans |
| messaging.bullmq.job.timestamp, .delay, .attempts, .repeatJobKey | single-job spans |
| messaging.batch.message_count, messaging.bullmq.job.bulk.names | addBulk parents |
| messaging.message.retry.count, messaging.job.queue_time_ms | Worker.run |
| messaging.bullmq.job.processedOn, .finishedOn, .failedReason | Worker.run (failedReason only after a failure) |
| messaging.bullmq.worker.concurrency, .lockDuration, .lockRenewTime, .rateLimiter.max, .rateLimiter.duration | Worker.run, when set on the worker |
messaging.job.queue_time_ms is processedOn - timestamp - delay.
Events on Worker.run
| Event | Attributes |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| bullmq.job.lock_extended | messaging.message.id, messaging.bullmq.lock.duration |
| bullmq.job.removed | messaging.message.id of the removed job |
| bullmq.job.retry | messaging.message.id, and for automatic retries messaging.message.retry.count and messaging.bullmq.retry.delay |
Tests
The tests need Redis. They use REDIS_URL when set and redis://127.0.0.1:6391 otherwise:
redis-server --port 6391 --save '' --appendonly no
pnpm testFor AI agents
A coding agent can install this package, check that its data arrives and fix the errors it reports through the Unhandled MCP server at https://unhandled.net/mcp. In Claude Code, the Unhandled plugin adds that server plus skills for instrumenting a service, fixing a production error with a failing test first and verifying a deploy:
claude plugin marketplace add treboryx/unhandled
claude plugin install unhandled@unhandledCodex, Cursor, Gemini CLI and other agents connect to the same URL. Coding agents has the setup for each one and an AGENTS.md section to add to your repository.
