thenodebook.com
Lab 01 / Node Runtime Labs

Node 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 planGet the lab
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.
15Phases
AdvancedDifficulty
0 depsPackage installs
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.

00

Create the project

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

  • 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.
A project shell with package metadata, folders, help output, parsed target data, and strict flag handling.
01

Launch a child Node process

Run a target Node script from the recorder and preserve the child process result.

  • 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.
A parent process wrapper that launches a child Node process and returns the same success or failure result.
02

Capture stdout and stderr

Stream child output through the recorder while keeping byte counts and timestamped previews.

  • 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.
Live output passthrough plus a structured stdio report for stdout and stderr evidence.
03

Record process lifecycle

Capture spawn time, exit time, signal, exit code, and elapsed duration in one lifecycle record.

  • 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.
A lifecycle report with pid, startedAt, exitedAt, exitCode, signal, and elapsedMs.
04

Forward signals

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

  • 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.
A report that shows the full interrupt path from terminal signal to child process shutdown.
05

Add an in-process probe

Inject an ESM preload into the child process and send probe events back to the parent.

  • 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.
A child process that starts with recorder instrumentation and emits a first structured probe event.
06

Measure memory

Sample RSS, heap, external memory, and ArrayBuffer memory from inside the child.

  • 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.
A memory time series that shows Buffer-heavy behavior beyond V8 heap usage.
07

Measure CPU usage

Sample process CPU usage over time and identify the hottest window in the run.

  • 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.
A CPU report that places synchronous CPU pressure next to the rest of the runtime evidence.
08

Measure event loop delay

Measure event loop delay with histogram statistics and sampling drift.

  • 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.
An event loop report that captures delay from synchronous work through histogram data and interval drift.
09

Track active handles

Report active resources that keep the child process alive.

  • 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.
Handle evidence that explains why an otherwise idle child process remained alive.
10

Capture warnings, rejections, and exceptions

Record runtime warnings and failure events while preserving the target program's failure behavior.

  • 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.
Failure evidence with timestamps, stacks, event types, and the original failing child exit result.
11

Add environment and runtime flag support

Pass env files, explicit environment values, NODE_OPTIONS, and extra Node flags into the child.

  • 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.
Startup configuration evidence that explains which runtime flags and environment sources shaped the child.
12

Generate the timeline report

Combine lifecycle, stdio, memory, CPU, event loop delay, warnings, handles, and exit data into one ordered JSON report.

  • 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.
reports/flight.json with one ordered timeline and stable top-level sections for every observed subsystem.
13

Generate HTML and Markdown reports

Render human-readable HTML and Markdown reports from the same JSON data.

  • 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.
HTML and Markdown reports with summary cards, metric sections, timeline evidence, and escaped target output.
14

Compare multiple runs

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

  • 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.
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.

Switch between one-reader pricing and team licenses for up to 25 team members.

Individual pricing is for one reader and one personal purchase record.TEAM LICENSES INCLUDE UP TO 25 MEMBERS. DOWNLOADED CONTENT MAY BE
SHARED INTERNALLY WITH UP TO 30 PEOPLE TOTAL.
Downloadable book bundle

Digital Bundle

Volume I as EPUB, light/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 together

NodeBook Pro

All Labs plus the downloadable Volume I bundle in one purchase. Save $9.99 vs buying separately.

$49.99$99.99
One-time purchase
Node Runtime Labs+Digital Bundle
  • Everything in Node Runtime Labs
  • Everything in the Digital Bundle
  • Seven included lab projects
  • Three upcoming labs when released
  • Future updates for both products
  • Lifetime access to purchased files
Get NodeBook Pro
This includes both paid products: Node Runtime Labs and the Digital Bundle.
Premium labs
Complex runtime projects

Node Runtime Labs

Seven long-form builds: recorder, binary store, stream workbench, resolver, watcher, task runtime, and protocol gateway.

$39.99$79.99
One-time purchase
  • Node Runtime Flight Recorder
  • Binary File Store / Append-Only Log Database
  • Stream Processing Workbench
  • Module Resolution Inspector
  • Atomic File Watcher + Incremental Build Cache
  • Async Task Runtime / Local Job Orchestrator
  • Custom Binary Protocol Gateway
  • Three more labs upcoming
Get Labs Bundle
This is the paid labs bundle. It does not include EPUB, PDFs, slides, or cheatsheets.
Team downloadable files

Digital Bundle Team

Volume I files, slides, cheatsheets, and updates for a small engineering team.

$59.99
One-time team license
  • Everything in the Digital Bundle
  • Supports up to 25 team members
  • Share internally with up to 30 people
  • Single purchase for the team
  • Future Digital Bundle updates
  • Lifetime access to purchased files
Get Team Bundle
Covers up to 25 team members and internal sharing with up to 30 people.
Team value
Everything for the team

NodeBook Pro Team

Node Runtime Labs plus the downloadable Volume I bundle in one team license.

$149.99
One-time team license
Node Runtime Labs+Digital Bundle
  • Everything in NodeBook Pro
  • Supports up to 25 team members
  • Share internally with up to 30 people
  • One receipt and license record
  • Future updates for both products
  • Save $29.99 vs team products separately.
Get Pro Team
Covers up to 25 team members and internal sharing with up to 30 people.
Team labs
Runtime training projects

Node Runtime Labs Team

Seven long-form builds for onboarding, study groups, and internal training.

$119.99
One-time team license
  • Node Runtime Flight Recorder
  • Binary File Store / Append-Only Log Database
  • Stream Processing Workbench
  • Module Resolution Inspector
  • Supports up to 25 team members
  • Share internally with up to 30 people
  • Three more labs upcoming
Get Team Labs
Covers up to 25 team members and internal sharing with up to 30 people.
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.

Node Runtime Flight Recorder Lab | NodeBook Runtime Labs