NestJS Profiler
Tutorials

RabbitMQ message profiling

Profile RabbitMQ messages consumed via @RabbitSubscribe and inspect routing key, payload and timing in the web profiler.

This tutorial shows how to profile RabbitMQ messages consumed with @golevelup/nestjs-rabbitmq. Each consumed message produces a profile - with a Message panel plus any HTTP, cache, or database activity the handler triggered - that appears in a dedicated RabbitMQ view at /_profiler. The last steps cover the other direction: the messages your app publishes.

Prerequisites

  • @eleven-labs/nest-profiler installed and configured
  • @golevelup/nestjs-rabbitmq consuming messages via @RabbitSubscribe

Step 1 - Install the package

pnpm add -D @eleven-labs/nest-profiler-rabbitmq

@golevelup/nestjs-rabbitmq and amqplib are optional peer dependencies - the ones you already use to consume messages, which stay regular dependencies of your app.

Step 2 - Register the module

Add RabbitMqCollectorModule to the dev-only profiling bundle of the application that consumes your messages (the same process that hosts the profiler). Your RabbitMQModule stays in your own application module: the collector patches AmqpConnection and discovers the @RabbitSubscribe handlers wherever they are declared.

profiling/profiling.module.ts
import { Module } from '@nestjs/common';
import { ProfilerModule } from '@eleven-labs/nest-profiler';
import { RabbitMqCollectorModule } from '@eleven-labs/nest-profiler-rabbitmq';

@Module({
  imports: [ProfilerModule.forRoot({ isGlobal: true }), RabbitMqCollectorModule.forRoot()],
})
export class ProfilingModule {}

ProfilingModule is the dev-only bundle loaded by main-dev.ts — see Enabling and disabling the profiler. If the profiler is installed as a production dependency behind the runtime gate, wrap the same call in ConditionalModule.registerWhen(..., isProfilerEnabled).

Step 3 - Keep your consumer unchanged

You do not change anything for profiling - write an ordinary @RabbitSubscribe handler:

narration.service.ts
import { Injectable } from '@nestjs/common';
import { RabbitSubscribe } from '@golevelup/nestjs-rabbitmq';
import type { ConsumeMessage } from 'amqplib';

@Injectable()
export class NarrationService {
  @RabbitSubscribe({
    exchange: 'articles.events',
    routingKey: 'published.*',
    queue: 'tts.narration',
  })
  async createGeneration(message: ArticleEvent, raw: ConsumeMessage): Promise<void> {
    // … your business logic …
  }
}

Step 4 - Inspect the profile

Publish a message (or trigger your normal flow) and open /_profiler, then pick RabbitMQ in the sidebar. Messages get their own view, with a filter bar of their own. Open one to find:

  • Message - exchange, routing key, handler, redelivered flag, consumer/delivery tags, headers and payload (the HTTP request/response tabs are hidden)
  • HTTP Client, Database, … - whatever the handler triggered

A handler that throws is captured too: its profile is marked failed (status 500) and the thrown error appears in the Exceptions tab.

Try it in the example app

The example API wires this end to end behind feature flags (off by default): creating a review publishes a review.created event that a @RabbitSubscribe consumer reacts to. Start the infrastructure and run it with the flags on:

docker compose up -d mongodb rabbitmq
FEATURE_MONGOOSE=true FEATURE_RABBITMQ=true pnpm example:dev

Then create a review and open /_profiler to see the consumed message profiled:

curl -X POST http://localhost:3000/api/v1/reviews \
  -H 'content-type: application/json' \
  -d '{ "productId": "1", "rating": 5, "comment": "Great product!", "authorId": 1 }'

Configuration

RabbitMqCollectorModule.forRoot({
  captureHeaders: true, // RabbitMQ headers (sensitive ones masked)
  captureBody: true, // deserialized payload - disable if payloads are large
  maskHeaders: ['x-tenant-secret'], // merged with the built-in mask list
});

Driving options from ConfigService

Use forRootAsync() in the bundle to resolve captureBody/maskHeaders from ConfigService (or any provider). It resolves option values only: behind the runtime gate, wrap it in ConditionalModule.registerWhen(..., isProfilerEnabled) as usual (see Enabling and disabling the profiler).

import { ConfigService } from '@nestjs/config';

RabbitMqCollectorModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    captureBody: config.get<boolean>('profiler.rabbitmqCaptureBody') ?? true,
    maskHeaders: config.get<string[]>('profiler.maskHeaders') ?? [],
  }),
});

Profiling what you publish, too

The same package ships RabbitMqPublishCollectorModule, which lists the messages a profiled request published in a RabbitMQ panel. It is independent of the module above — add it to the bundle on its own in a publish-only API, or alongside it to also see the messages your consumers republish:

profiling/profiling.module.ts
import { RabbitMqPublishCollectorModule } from '@eleven-labs/nest-profiler-rabbitmq';

RabbitMqPublishCollectorModule.forRoot();

Nothing changes in your publishers: keep injecting AmqpConnection and calling publish(). Each row shows the exchange, routing key, message properties, masked headers, payload, duration and outcome, tagged slow / n-plus-one / error by the rule engine — publishing the same message once per loop iteration is exactly the N+1 the panel makes visible.

RabbitMqPublishCollectorModule.forRoot({
  captureBody: true, // the published message - disable if payloads are large
  maskHeaders: ['x-tenant-secret'], // merged with the built-in mask list
  slowThreshold: 50, // ms before a publish is tagged `slow`
});

See the whole RabbitMQ surface, not just the traffic

With @eleven-labs/nest-profiler-routes installed, the same module contributes a Discover / RabbitMQ view: the topology your RabbitMQModule declared — connections (credentials masked), exchanges, queues with the binding and x-… arguments that feed them, exchange bindings — then every consumer, each expanding to its full subscription: queue, exchange, routing keys, connection, queueOptions and error behaviour.

It is read from the resolved configuration, so it also answers the questions traffic cannot: which dead-letter and retry queues exist, which handler runs on which connection, and whether a handler referencing a module-level handlers entry is registered at all.

How it works

A consumed message has no HTTP request/response, so the module registers an IContextAdapter for the rmq context that creates a fresh profile per message and registers the rabbitmq entrypoint type (the RabbitMQ list view and Message detail tab). The publish collector works the other way around: it patches AmqpConnection.prototype.publish and appends to whatever profile is active. See How it works on the package page.

Powered & maintained by

On this page