---
title: "BullMQ"
description: "Adds tracing and metrics for BullMQ."
url: https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq/
---

# BullMQ for React Router Framework

Available since: `v11.11.0`

*Import name: `Sentry.BullMQTelemetry`*

`BullMQTelemetry` adds tracing for [BullMQ](https://bullmq.io/) queues and workers, and can send BullMQ's job metrics to Sentry. It implements BullMQ's [telemetry interface](https://docs.bullmq.io/guide/telemetry), so you do not add it to `integrations` in `Sentry.init()`. Instead, pass it to the `telemetry` option of each `Queue`, `Worker`, and `FlowProducer`:

```javascript
import * as Sentry from "<sdk-package-name>";
import { Queue, Worker } from "bullmq";

const connection = { host: "127.0.0.1", port: 6379 };
const telemetry = new Sentry.BullMQTelemetry();

const queue = new Queue("emails", { connection, telemetry });

const worker = new Worker(
  "emails",
  async (job) => {
    // Process the job
  },
  { connection, telemetry },
);
```

What gets sent to Sentry:

* **Spans** follow your tracing configuration in `Sentry.init()`, such as [`tracesSampleRate`](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options.md#tracesSampleRate). Without tracing, no spans are sent.
* **Errors** from failed jobs are always captured.
* **Metrics** are off by default. To send them, set [`enableMetrics`](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#enablemetrics).

## [Options](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#options)

### [`enableMetrics`](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#enablemetrics)

*Type: `boolean`*

Sends BullMQ's job metrics to Sentry. Defaults to `false`. Requires `bullmq` `5.69.0` or higher.

```javascript
const telemetry = new Sentry.BullMQTelemetry({ enableMetrics: true });
```

## [Spans](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#spans)

The SDK creates a span when you add a job to a queue and when a worker processes it, and links the two so you can follow each job from the code that added it to the worker that ran it. These spans populate the [Queues dashboard](https://docs.sentry.io/product/dashboards/sentry-dashboards/backend/queues.md).

Span attributes follow Sentry's `messaging.*` conventions, for example `messaging.destination.name` for the queue name. Other BullMQ attributes are sent as `messaging.bullmq.*`, some with underscores instead of dots, such as `messaging.bullmq.worker.force_close`.

## [Errors](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#errors)

When a job fails, the SDK captures an error with the failure message. This also applies to failed attempts that BullMQ retries. BullMQ gives only the message to the telemetry interface, so the stack trace of the error does not show where in the job the error occurred.

## [Metrics](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#metrics)

With `enableMetrics: true`, the SDK sends these [metrics](https://docs.sentry.io/platforms/javascript/guides/react-router/metrics.md):

| Metric                                   | Type         | Unit   | Description                                                                                                                                                    |
| ---------------------------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messaging.bullmq.jobs.completed`        | counter      | none   | Jobs that completed                                                                                                                                            |
| `messaging.bullmq.jobs.failed`           | counter      | none   | Jobs that failed and are not retried                                                                                                                           |
| `messaging.bullmq.jobs.retried`          | counter      | none   | Failed jobs that are retried without a delay                                                                                                                   |
| `messaging.bullmq.jobs.delayed`          | counter      | none   | Jobs that moved to the delayed state, for a retry with a backoff delay or through `job.moveToDelayed()`                                                        |
| `messaging.bullmq.jobs.waiting`          | counter      | none   | Jobs that `job.moveToWait()` moved back to the wait state                                                                                                      |
| `messaging.bullmq.jobs.waiting_children` | counter      | none   | Jobs that moved to the waiting-children state to wait for their child jobs                                                                                     |
| `messaging.process.duration`             | distribution | second | Time from the start of processing until the job left the active state, with `messaging.system` set to `bullmq` and `messaging.operation.name` set to `process` |
| `messaging.bullmq.queue.jobs`            | gauge        | none   | Jobs in a queue in one job state, sent when you call `queue.recordJobCountsMetric()`                                                                           |

## [Supported Versions](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/bullmq.md#supported-versions)

* `bullmq`: `>=5.22.0`
