Overview

@eleven-labs/nest-profiler

@eleven-labs/nest-profiler provides execution profiling for NestJS applications. Each profiled execution receives a unique token, and the collected data (request, response, performance, logs, exceptions, custom collectors) can be inspected at /_profiler/{token}.

Installation

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

There is no stable release yet — install every @eleven-labs/nest-profiler* package with the @alpha dist-tag (@latest resolves to nothing).

nestjs-cls is a required peer dependency used for per-execution context propagation.

Want the profiler in devDependencies only, with zero production footprint? Install it with pnpm add -D @eleven-labs/nest-profiler@alpha nestjs-cls and use the dev-entry split instead of the runtime gate below.

Quick start

The recommended way to wire the profiler is to gate it with Nest's ConditionalModule.registerWhen, so it loads only when you want it:

import { Module } from '@nestjs/common';
import { ProfilerModule } from '@eleven-labs/nest-profiler';
import { ConditionalModule } from '@nestjs/config';

const isProfilerEnabled = (env: NodeJS.ProcessEnv) => env['PROFILER_ENABLED'] === 'true';

@Module({
  imports: [
    ConditionalModule.registerWhen(
      ProfilerModule.forRoot({ isGlobal: true, maxProfiles: 100 }),
      isProfilerEnabled,
    ),
  ],
})
export class AppModule {}

Start the application, make a few requests, and open http://localhost:3000/_profiler. Every non-profiler response also carries an X-Debug-Token-Link header pointing straight to its profile.

If a service injects ProfilerService directly (custom startSpan, events, exceptions…), also register ProfilerNoopModule.forRoot({ isGlobal: true }) gated on (env) => !isProfilerEnabled(env) so that injection still resolves when off. Log capture never needs it — createProfilerLogger is DI-free. A top-level enabled option is also supported as an alternative, documented once in Configuration → Enabling and disabling the profiler.

Documentation

Each capability has its own focused guide:

The Getting started guide covers the full setup including the optional collector packages (TypeORM, MikroORM, Mongoose, Axios, cache, auth, config, validator, GraphQL, commander), and the Profiler UI page gives a visual tour of every panel.

Public API

import {
  ProfilerModule,
  ProfilerNoopModule,
  ProfilerService,
  NoopProfilerService,
  ProfilerStorageService,
  ProfilerViewsSetup,
  CollectorRegistry,
  ProfilerCollector,
  TimelineCollector,
  ClientAssetRegistry,
  PROFILER_STORAGE_ADAPTER,
  MemoryStorageAdapter,
  FileStorageAdapter,
  createProfilerLogger,
  parseLogArgs,
  DEFAULT_LOG_METHODS,
} from '@eleven-labs/nest-profiler';

import type {
  ProfilerModuleOptions,
  ProfilerModuleAsyncOptions,
  IProfilerCollector,
  IProfilerStorageAdapter,
  StorageFindOptions,
  CollectorPanelInfo,
  Profile,
  LogEntry,
  ExceptionEntry,
  TimelineSpan,
  SecurityContext,
  LogMethodMap,
  LogArgsParser,
  ParsedLogCall,
  ProfilerLoggerOptions,
} from '@eleven-labs/nest-profiler';

The full generated reference lives at API reference — nest-profiler.