Home

node-red-contrib-flight-recorder

A flight recorder for Node-RED flows. The debug sidebar shows you the present; this shows you the moments leading up to a failure.

Each recorder keeps a rolling recording of recent messages — who sent them, when, how far apart, and what they carried — and emits that recording as a structured incident when you ask for it, when a node in scope reports an error, or when a message matches a watermark condition. With persistence enabled, the recording survives crashes and restarts, which is the part that truly earns the name.

Like real flight recorders, the nodes are orange.

The four nodes

recorder (flight-recorder) — an inline recorder you drop onto a wire. Traffic passes through untouched, always; the recording happens on the side. See Recorder Node.

recorder tap (flight-recorder-tap) — an ambient recorder that observes messages flowing through other nodes via Node-RED's messaging hooks, without touching their wires. Point it at flows, node ids, or node types; drop one on a dedicated tab and you have a black box for the whole runtime. See Recorder Tap Node.

recorder control (flight-recorder-control) — the cockpit panel. An input-only node targeting one recorder; wire inject buttons into it to issue commands, and receive a receipt per command. See Recorder Control Node.

recorder report (flight-recorder-report) — the post-mortem archiver. Renders incidents as readable reports (text, Markdown, or self-contained HTML), to the message and/or to dated files on disk, with an optional raw-JSON evidence companion. See Recorder Report Node.

Install

cd ~/.node-red
npm install node-red-contrib-flight-recorder

Restart Node-RED. The nodes appear in the function category of the palette.

Start here

Use Import → Examples → node-red-contrib-flight-recorder and work through the examples in order:

1. Simple Inline — drop a recorder on a wire, press dump, read the report. Two minutes.
2. Simple Tap — a flow that doesn't know it's being watched; error reports appear hands-free.
3. Full Demo — watermarks, cockpit controls, pause/mark/mute, everything at once.
4. Home Assistant — incidents as HA notifications and a dashboardable incident counter (requires the HA websocket palette; setup steps in the flow's tab info).

The Getting Started page walks through the first two with annotated output.

Core principles

These are contracts, not aspirations — each is enforced by the test suite:

• Passthrough is sacred. The inline recorder forwards the original message object untouched, no matter what. Pausing stops the tape, never the flow. No recording problem may ever block or mutate traffic.
• Nothing invisible. Messages dropped while paused are counted. Suppressed auto-dumps emit events. Mutes lay marks on the tape and count what they silence. Commands acknowledge.
• Recorders never record recorders. The whole family is hard-excluded from every tap scope, unconditionally.
• Evidence is never destroyed. Dumps don't clear the tape, file collisions get suffixes instead of overwrites, and retention only ever touches files the report node itself created.
• Sequence numbers are monotonic forever — across buffer wraps, clears, and restarts — so records are globally orderable.

Documentation

Page	What's there
Getting Started	Guided walkthrough of the simple examples
Recorder Node	Inline recorder reference
Recorder Tap Node	Tap reference: scope, muting, auto error dumps
Recorder Control Node	Control reference: commands and receipts
Recorder Report Node	Report reference: formats, files, retention
Commands	The full command vocabulary in one place
Data Formats	Incident, record, envelope, and persist-file JSON reference

Current version: 0.2.0. License: Apache-2.0.