Getting Started

This page walks through the two simple examples. Each takes a couple of minutes and teaches one idea; together they cover most of what you'll use day to day.

Before you start: one settings tweak

The Node-RED debug sidebar truncates displayed strings at 1000 characters by default, and flight recorder reports are longer than that. The report is always complete — only the display is cut — but you'll have a much better time if you raise the limit first. In your settings.js (typically ~/.node-red/settings.js), set:

debugMaxLength: 10000,

and restart Node-RED. Alternatively, use file output on the report node and read reports from disk.

Walkthrough 1: Simple Inline

Import it via Import → Examples → node-red-contrib-flight-recorder → Simple Inline and deploy.

What's on the canvas: an inject fires every 3 seconds into a recorder, which forwards each message untouched to a (disabled) debug. The recorder's incidents output feeds a report node into an active debug. Below, a single dump inject wired to a control node targeting the recorder.

Watch the recorder's status: ● 4/12, ● 5/12… — the recording filling toward its capacity of 12. Once past 12 it stays at 12/12; the oldest record is evicted for each new one (the tape "wraps"), but sequence numbers keep climbing forever.

Press dump. In the debug sidebar:

════════════════════════════════════════════ ...
 FLIGHT RECORDER INCIDENT · MANUAL
════════════════════════════════════════════ ...
 store      frsimple1.recorder
 incident   7f37a4e8
 at         2026-07-13 19:57:19
 runtime    node-red-contrib-flight-recorder@0.2.0 · Node-RED 4.x · node v22.x · host yourbox

 12 records · span 33.0s · median gap 3.0s
 wraps 1 · truncated 0 · dropped while paused 0
──────────────────────────────────────────── ...
  SEQ    +TIME     GAP   SOURCE                        PAYLOAD
──────────────────────────────────────────── ...
    2     0.0s    3.0s   recorder [flight-recorder]    1783987005544
    3     3.0s    3.0s   recorder [flight-recorder]    1783987008544
    ...

Reading it: the header says what triggered this and when; the stats say how much tape and what normal looks like (median gap 3.0s — matching the inject interval); the timeline is one line per record, with time relative to the first record and the gap since the previous capture.

Two things worth understanding here:

Every source reads recorder [flight-recorder]. That's expected for the inline node — it captures at its own input and can't know which node sent the message (Node-RED doesn't pass sender identity on a wire). Sources become genuinely informative in tap mode, which is walkthrough 2.

The traffic never noticed. Enable the "traffic out" debug and you'll see the original messages flowing regardless of anything the recorder does — passthrough is sacred, and pausing the recorder (try it from the Full Demo's cockpit later) stops only the tape.

Walkthrough 2: Simple Tap

Import Simple Tap and deploy. Then just wait about ten seconds.

What's on the canvas: the top row is a plain flow — inject → a worker function that errors every 5th message → debug. Nothing recorder-related is wired into it. Below sits a tap scoped to this tab with auto-error dump enabled, feeding a report node.

When the worker's 5th message errors, this appears in the sidebar without you touching anything:

 FLIGHT RECORDER INCIDENT · ERROR
 ...
 cause      "something went wrong (simulated)"
            from: worker (errors every 5th) [function]
 ...
  SEQ    +TIME     GAP   SOURCE                        PAYLOAD
    1     0.0s       —   every 2s [inject]             1783987...
    2     0.0s    0.0s   worker (errors every 5th)...  {"value":42,"run":1}
    3     2.0s    2.0s   every 2s [inject]             1783987...
    ...

This is the product's core idea in one screen: the flow being recorded has no idea it's being watched, the error's cause and source are front and center, and the timeline shows the messages leading up to the failure — with real source attribution, because the tap's hooks know which node emitted each message.

Notice the gaps: the worker rows normally trail the inject rows by 0.0s, but after each swallowed error there's a 4-second gap in the worker's cadence — the recorder telling the truth about a missing message. Large anomalous gaps (≥ 3× the median) get flagged with ⚠ automatically.

The tap fires at most one automatic incident per 10 seconds here (the cooldown); a dump command would bypass that — manual requests always fire.

Where next

The Full Demo example adds the cockpit (pause/resume/mark/mute/query buttons), a watermark that auto-dumps on payload.temp > 90, and both recorder types side by side. From there:

• Commands — everything you can ask a recorder to do
• Recorder Report Node — writing reports to files, with raw-JSON evidence pairs and retention
• Recorder Tap Node — scope configuration and per-channel muting