NestJS Profiler
Tutorials

Set up the profiler

Install @eleven-labs/nest-profiler, enable the core module and inspect your first HTTP requests in the profiler UI.

This tutorial shows how to add @eleven-labs/nest-profiler to a NestJS application and inspect collected request data in the built-in profiler UI.

Step 1 - Install the package

Install the profiler as a dev dependency, so it never reaches your production install:

pnpm add -D @eleven-labs/nest-profiler nestjs-cls

nestjs-cls is required for per-request context propagation.

Install them as regular dependencies instead only if your production code calls the profiler — a service that injects TracerService for custom spans, for instance — and gate them with the runtime gate.

Step 2 - Bundle the profiler

Create a module that holds the profiler — and, later, every collector you add:

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

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

Step 3 - Add a dev entrypoint

Production must not import a package it does not install, so main.ts and AppModule stay as they are. A dev-only root module composes your application with the profiler bundle:

src/app.dev.module.ts
import { Module } from '@nestjs/common';
import { AppModule } from './app.module';
import { ProfilingModule } from './profiling/profiling.module';

@Module({ imports: [AppModule, ProfilingModule] })
export class AppDevModule {}

Move your bootstrap code into a function both entrypoints share, with a hook to wrap the logger:

src/bootstrap.ts
import { ConsoleLogger } from '@nestjs/common';
import type { LoggerService, Type } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';

export async function bootstrap(
  rootModule: Type<unknown>,
  wrapLogger: (logger: LoggerService) => LoggerService = (logger) => logger,
): Promise<void> {
  const app = await NestFactory.create(rootModule, { bufferLogs: true });
  app.useLogger(wrapLogger(new ConsoleLogger('MyApplication')));
  await app.listen(3000);
}
src/main.ts
import { AppModule } from './app.module';
import { bootstrap } from './bootstrap';

void bootstrap(AppModule);

The dev entry boots AppDevModule and wraps the logger with createProfilerLogger, so log entries appear in the profiler's Logs tab:

src/main-dev.ts
import { createProfilerLogger } from '@eleven-labs/nest-profiler';
import { AppDevModule } from './app.dev.module';
import { bootstrap } from './bootstrap';

void bootstrap(AppDevModule, (logger) => createProfilerLogger(logger));

The capture is logger-agnostic and keeps structured context - message, context name and payload all land in the Logs tab whichever logger the app uses. The Log capture with context tutorial and the Log capture page cover the supported conventions in detail.

Finally, keep the dev files out of the production build and run the dev entry from a TypeScript config that includes them:

tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "exclude": [
    "node_modules",
    "test",
    "dist",
    "**/*spec.ts",
    "src/main-dev.ts",
    "src/app.dev.module.ts",
    "src/profiling/**",
  ],
}
tsconfig.dev.json
{
  "extends": "./tsconfig.json",
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"],
}
package.json
{
  "scripts": {
    "start:dev": "nest start --watch --entryFile main-dev -p tsconfig.dev.json",
  },
}

Step 4 - Make a request and inspect the profile

Start the application with pnpm start:dev, then make any HTTP request:

curl -i http://localhost:3000/health

The response includes two headers:

X-Debug-Token: 550e8400-e29b-...
X-Debug-Token-Link: /_profiler/550e8400-e29b-...

Open http://localhost:3000/_profiler in your browser to see the list of recent profiles. Click a token to open the detail view with tabs:

  • Request - method, URL, headers, query params
  • Response - status code, headers
  • Performance - duration, memory delta
  • Logs - log entries captured during the request
  • Exceptions - errors thrown during the request

Step 5 - Secure the profiler (optional)

The profiler is open by default. Restrict /_profiler/* by providing your own security strategy — an authorize predicate and/or NestJS guards. A minimal bearer-token check:

src/profiling/profiling.module.ts
ProfilerModule.forRoot({
  isGlobal: true,
  security: {
    authorize: ({ request }) =>
      request.headers['authorization'] === `Bearer ${process.env.PROFILER_TOKEN}`,
  },
});
PROFILER_TOKEN=my-dev-secret pnpm start:dev
curl -H "Authorization: Bearer my-dev-secret" http://localhost:3000/_profiler

See Securing the UI for basic-auth, cookie/session and DI-guard recipes.

Production warning

Never enable the profiler in production. It exposes internal request data including headers, query parameters, and logs. With the dev-dependency install above it cannot be: production runs main.ts, which never imports it, and a production install (pnpm install --prod, npm ci --omit=dev) does not even contain it. Check it once — build, install production dependencies only, run node dist/main and confirm /_profiler returns 404.

If your production code calls the profiler and you installed it as a regular dependency, gate it with ConditionalModule and keep it off unless PROFILER_ENABLED=true — see the runtime gate.

Powered & maintained by

On this page