Skip to content
gunkslab

Guides

Record a run and play it back

Keep everything a fleet says during a run in a file, then play it back to watch on the page, or read it as text, to work out what happened. The recorder listens; it never sends anything to the fleet it records.

You need the broker up (scripts/broker up), or a broker that takes logins and a login that may read the fleet.

Record

scripts/record start                  # fleet desk; --fleet lab for another
# ... the run ...
scripts/record stop

The recording is a new file in recordings/, named for the fleet and when it started (UTC): desk-20261022-143245.jsonl. It’s written a message at a time, so a crash or a pulled cable loses nothing already heard. recordings/ is kept out of git.

Everything on the fleet’s topics goes in, as heard: each bot’s hello, status, telemetry, events and the commands it was sent, poses, the station’s summary and notices, the e-stop, and what clients asked the station for. The fleet’s state when recording started (the retained hellos, statuses and e-stop) is the first thing in it.

On a broker that takes logins, the recorder login reads everything. The command is in Run the programs with a login.

Find one

scripts/record list
desk-20261022-143245.jsonl  fleet desk, started 2026-10-22T14:32:45Z, 0:11, 448 messages, bots: sim-1, sim-2

Read it as text

scripts/record show desk-20261022-143245.jsonl                    # everything
scripts/record show desk-20261022-143245.jsonl --topic '*/event'  # every bot's events
scripts/record show desk-20261022-143245.jsonl --topic 'sim-1/*'  # one bot

A line each: seconds since the start, the topic, the message. (retained) marks the state it started from.

Watch it on the page

Playback sends the messages again, at the times they were heard, into another fleet (replay unless --into says otherwise). The page watches that fleet like any other.

scripts/viewer up                     # if it isn't already
scripts/record play desk-20261022-143245.jsonl

Open http://127.0.0.1:8080/?fleet=replay in your browser to watch it.

  • --speed 2 plays it twice as fast; --from 30 --until 90 plays seconds 30 to 90. Started from the middle, it first sends the fleet as it was then (the latest hello, status, telemetry and pose of each bot), so the page isn’t empty until the next message.
  • Ctrl-C stops it.

It refuses to play into the fleet it was recorded on, and into a fleet with anything online or anything live on it. A bot there could act on a played-back command, and a station there would argue with the recording’s. It also refuses when the broker doesn’t accept its login or won’t let it read that fleet, since then it can’t tell. It sends nothing retained, so nothing is left behind when it ends.

On the cluster’s broker, no login may publish to another fleet, so play back on the development broker (scripts/broker up) and point the page at it.

The file

JSON Lines: a header, then a message a line.

{"gunkslab_recording": 1, "protocol": "v0", "fleet": "desk", "started": "2026-10-22T14:32:45Z"}
{"t":0.05,"topic":"sim-1/hello","msg":{"type":"gl-zero", ...},"retained":true}
{"t":0.085,"topic":"sim-1/telemetry","msg":{"up_ms":2305, ...}}

t is seconds since the recording started, topic the part after gunkslab/v0/<fleet>/. A cleared retained message has "msg": null; one that wasn’t JSON keeps its text as "raw". Any tool that reads JSON Lines can take it apart.