Queue managers

A queue manager is the live read/write side of the dashboard — it browses your queues' current state directly through the driver's API (counts, jobs, payloads) and, behind a second default-deny gate, acts on jobs. Managers are passed via the queueManagers option (not watchers), and every endpoint they add sits under the existing Telescope authorizer.

TelescopeModule.forRoot({
  authorizer: (ctx) => isAdmin(ctx.request),                 // reads
  authorizeAction: (ctx, action) => canMutateQueues(ctx.request), // mutations — default-deny
  queueManagers: [/* ... */],
});

BullMQ — @dudousxd/nestjs-telescope-bullmq

This package has two halves: a job watcher (what jobs did) and a queue manager (current queue state + actions).

Job watcher

Captures every processed job (id, name, queue, outcome, duration, attempts) and correlates the queries and exceptions a job emits to that job's batch. No host wiring — it discovers your @Processor (WorkerHost) classes automatically.

import { BullMqJobWatcher } from '@dudousxd/nestjs-telescope-bullmq';

TelescopeModule.forRoot({ watchers: [new BullMqJobWatcher({ slowMs: 1000 })] });

Each job becomes a job entry with origin: 'queue'; opening it in the dashboard shows everything it caused. With these entries captured, GET /telescope/api/queues?window=1h reports per-queue throughput, runtime/wait-time percentiles, and failure rate.

Queue manager (live reads + actions)

BullMqQueueManager browses queues' current state via the BullMQ Queue API and implements the action side (retry, remove, promote, retryAll). At bootstrap it discovers every @nestjs/bullmq Queue in the container via DiscoveryService — no extra wiring.

import { BullMqQueueManager } from '@dudousxd/nestjs-telescope-bullmq';

TelescopeModule.forRoot({ queueManagers: [new BullMqQueueManager()] });
// allow-list only some queues: new BullMqQueueManager(['mail', 'reports'])

Read endpoints:

Mutation endpoints (default-deny):

Job payloads pass through core redaction before they leave the server, so secret-keyed fields are masked. redrive is SQS-only — calling it against the bullmq driver returns 405.

SQS — @dudousxd/nestjs-telescope-sqs

A live-queue manager for Amazon SQS: report queue depth (pending / in-flight / delayed) for any queue, and — for queues that have a dead-letter queue — snapshot the DLQ (redacted bodies) and redrive it back to the source.

The DLQ is optional, matching real AWS. Without dlqUrl you still get live depth; with it you also get DLQ inspection and redrive. Each summary carries an actions hint (['redrive'] with a DLQ, else []) so the UI shows the Redrive button only where it works.

import { SQSClient } from '@aws-sdk/client-sqs';
import { SqsQueueManager, createAwsSqsOps } from '@dudousxd/nestjs-telescope-sqs';

const client = new SQSClient({ region: 'us-east-1' });

TelescopeModule.forRoot({
  queueManagers: [
    new SqsQueueManager({
      ops: createAwsSqsOps(client),
      queues: [
        { name: 'mail', url: '…/mail', dlqUrl: '…/mail-dlq' }, // depth + DLQ + redrive
        { name: 'events', url: '…/events' },                   // depth only
      ],
    }),
  ],
});

There's no hard dependency on @aws-sdk/client-sqs — the SDK is touched only inside createAwsSqsOps. Advanced hosts can implement the SqsOps port themselves (four methods) and skip the SDK entirely.

What SQS can and can't do

SQS has no "list all messages" primitive, so:

• Depth is always reported (waiting / active / delayed) from GetQueueAttributes.
• Only failed is browsable, and only with a dlqUrl. listJobs('failed') is a snapshot, not a drain — it ReceiveMessages up to 10 DLQ messages with a short visibility timeout and never deletes them; there's no real pagination.
• The one mutation is redrive (POST .../sqs/:queue/actions/redrive), which issues a native StartMessageMoveTask from the DLQ back to the source — available only for queues with a dlqUrl, and gated by authorizeAction like every other mutation.