Browsing profiles

Every profiled execution receives a unique token and lands in the profiler UI. This page is the reference for the endpoints that expose the collected data, the debug headers that link a response to its profile, the list filters, and how to export a profile.

Profiler UI endpoints

Home page navigation

The home page uses the same two-column layout as the detail page: a sticky left sidebar lists the available views, and the active one is selected server-side from a ?view= query parameter (plain links, no client-side routing — consistent with the profiler's script-src 'self' CSP).

Each entrypoint kind is its own dissociated page under a Profiling group, and every global-scope collector is a view too:

Both sidebars — the home page's views and a profile's tabs — are the same component: the same group headings, the same item padding and the same count-badge scale, with the active item's badge picking up the accent. Each item carries its subject's glyph, and a protocol keeps one glyph wherever it is named: the same globe on Profiling / HTTP and Discover / HTTP, the same GraphQL mark on Profiling / GraphQL and Discover / GraphQL. A section that registers no icon keeps its label aligned with the others.

Views whose collector declares a group (Discover, Schemas) sit under that heading in the sidebar and carry a short label — the panel header restates the group, so Discover / HTTP stays unambiguous. A Discover key is prefixed on purpose: ?view=graphql is the GraphQL profile list, ?view=discover-graphql its routing table.

Most sidebar items carry a count badge: a list section shows its unfiltered profile total, and a global panel shows its own count (the first *Count field its data exposes, e.g. routeCount). A view that counts nothing — Runtime describes a process, it does not enumerate anything — carries none, since a badge reads as a quantity. The ?view= parameter coexists with the list filters, so a filtered link keeps its view: GET /_profiler?view=http&http_method=POST.

Process-wide memory and CPU are a view of their own — Runtime, in the sidebar — rather than a strip above every list. A trend needs an axis made of time, not of traffic: sampling once per profiled request makes idle periods vanish and a burst compress, which is the opposite of what you read a trend for. See CPU and memory.

Every list opens on the same two columns — Time then Duration — before the columns specific to its kind (the collector tables of a profile's detail page follow that same order), and the row itself is the link: clicking anywhere on it opens the profile (ctrl/cmd or middle click opens it in a new tab, Enter follows a focused row). The token is not a column: it identifies the profile in the URL, in the X-Debug-Token header and on the detail page, and repeating a truncated copy on every row only pushed the columns that discriminate one execution from another out of the way.

Debug headers

Every non-profiler request receives response headers:

List filters

Each list (HTTP, GraphQL, Commands…) has its own filter bar and is filtered independently, so query parameters are namespaced by the section key: <section>_<filter>. The HTTP list, for example, uses http_method, http_status…

GET /_profiler?http_method=GET&http_minDuration=100&http_q=/api&http_statusClass=2

The universal filters (available on every list) are:

exception and error answer different questions and are meant to be used together. error asks "what failed?" — a verdict you configure, which by default does not count a 404 even though its NotFoundException was captured. exception asks "show me the NotFoundExceptions", regardless of whether they count as failures. Its options are not a fixed list: they are the values actually present in your store, so each list offers only what it has really seen.

Each entrypoint kind also contributes scoped filters, shown only above its own list — e.g. method (HTTP), operationType (GraphQL, via @eleven-labs/nest-profiler-graphql), commandStatus (Commands). A scoped filter is namespaced like any other: graphql_operationType=mutation.

A kind may also hide a universal filter that is redundant on its own list: the Commands list has no error checkbox, since its commandStatus filter (Success/Failed) already asks exactly that.

Custom list filters

Filters are pluggable. A filter is a ProfilerListFilter — it describes its own control, parses its raw query value and decides whether a profile matches:

import { ProfilerCoreService, ProfilerListFilter } from '@eleven-labs/nest-profiler';

const slowFilter: ProfilerListFilter<boolean> = {
  key: 'slow',
  label: 'Slow only',
  control: 'checkbox',
  // Checked boxes submit '1'; undefined keeps the filter inactive.
  parse: (raw) => (raw ? true : undefined),
  matches: (profile) => (profile.performance.duration ?? 0) >= 500,
};

Register it from a module's onModuleInit (the cross-module path, robust to import order):

core.registerListFilter(slowFilter); // core: ProfilerCoreService

or declaratively via the PROFILER_LIST_FILTERS multi-token:

{ provide: PROFILER_LIST_FILTERS, useValue: slowFilter, multi: true }

Pagination

Each list paginates independently to keep the page light when many profiles are captured. A section shows listPageSize profiles per page (default 25, configurable via ProfilerModule.forRoot({ listPageSize })) with a Previous/Next pager; the pager is hidden when a section fits on one page.

The current page is carried as a section-namespaced query parameter, <section>_page, so sections page independently — and pager links preserve the active filters and the other sections' pages:

GET /_profiler?http_page=2&graphql_page=3&http_status=200

Page numbers are 1-based and clamped to the available range. Submitting a filter bar resets every section back to page 1, since the result set changed.

Exceptions and their causes

The Exceptions tab shows every failure captured for a profile: the ones a route handler threw, the ones a guard or a pipe threw before the interceptor ran, and — for GraphQL — the errors returned inside a 200 envelope.

Each exception also carries its cause chain. throw new InternalServerErrorException('...', { cause: err }) is how a layered application reports a failure, and the cause is usually the half that says what went wrong: the outer exception is what the client is told, the ECONNREFUSED or QueryFailedError underneath is the diagnosis. The tab renders the chain under the exception, one Caused by block per level, each with its own message, code and stack.

The chain is followed to a bounded depth and is cycle-safe, so a wrapped error cannot bloat a stored profile. A machine-readable code is captured whenever the error carries one — Node's ENOENT/ECONNREFUSED, a driver's own code, a GraphQL extensions.code — and it is what the exception list filter groups by, since a class name like GraphQLError discriminates nothing.

Export a profile

Every profile detail page has an Export JSON button. You can also download the raw profile directly:

curl http://localhost:3000/_profiler/{token}/data > profile.json

Copying requests & queries

Inspired by the Symfony Web Profiler, the detail page offers one-click copy buttons that turn a captured operation into something you can paste straight into a terminal or REPL:

Header values that the profiler masks at capture time (e.g. authorization) stay masked in the copied command — the feature is for replaying requests during development, not for exfiltrating secrets.

The cURL and SQL builders are also exported for programmatic use:

import { buildCurlCommand, interpolateSql } from '@eleven-labs/nest-profiler';

buildCurlCommand({
  method: 'POST',
  url: '/users',
  headers: { host: 'localhost:3000' },
  body: { name: 'Ada' },
});
interpolateSql('SELECT * FROM "user" WHERE id = $1', [42]); // → SELECT * FROM "user" WHERE id = 42

Visual tour — the Profiler UI page walks through the profiles list, every built-in tab and every collector panel with screenshots.