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-clsnestjs-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
TracerServicefor 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:
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:
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:
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);
}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:
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:
{
"extends": "./tsconfig.json",
"exclude": [
"node_modules",
"test",
"dist",
"**/*spec.ts",
"src/main-dev.ts",
"src/app.dev.module.ts",
"src/profiling/**",
],
}{
"extends": "./tsconfig.json",
"exclude": ["node_modules", "test", "dist", "**/*spec.ts"],
}{
"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/healthThe 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:
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/_profilerSee 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.
Tutorials
Step-by-step NestJS profiler tutorials - enable collectors for SQL, HTTP, GraphQL, cache and auth, and build your own custom collector and entrypoint types.
Log capture with context
Wrap your logger so request-scoped logs - with context names and structured payloads - appear in the profiler's Logs tab.