nest-profiler

Module optionsCopy Anchor Link

ProfilerModuleOptionsCopy Anchor Link

Options passed to ProfilerModule.forRoot().

ProfilerModuleAsyncOptionsCopy Anchor Link

Options passed to ProfilerModule.forRootAsync().

ProfilerSecurityOptionsCopy Anchor Link

Pluggable access control for the profiler UI/API, passed as the security option. Provide an authorize predicate and/or NestJS guards (all must pass); omit it to leave the profiler open. See Securing the UI.

ProfilerAuthContextCopy Anchor Link

The context passed to a ProfilerAuthorize predicate. ProfilerAuthorize is (context: ProfilerAuthContext) => boolean | Promise<boolean> — return false to deny (the guard throws 401).

Error classificationCopy Anchor Link

What counts as a failure, per entrypoint kind and per collector. See What counts as an error.

ProfilerErrorOptionsCopy Anchor Link

The error option of ProfilerModule.forRoot() (the http kind), and of every package contributing a kind — GraphQLCollectorModule, RabbitMqCollectorModule, EventEmitterCollectorModule.

EntryErrorOptionsCopy Anchor Link

The error option of a collector judging its own entries, such as HttpCollectorModule.forRoot().

ProfileErrorInfoCopy Anchor Link

The view of a profile handed to a classify predicate.

Profile structureCopy Anchor Link

ProfileCopy Anchor Link

Full data structure for a collected profile. The entrypoint field records what triggered it (an HTTP request, a CLI command, a consumed message…).

ProfileEntrypointCopy Anchor Link

The discriminated descriptor of a profile's entrypoint. type identifies the kind ('http', 'command', …) and data holds the kind-specific payload, owned by the package that registered the type.

HttpRequestDataCopy Anchor Link

Payload of the built-in http entrypoint - an HTTP request (REST or GraphQL).

ResponseDataCopy Anchor Link

ResponseStreamDataCopy Anchor Link

PerformanceDataCopy Anchor Link

RouteInfoCopy Anchor Link

SecurityContextCopy Anchor Link

Populated by the Auth collector when request.user is present.

ExceptionEntryCopy Anchor Link

SourceCodeFrameCopy Anchor Link

One parsed frame of an exception's stack, on ExceptionEntry.frames - the application's own code, a dependency and a Node internal alike. lines carries the source excerpt around the frame, and is present only for application frames while sourceContext is on.

SourceCodeLineCopy Anchor Link

TraceSpanCopy Anchor Link

One node of the unified trace on Profile.trace - the single representation of "a piece of work that took time", whatever produced it: the entrypoint itself, a framework phase, an outgoing HTTP call, a database query, a GraphQL field, or a TracerService.span() written by hand. Stored flat and linked by parentId, so it serializes without cycles; the UI rebuilds the tree at render time.

LogEntryCopy Anchor Link

Entrypoint typesCopy Anchor Link

ProfilerEntrypointTypeCopy Anchor Link

Everything the profiler needs to support an entrypoint kind, registered in one call via ProfilerCoreService.registerEntrypointType(): the list-page table, the detail tab(s), the kind-scoped list filters and the breadcrumb summary.

ProfilerDetailTabCopy Anchor Link

A primary detail-page tab contributed by an entrypoint type. Its body is rendered from templatePath (an absolute path to an EJS partial that receives { profile } plus the shared template helpers).

EntrypointSummaryCopy Anchor Link

The compact summary an entrypoint type renders in the detail-page breadcrumb.

LoggingCopy Anchor Link

ProfilerLoggerOptionsCopy Anchor Link

Options accepted by createProfilerLogger(). The default parseArgs implementation, exported as parseLogArgs, understands the NestJS (log(message, context), error(message, stack, context)), pino / nestjs-pino (info(mergingObject, message)) and message-first (log(message, payloadObject)) conventions; pass a custom parseArgs for loggers with an exotic argument convention.

ParsedLogCallCopy Anchor Link

Return value of a LogArgsParser: what the profiler stores for one log call.

ServiceCopy Anchor Link

TracerServiceCopy Anchor Link

Injectable facade. Inject it in any provider or controller to instrument your application: open trace spans, report errors your code caught itself, and read the identifiers of the profile in flight. Every method is a no-op outside a profiled execution - see Trace spans.

TraceSpanDelegateCopy Anchor Link

The handle on an open span, passed to the span() callback and returned by startSpan().

SpanCopy Anchor Link

Method decorator recording a method as one span of the trace, without touching its body. Same nesting and error marking as TracerService.span(), but it leaves return meaning what it means and needs no injection. See Measuring a whole method.

@Span('db.products.findAll')
async findAll(): Promise<Product[]> {
  return this.repo.findAll();
}

createProfilerInstrumentCopy Anchor Link

Builds the instanceDecorator that NestFactory takes through its instrument option (Nest @nestjs/core 11.1.4+). Every provider method call then becomes a span, so the trace carries the full call tree instead of only the spans you opened by hand. Opt-in and development-only: it places a Proxy on every provider instance, a cost paid whether or not the request is profiled. See Recording every method call automatically.

import { createProfilerInstrument } from '@eleven-labs/nest-profiler';

const app = await NestFactory.create(AppModule, {
  instrument: createProfilerInstrument({
    // Classes and methods to keep off the trace: the class, one of its methods, a wildcard, a RegExp.
    exclude: ['ConfigService', 'ClockService.now', '*.getRequestId', /Repository$/],
  }),
});

markInternal(target) opts a provider of your own out of the recording, the same way the profiler's own providers are; isInternal(target) reads that mark back.

TraceContributorCopy Anchor Link

Implemented by a collector that projects its already-collected entries onto the trace, so its queries or outgoing calls appear as spans in the waterfall alongside the ones you opened by hand. entriesToSpans(entries, options) turns a collector's already-timed entries into the RawSpan[] getTraceSpans() must return, without re-timing anything. runAsSpanParent(cls, work) reserves a span id for an entry that wraps work other collectors record; passed back through the id option of entriesToSpans, it nests those entries under the entry's bar.

CollectorsCopy Anchor Link

IProfilerCollectorCopy Anchor Link

Interface to implement when building a custom collector.

CollectorPanelInfoCopy Anchor Link

Panel metadata returned by CollectorRegistry.buildPanels(), passed to EJS templates and the toolbar.

GlobalPanelDescriptorCopy Anchor Link

One sidebar view returned by IProfilerCollector.expandGlobalPanels(), when a scope: 'global' collector splits its snapshot into several views instead of a single panel.

StorageCopy Anchor Link

IProfilerStorageAdapterCopy Anchor Link

Interface for plugging in a custom storage backend.

FileStorageAdapterOptionsCopy Anchor Link

Options for the built-in file-system storage adapter.

Copy helpersCopy Anchor Link

Pure functions backing the profiler UI's "copy" buttons, exported for reuse.

buildCurlCommandCopy Anchor Link

Builds a runnable, multi-line curl command from captured HTTP request data. Relative URLs are made absolute using the host (and x-forwarded-proto) headers.

interpolateSqlCopy Anchor Link

interpolateSql(sql, parameters) inlines bound parameters into a SQL string, returning a runnable query. Supports both $N (Postgres/TypeORM) and ? (MySQL/MikroORM) placeholders.

Optional peersCopy Anchor Link

Helpers for a collector package that works with a library it does not depend on.

loadOptionalPeerCopy Anchor Link

function loadOptionalPeer<T>(
  specifier: string,
  logger?: { warn(message: string): void },
): T | undefined;
function resolveOptionalPeer<T>(specifier: string): OptionalPeer<T>;

Loads an optional peer and tells its three outcomes apart: loaded, absent (not installed — the normal case, and silent), and broken (installed but its own code threw or one of its dependencies is missing). A bare try { require(x) } catch {} reports the last two identically, which turns a broken install into a panel that is silently missing.

loadOptionalPeer returns the exports, or undefined when the package is absent, warning through logger only on the broken case. resolveOptionalPeer returns the tagged OptionalPeer<T> union when you need to branch yourself.

Both recover a subpath a package's exports map refuses to publish — @nestjs/core/package.json from Nest 12 on — by reading it from the package root. For resolving providers rather than modules, see tryResolve.

Client assetsCopy Anchor Link

ClientAssetRegistryCopy Anchor Link

Registry of client-side script bundles the profiler serves same-origin and injects into the page <head>. A package shipping browser behaviour calls register() at startup. See Extending the UI with JavaScript.

Commonly imported symbolsCopy Anchor Link

Everything the entry point exports is public API — see Versioning and stability. This is the shortlist you reach for most often; the sections above document the extension contracts in full.

import {
  ProfilerModule,
  TracerService,
  TraceSpanDelegate,
  Span,
  createProfilerInstrument,
  markInternal,
  entriesToSpans,
  runInSpan,
  runAsSpanParent,
  ProfilerStorageService,
  CollectorRegistry,
  ProfilerCollector,
  HTTP_ICON,
  PROFILER_STORAGE_ADAPTER,
  MemoryStorageAdapter,
  FileStorageAdapter,
  createProfilerLogger,
  parseLogArgs,
  DEFAULT_LOG_METHODS,
  buildCurlCommand,
  interpolateSql,
  loadOptionalPeer,
  resolveOptionalPeer,
  ClientAssetRegistry,
  CORE_CLIENT_SCRIPT,
} from '@eleven-labs/nest-profiler';

import type {
  ProfilerModuleOptions,
  ProfilerModuleAsyncOptions,
  IProfilerCollector,
  IProfilerStorageAdapter,
  FileStorageAdapterOptions,
  MemoryStorageAdapterOptions,
  CollectorPanelInfo,
  GlobalPanelDescriptor,
  Profile,
  ProfileEntrypoint,
  HttpRequestData,
  ResponseData,
  PerformanceData,
  RouteInfo,
  LogEntry,
  ExceptionEntry,
  SourceCodeFrame,
  SourceCodeLine,
  ExceptionCaptureOptions,
  SourceContextOptions,
  StackAnalysisOptions,
  ProfilerEditorName,
  EditorLink,
  LogLevel,
  LogMethodMap,
  LogArgsParser,
  ParsedLogCall,
  ProfilerLoggerOptions,
  TraceSpan,
  TraceSpanKind,
  TraceSpanLane,
  TraceSpanStatus,
  RawSpan,
  TraceContributor,
  ProfilerInstrumentOptions,
  EntrySpanOptions,
  SecurityContext,
  CurlInput,
  OptionalPeer,
  OptionalPeerLogger,
  ClientAssetRegistration,
} from '@eleven-labs/nest-profiler';