@sonawaneyogesh/live-api-tracer

Zero-config request tracing for Express-shaped apps: see exactly which functions ran for a live API call (as a call tree) and each function's source inlined, with executed lines in light green and unexecuted lines in light red — all on one page, no build step, no report CLI.

const express = require('express');
const { attachTracer } = require('@sonawaneyogesh/live-api-tracer');

const app = express();
attachTracer(app); // that's it — works with ESM or CJS apps, no other setup

app.get('/users/:id', (req, res) => { /* ... */ });

app.listen(3000);

Hit any route, then open GET /__trace/last in a browser — it always renders the most recently captured request.

Works identically from an ESM app:

import express from 'express';
import { attachTracer } from '@sonawaneyogesh/live-api-tracer';

How it works

attachTracer uses Node's built-in inspector module (the Profiler domain) — not nyc, not Istanbul, not the TypeScript compiler. On each request it opens a fresh coverage + CPU-profiling window (Profiler.startPreciseCoverage + Profiler.start), and on res.on('finish') closes it (Profiler.stop + Profiler.takePreciseCoverage), producing:

• A call tree from the CPU profile's real invocation nesting, filtered to your own project source (process.cwd() by default, excluding node_modules).
• Colorized source from the precise coverage ranges: executed lines green, unexecuted lines in touched files red.

The last 20 traces (configurable) are kept in memory; /__trace/last always reflects the most recent one.

Options

attachTracer(app, {
  routePath: '/__trace/last', // where the trace viewer is mounted
  projectRoot: process.cwd(), // root used to decide "your" source vs framework/library internals
  capacity: 20,                // how many recent traces to keep in memory
});

Environment gating

attachTracer only activates when NODE_ENV is one of development, test, staging, or qa. In any other value — including unset, as in a typical production deploy — it no-ops entirely: no inspector session is created, no middleware or route is mounted. Never rely on this as your only safeguard against enabling tracing in production — it's a convenience default, not a security boundary.

Known limitations — please read before relying on this in staging

Traces one request at a time. The Profiler domain is process-global: two truly overlapping in-flight requests can't be captured independently without corrupting each other's coverage/profile data. If a second request arrives while a trace is already in progress, it is served completely normally — no error, no slowdown — it's just not captured; /__trace/last simply won't show it. This is intentional for a low-traffic dev/staging tool used one request at a time. Do not run this expecting every request under real concurrent traffic to be captured.

Call trees come from statistical sampling, not exact instrumentation. Profiler.start/stop is a CPU sampling profiler (tuned to a 100 microsecond interval here, well below V8's 1ms default, specifically to improve odds for short-lived request-scoped traces). Very fast functions can occasionally execute between samples and simply not appear in the call tree, even though they ran. Coverage/coloring is exact — Profiler.takePreciseCoverage is not sampled — only the call tree's nesting is approximate.

Out of scope (see the project spec for the full roadmap)

• Live variable value capture, endpoint-specific targeting, and cross-service tracing are deliberately deferred to later iterations — see docs/live-api-trace-simplified-spec.md.
• Persisting traces to disk — in-memory only, evicts oldest past capacity.
• TypeScript source maps — traced source is shown as executed (compiled) JS, even for TypeScript projects.

Development

npm install
npm run build   # tsc -> dist/
npm test        # builds, then runs the node:test suite
npm run example:cjs   # NODE_ENV must be set, e.g. NODE_ENV=development npm run example:cjs
npm run example:esm

Authored in TypeScript (src/), published as plain compiled JavaScript (dist/) — consumers never need TypeScript installed.