Lab 01 · Node Runtime Labs

Runtime flight recorder.

Build a local recorder that launches another Node program, observes the process boundary, injects a small probe when internal data is needed, and writes reports a developer can inspect after the run.

Read the phase plan Get the lab

15Phases

AdvancedDifficulty

0 depsPackage installs

Recorder commandsFlight recorder runbook

01Launch
$ npm run flight -- fixtures/hello.js
Proves the parent runner and child exit path.
02CPU
$ npm run flight -- --sample-ms 100 fixtures/cpu-loop.js
Captures the hot window without extra dependencies.
03Timeout
$ npm run flight -- --timeout-ms 1500 fixtures/hanging-server.js
Turns a stuck process into recorded evidence.
04Report
$ npm run flight -- --html reports/flight.html fixtures/mixed-load.js
Writes the reviewable run report.
05Compare
$ npm run flight -- compare reports/copy.json reports/view.json --markdown reports/comparison.md
Shows how two recordings diverge.

Start with a smoke run, then collect focused reports.

What this lab builds

The finished tool records a real Node run.

Parent process runner

Parse recorder flags, launch another Node script with the same Node binary, preserve exit status, and keep target arguments separate from recorder options.

Signal and stdio evidence

Forward stdout and stderr live, count bytes, keep bounded previews, forward SIGINT/SIGTERM, and record the signal path before the recorder exits.

In-process probe

Inject an ESM preload into the child process when internal runtime counters are needed: memory, CPU, event loop delay, active resources, warnings, rejections, and exceptions.

Reports you can inspect

Write JSON timeline data, focused metric files, HTML and Markdown reports, then compare multiple runs from existing report files.

Complete phase plan

Every phase in Lab 01.

The build starts with command parsing and ends with multi-run comparison. Each phase ships one observable capability and one artifact to inspect.

00Create the projectCreate the CLI shell that accepts a target script path, prints useful help, and rejects invalid recorder flags.

Tasks

Create a private ESM package for Node.js v24 or newer and add the flight npm script.
Separate src, fixtures, reports, and out so implementation files and generated evidence never mix.
Add the CLI entry file, print a short help screen, and treat help as a successful command.
Parse the first non-option argument as the target path while preserving later target arguments.
Normalize one options object with json, html, markdown, env file, Node flags, timeout, and sample interval defaults.
Reject unknown recorder flags with stderr output and a failure exit code.

Artifact

A project shell with package metadata, folders, help output, parsed target data, and strict flag handling.

01Launch a child Node processRun a target Node script from the recorder and preserve the child process result.

Tasks

Copy the hello fixture into the project fixtures directory and verify it under plain Node first.
Move launch logic into a run module so the CLI entry remains small.
Spawn the child with process.execPath so the observed process uses the same Node binary as the recorder.
Listen for error, spawn, and close, then capture pid, exit code, and signal.
Expose the child exit code through the recorder process after async report work has finished.

Artifact

A parent process wrapper that launches a child Node process and returns the same success or failure result.

02Capture stdout and stderrStream child output through the recorder while keeping byte counts and timestamped previews.

Tasks

Add the noisy fixture and verify direct stdout and stderr behavior.
Switch child stdio to pipes so the parent can inspect output chunks before forwarding them.
Forward stdout chunks to process.stdout and stderr chunks to process.stderr without changing the bytes.
Maintain separate byte counters and output events with type, offset, byte length, and capped preview text.
Write reports/stdio.json after the child closes.

Artifact

Live output passthrough plus a structured stdio report for stdout and stderr evidence.

03Record process lifecycleCapture spawn time, exit time, signal, exit code, and elapsed duration in one lifecycle record.

Tasks

Add the exit-code fixture and verify its non-zero status before recording it.
Create lifecycle helpers that start and finish a stable record shape.
Record wall-clock timestamps for humans and monotonic timestamps for duration math.
Set the child pid on spawn and final exit data on close.
Write reports/lifecycle.json even when the observed child exits with a failure code.

Artifact

A lifecycle report with pid, startedAt, exitedAt, exitCode, signal, and elapsedMs.

04Forward signalsForward SIGINT and SIGTERM from the recorder to the child and record the shutdown path.

Tasks

Add a long-running fixture so signal behavior can be observed during an active run.
Track whether the child is still running before sending any signal.
Install parent signal listeners and record the signal received by the recorder.
Start the child in a separate process group on POSIX systems, then forward the signal from the recorder.
Add a kill timeout and force-kill a child that stays alive after the shutdown deadline.
Store parentSignals, forwardedSignals, forceKilled, and final child signal data.

Artifact

A report that shows the full interrupt path from terminal signal to child process shutdown.

05Add an in-process probeInject an ESM preload into the child process and send probe events back to the parent.

Tasks

Add a server fixture that stays alive long enough to prove the probe loaded.
Create src/probe/register.js as an ESM preload with no target application imports.
Insert --import and the probe file URL before the target script path.
Add a bounded --timeout-ms path so long-running fixtures finish during lab checks.
Choose IPC or a sidecar NDJSON file for probe event transport.
Send a probe-ready event with pid, Node version, execArgv, run id, and timeline offset.
Pass probe configuration through FLIGHT_RECORDER_* environment variables.

Artifact

A child process that starts with recorder instrumentation and emits a first structured probe event.

06Measure memorySample RSS, heap, external memory, and ArrayBuffer memory from inside the child.

Tasks

Add the buffer-retention fixture that makes external and ArrayBuffer counters move.
Start an unrefed probe interval controlled by FLIGHT_RECORDER_SAMPLE_MS.
Send rss, heapTotal, heapUsed, external, and arrayBuffers values in bytes.
Collect an initial sample immediately, then sample on the configured interval.
Aggregate peak RSS, heap used, external memory, and ArrayBuffer memory in the parent.
Write reports/memory.json with raw samples and peak summary fields.

Artifact

A memory time series that shows Buffer-heavy behavior beyond V8 heap usage.

07Measure CPU usageSample process CPU usage over time and identify the hottest window in the run.

Tasks

Add the CPU loop fixture and verify it consumes CPU under plain Node.
Take a baseline process.cpuUsage reading at probe startup.
Compute user, system, total microseconds, wall time, and CPU percent for each sample window.
Send cpu-sample events to the parent timeline.
Summarize total CPU time and the hottest sample in reports/cpu.json.

Artifact

A CPU report that places synchronous CPU pressure next to the rest of the runtime evidence.

08Measure event loop delayMeasure event loop delay with histogram statistics and sampling drift.

Tasks

Add the blocking JSON fixture that performs synchronous JSON work.
Create and enable monitorEventLoopDelay from node:perf_hooks inside the probe.
Sample min, max, mean, standard deviation, p50, p95, p99, exceeds, and timer drift.
Reset per-window histogram data while preserving whole-run maxima in the parent.
Write reports/event-loop.json with per-window samples and summary values.

Artifact

An event loop report that captures delay from synchronous work through histogram data and interval drift.

09Track active handlesReport active resources that keep the child process alive.

Tasks

Add a hanging server fixture and run it through the recorder with a timeout.
Use process.getActiveResourcesInfo when available to collect resource type names.
Add guarded private handle inspection for extra class-name diagnostics with redaction.
Classify handles into timer, server, socket, stdio, ipc, and unknown categories.
Capture final handle evidence near timeout before terminating the child.

Artifact

Handle evidence that explains why an otherwise idle child process remained alive.

10Capture warnings, rejections, and exceptionsRecord runtime warnings and failure events while preserving the target program's failure behavior.

Tasks

Add warning, unhandled rejection, and uncaught exception fixtures.
Listen for process warnings inside the probe and serialize name, message, stack, and code.
Listen for unhandledRejection and preserve Error details manually.
Listen for uncaughtException as a short last-chance evidence path.
Keep fatal listeners from converting child failures into successes.
Write warnings and fatal events into a failures section or reports/failures.json.

Artifact

Failure evidence with timestamps, stacks, event types, and the original failing child exit result.

11Add environment and runtime flag supportPass env files, explicit environment values, NODE_OPTIONS, and extra Node flags into the child.

Tasks

Add the environment fixture and sample env file.
Parse --env-file and pass native env-file loading through to the child process.
Parse repeatable --env KEY=value overrides while keeping values with equals signs intact.
Parse repeatable --node-flag entries and place them before the target script path.
Record startup metadata including Node version, exec path, execArgv, runtime flags, env files, and command argv.
Redact environment values for token, secret, password, key, and credential names.

Artifact

Startup configuration evidence that explains which runtime flags and environment sources shaped the child.

12Generate the timeline reportCombine lifecycle, stdio, memory, CPU, event loop delay, warnings, handles, and exit data into one ordered JSON report.

Tasks

Add the mixed-load fixture that combines warnings, output, Buffer retention, and CPU work.
Create a JSON report module separate from process launching and probe collection.
Define schemaVersion, runId, command, node, lifecycle, stdio, memory, cpu, eventLoop, handles, failures, and timeline fields.
Normalize all timeline entries into at, type, source, and data.
Sort by numeric timeline offset while preserving insertion order for ties.
Write reports atomically through a temp file and rename.

Artifact

reports/flight.json with one ordered timeline and stable top-level sections for every observed subsystem.

13Generate HTML and Markdown reportsRender human-readable HTML and Markdown reports from the same JSON data.

Tasks

Create an HTML renderer that consumes the JSON report object.
Show exit status, duration, peak RSS, CPU time, and max event loop delay near the top.
Render stdio, memory, CPU, event loop, warnings, failures, and active handles.
Render a timeline table with offsets, event types, sources, and short summaries.
Create a Markdown renderer for compact review and incident notes.
Escape untrusted child output, warnings, and stack traces before writing HTML.

Artifact

HTML and Markdown reports with summary cards, metric sections, timeline evidence, and escaped target output.

14Compare multiple runsCompare two or more recordings and write a Markdown comparison report.

Tasks

Add fixtures that create different Buffer ownership patterns.
Record each fixture into its own JSON report with the same schema.
Create a compare module that reads existing report files.
Validate schema compatibility before comparing metrics.
Compare duration, peak memory counters, CPU time, max event loop delay, exit status, warnings, and failures.
Rank the largest differences and write reports/comparison.md.

Artifact

A comparison report that turns separate recordings into memory, timing, and correctness deltas.

Runtime evidence

The report surface is part of the build.

Lab 01 treats reports as first-class artifacts: raw metric files, a combined timeline, readable HTML, Markdown for review notes, and a comparison report for multiple recordings.

stdio.jsonstdout/stderr byte totals and previews

lifecycle.jsonspawn, close, signal, and elapsed data

memory.jsonRSS, heap, external, and ArrayBuffer samples

cpu.jsonCPU time windows and hottest sample

event-loop.jsondelay histogram and timer drift

flight.jsonone ordered runtime timeline

flight.htmlhuman-readable run report

comparison.mdmulti-run memory and timing deltas

Choose your
NodeBook package.

Buy a single volume or lock in every volume at once. Switch between one-reader pricing and team licenses for up to 25 members.

Choose volume

Individual pricing is for one reader and one personal purchase record.

Downloadable book bundle

Digital Bundle

Volume I as EPUB, light and dark PDFs, slides, cheatsheets, and future updates.

$19.99$49.99

One-time purchase

Volume I EPUB for offline reading
Light and dark PDF editions
Slide decks for chapter review
Cheatsheets for quick lookup
Future Digital Bundle updates
Lifetime access to the files

Get Digital Bundle

This is the downloadable Volume I study bundle. It does not include Node Runtime Labs.

Best value

Everything for this volume

NodeBook Pro

Volume I Labs plus its downloadable bundle in one purchase. Save $9.99 vs buying the Digital Bundle and Labs separately.

$49.99$99.99

One-time purchase

Node Runtime LabsDigital Bundle

Everything in Node Runtime Labs
Everything in the Digital Bundle
Volume I labs and book bundle
Future updates for both products
Lifetime access to purchased files

Get NodeBook Pro

Includes both paid products for Volume I.

Premium labs

Complex runtime projects

Node Runtime Labs

Volume I long-form builds with checkpoints, hints, debugging notes, and expected output.

$39.99$79.99

One-time purchase

Volume I runtime lab projects
Phase-by-phase build instructions
Checkpoints, hints, and rubrics
Debugging notes and expected output
Reflection questions
Future lab updates

Get Labs Bundle

This is the paid labs bundle for Volume I. It does not include EPUB, PDFs, slides, or cheatsheets.

See complete pricing breakdown

Other labs in the bundle

Lab 01 belongs to the runtime lab set.

The bundle includes seven runtime projects covering process observation, binary storage, streams, module resolution, file watching, async orchestration, and custom protocols.

Lab 02