CPU profiling

When a route is slow but you can't tell where the time goes, a CPU flamegraph answers it: a picture of the call stack over the life of a request, with each frame sized by the time spent in it. Telescope can capture one on demand — arm "profile the next request to this endpoint", hit it, and read the flamegraph in the dashboard — or sample a fraction of traffic automatically. It's built on V8's own inspector profiler, aggregated into a cpu_profile entry that lands in the same batch as the request it profiled.

Turn it on

profiling is a core forRoot option. The minimal form enables the feature for manual triggers only — no request is profiled until you arm a capture, so enabling it this way carries no per-request cost beyond the gate:

import { TelescopeModule } from '@dudousxd/nestjs-telescope';

TelescopeModule.forRoot({
  profiling: { enabled: true }, // manual captures only; sampling stays off
});

To also auto-capture a fraction of traffic, add a sampleRate:

TelescopeModule.forRoot({
  profiling: {
    enabled: true,
    sampleRate: 0.01,           // profile ~1% of requests, uniformly
    maxConcurrent: 1,           // never run two captures at once (default)
    minDurationMs: 50,          // discard captures shorter than 50ms
    samplingIntervalMicros: 500, // finer-grained V8 sampling (default 1000 = 1ms)
  },
});

ProfilingOptions

The two capture modes

Manual (armed). You tell Telescope "profile the next N requests" — optionally only those whose normalized route matches a label like "GET /users/:id". Matching requests consume the budget one at a time until it's exhausted. This is the targeted path: reproduce a slow endpoint, arm one capture against it, and get exactly the flamegraph you want with no sampling noise.

Sampled. With sampleRate > 0, each request has that probability of being auto-captured. Uniform and untargeted — good for catching something slow you didn't anticipate, at a fixed cost budget. Because it's uniform, keep the rate low: at maxConcurrent: 1 an in-flight capture already sheds any concurrent selection, but a high rate still means a steady stream of captures competing for that one slot.

For every selected request the flow is: shouldProfile(route) (cheap gate) → begin(route) starts a V8 profile → the request runs → on finish, end() stops the profiler, aggregates the samples into a flame tree, and records it. The capture runs inside the request's async context, so the resulting cpu_profile entry inherits the active batch and trace context — it correlates to the exact request it profiled. A capture failure can never affect the request it wrapped; a too-short capture (below minDurationMs) is silently dropped.

The headless API

Everything the dashboard does is a plain HTTP call against the mounted API (default mount /telescope, so /telescope/api/...). Reads sit behind the normal read authorizer; arming a capture is a mutation — it incurs real overhead — so it's behind the same default-deny authorizeAction gate as Prune now and request replay.

Arm a capture straight from a script or curl — profile the next 3 hits to one route:

curl -X POST https://your-app/telescope/api/profiles/arm \
  -H 'content-type: application/json' \
  -d '{ "count": 3, "label": "GET /users/:id" }'
# → { "pendingManual": 3 }

The response returns the remaining manual budget across all arms. Omit label to profile the next count requests regardless of route; omit count to arm exactly one.

The dashboard flamegraph view

With profiling enabled the console shows a Profiles tab (hidden otherwise — the nav reads profiling.enabled from status, so an older server that predates the feature simply hides it). From there you can:

What gets stored

A finished capture is recorded as a cpu_profile entry. Crucially, Telescope stores the aggregated flame tree, not the raw per-sample .cpuprofile:

• Each V8 sample's time delta is charged to the self time of the frame it landed on; total time is the frame's self time plus all its descendants', from a single post-order walk. The tree mirrors V8's call graph, so callers nest exactly as they did at runtime.
• The tree is rooted at a synthetic (root) frame; times are in milliseconds (selfMs / totalMs), with sample counts alongside.
• The entry also carries a small precomputed hot list — the hottest frames by self time (with selfPct) — so the dashboard's hot-functions panel doesn't have to walk the tree.

interface CpuProfileContent {
  durationMs: number;            // wall-clock capture duration
  sampleCount: number;           // V8 samples collected
  reason: 'manual' | 'sampled';  // what triggered the capture
  label: string | null;          // route/label, e.g. "GET /users/:id"
  tree: FlameNode;               // aggregated flamegraph (single synthetic root)
  hot: HotFrame[];               // hottest frames by self time, precomputed
}

Overhead, precisely

The whole design is built so the cost is where you asked for it and nowhere else:

• Disabled: shouldProfile returns false after one boolean check; begin returns null. No profiler, no node:inspector, no RNG.
• Enabled, request not selected: the gate plus — only if sampling is on — a single Math.random() call.
• Selected: a V8 sampling profiler runs for that request. Real overhead, which is exactly why captures are capped by maxConcurrent (default 1) and can be floored by minDurationMs. node:inspector is required lazily on the first capture and never before.

This composes with Telescope's other guards — sampling for store volume, overload protection for event-loop pressure — so profiling is a scalpel you pick up deliberately, not a cost you carry by default.