nest-profiler-http

This package owns the HTTP Client panel: the HttpRequestEntry contract, the collector, the injectable HttpProfilerRecorder and the HttpInstrumentation interface. It ships two opt-in adapters — AxiosInstrumentation (/axios) and FetchInstrumentation (/fetch) — each on its own subpath, both capturing request and response bodies safely. You select which client(s) to instrument; nothing is patched unless listed. Any other client (undici, got, a custom module…) can feed the same panel through the recorder or a custom HttpInstrumentation.

Module

HttpCollectorModule

Registers the HTTP Client panel and the HttpProfilerRecorder, then installs the HTTP instrumentations you selected in instrumentations. Import it once with HttpCollectorModule.forRoot(options).

HttpCollectorModuleOptions

Options passed to HttpCollectorModule.forRoot(). They extend the shared HttpCaptureOptions capture/redaction contract with an instrumentations array.

• instrumentations (default []) - the adapters to install, imported from their subpaths (AxiosInstrumentation, FetchInstrumentation) or your own HttpInstrumentation. Nothing is instrumented unless it appears here.

Gate the module with ConditionalModule.registerWhen(HttpCollectorModule.forRoot({ … }), isProfilerEnabled) so it loads only when the profiler is on — the same pattern used for every profiler module.

Recorder

HttpProfilerRecorder

Injectable façade for recording outgoing HTTP requests into the active profile. This is the API to reach for from application code or a custom instrumentation: inject it and call capture with the raw request/response material. Its maskHeaders property exposes the built-in mask list merged with the configured maskHeaders.

capture(input: HttpCaptureInput): void builds an HttpRequestEntry from raw request/response material, honouring the configured HttpCaptureOptions (capture flags) and masking sensitive headers, then records it. This is the recommended entry point - it guarantees a custom client captures the same request/response detail (shown in the panel) as the bundled adapters.

record(entry: HttpRequestEntry): void appends an already-built entry as-is (no capture flags / masking applied) - use it only to bypass the options. Both methods are a no-op outside a CLS context or when no profile is active.

HttpCaptureInput

Raw request/response material handed to capture. Header bags may be plain records, fetch Headers, a Map, or axios AxiosHeaders.

Instrumentations

HttpInstrumentation

Interface to implement when teaching the profiler how to capture requests from a given client. Register implementations via HttpCollectorModule.forRoot({ instrumentations: [MyInstrumentation] }). Implementations are NestJS providers, so they may inject ModuleRef, config, etc. through their constructor.

install(recorder: HttpProfilerRecorder): void | Promise<void> is called once at application bootstrap. Use recorder.capture(...) to push captured requests - it applies the capture options and header masking for you.

This is the extension point for any client without a bundled adapter (got, undici, superagent, a bespoke NestJS service…): hook the client's own API in install so you capture full request and response bodies safely. For a one-off call, inject HttpProfilerRecorder and call capture(...) inline instead. The HTTP client tutorial walks through both patterns with a complete got example.

Each bundled adapter is exported from its own subpath so importing one never loads another's dependency.

AxiosInstrumentation

import { AxiosInstrumentation } from '@eleven-labs/nest-profiler-http/axios';

The bundled axios adapter. It auto-discovers every axios instance in the DI container via DiscoveryService — @nestjs/axios HttpService (including each per-feature HttpModule / HttpModule.register(), which build distinct instances) and bare axios instances — and patches their interceptors. No axiosRef wiring and no @nestjs/axios import; only axios's types are referenced. Instances created outside DI aren't discoverable — record those with a custom instrumentation. Optional peer: axios.

FetchInstrumentation

import { FetchInstrumentation } from '@eleven-labs/nest-profiler-http/fetch';

Patches globalThis.fetch once (Node ≥ 22 built-in). A single global hook captures every caller. Response bodies are read (via Response.clone()) only when captureResponseBody is enabled; request bodies are captured for serialisable init.body (string / URLSearchParams). No dependency.

Types

HttpRequestEntry

One entry per outgoing HTTP request, surfaced in the HTTP Client panel. Client-agnostic by design: the bundled adapters (axios, fetch) produce these, but any client can record the same shape via HttpProfilerRecorder or appendHttpRequestEntry.

HttpCaptureOptions

Capture/redaction flags shared by every instrumentation so they expose the same option surface. HttpCollectorModuleOptions extends it.

Helpers

appendHttpRequestEntry

function appendHttpRequestEntry(cls: ClsService, entry: HttpRequestEntry): void;

Low-level primitive for feeding the HTTP Client panel directly from a ClsService. Reads the active profile from the CLS store and appends the entry; a no-op outside a CLS context or when no profile is active. In application code, prefer the injectable HttpProfilerRecorder - it wraps this and exposes the merged maskHeaders.

Redaction helpers

Client-agnostic header redaction helpers shared by instrumentations.

• DEFAULT_MASK_HEADERS: string[] - built-in list of header names masked by default (authorization, cookie, set-cookie, x-api-key, x-auth-token, proxy-authorization).
• extractHeaders(headers: unknown, maskHeaders: string[]): Record<string, string> - normalises a header bag (a fetch Headers, an axios AxiosHeaders or a plain record) into a flat record, replacing the values of maskHeaders (compared case-insensitively) with [REDACTED]. Pass recorder.maskHeaders to honour the configured mask list.
• formatHeaderValue(value: unknown): string - renders an arbitrary header value as a display string.

Constants

• HTTP_CLIENT_REQUESTS_KEY - the private profile.collectors key where instrumentations accumulate raw HttpRequestEntry items before the collector migrates them to the public http-client key.
• HTTP_COLLECTOR_OPTIONS - DI token for the resolved HttpCollectorModuleOptions, injected by HttpProfilerRecorder.
• HTTP_INSTRUMENTATIONS - DI token for the array of resolved HttpInstrumentation instances.

Public exports

The root barrel is client-agnostic — it exports no adapter. Select adapters from their subpaths.

import {
  HttpCollectorModule,
  HttpProfilerRecorder,
  HttpClientCollector,
  appendHttpRequestEntry,
  DEFAULT_MASK_HEADERS,
  extractHeaders,
  formatHeaderValue,
  HTTP_CLIENT_REQUESTS_KEY,
  HTTP_COLLECTOR_OPTIONS,
  HTTP_INSTRUMENTATIONS,
} from '@eleven-labs/nest-profiler-http';

import type {
  HttpCollectorModuleOptions,
  HttpInstrumentation,
  HttpRequestEntry,
  HttpCaptureOptions,
} from '@eleven-labs/nest-profiler-http';

// Adapters — one per subpath:
import { AxiosInstrumentation } from '@eleven-labs/nest-profiler-http/axios';
import { FetchInstrumentation } from '@eleven-labs/nest-profiler-http/fetch';

Installation

pnpm add @eleven-labs/nest-profiler-http@alpha
# only if you select the axios adapter — your app already owns these:
pnpm add @nestjs/axios axios

Optional peer dependency: axios ^1.0.0 (type-only, used by the /axios adapter). fetch is a Node ≥ 22 built-in and needs no dependency. This package never imports @nestjs/axios — that is your application's dependency.

Setup

Select the client(s) to instrument via instrumentations, importing each adapter from its subpath:

import { ConditionalModule } from '@nestjs/config';
import { HttpCollectorModule } from '@eleven-labs/nest-profiler-http';
import { AxiosInstrumentation } from '@eleven-labs/nest-profiler-http/axios';
import { FetchInstrumentation } from '@eleven-labs/nest-profiler-http/fetch';

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

@Module({
  imports: [
    ConditionalModule.registerWhen(
      HttpCollectorModule.forRoot({
        instrumentations: [AxiosInstrumentation, FetchInstrumentation],
      }),
      isProfilerEnabled,
    ),
  ],
})
export class PostsModule {}

The axios adapter auto-discovers your HttpService instances, so injecting HttpService as usual is enough — no axiosRef wiring. At bootstrap each selected instrumentation installs its hooks and pushes every HttpRequestEntry to the current profile via the HttpProfilerRecorder. The collector registered by HttpCollectorModule renders the panel.