Backplane Tracecheck

Check robot recordings against an explicit recording contract.

Tracecheck reads an MCAP recording (the default ROS 2 bag format) and checks it against a small JSON recording contract: which topics must be present, their schemas and encodings, message counts, rates, timestamp gaps, regressions, sequence continuity and time coverage. It produces a JSON report and a readable HTML report. Each finding points to an exact byte offset in the file.

• Free and open source (Apache-2.0).
• Read-only. Message payloads are never decoded or executed.
• No robot, ROS install, account or cloud service needed.
• Streams files of any size. Handles zstd and lz4 chunks safely.
• Runs as a Python CLI or entirely in your browser at backplanerobotics.com/tracecheck, where files never leave your device.

Built by Backplane Robotics.

Install

pip install backplane-tracecheck

Requires Python 3.11+.

Quick start

# Write the synthetic demo recordings and contract to ./examples
tracecheck samples

tracecheck validate-contract examples/demo-contract.json
tracecheck check examples/clean.mcap  --contract examples/demo-contract.json --out reports/clean
tracecheck check examples/faults.mcap --contract examples/demo-contract.json --out reports/faults

# Optional local browser UI (binds to 127.0.0.1 only)
tracecheck serve --open

--out must be a new directory. Existing reports are never overwritten.

Useful options

Exit codes

• 0: overall pass.
• 1: contract failures, warnings or an incomplete scan (all recorded in the report).
• 2: configuration, input or operational error. No report is written.

In the browser

backplanerobotics.com/tracecheck runs the same checks in a Web Worker, using a JavaScript port of the engine in web/src/engine/.

• The file is read locally in slices and never uploaded.
• The site's Content-Security-Policy blocks connections to any other origin.
• For the same inputs, the browser and CLI produce identical JSON reports, apart from timestamps and tool fields. The web test suite checks this.

A minimal contract

{
  "version": 1,
  "name": "My recording requirements",
  "topics": {
    "/my/topic": { "required": true, "min_count": 1 }
  }
}

Start minimal, then read the report's channel inventory to see the actual schema names, encodings and fingerprints. Add only the requirements you can justify. See docs/CONTRACT_REFERENCE.md for every key.

The ten checks

Statuses

• PASS: the configured requirement was met.
• WARN: a scoped limitation, for example message data with no CRC coverage. Default ROS 2 files with chunk CRCs pass.
• FAIL: an unmet requirement or a failed scan. It does not mean the robot is unsafe.
• SKIPPED: no conclusion was reached.

Tracecheck does not certify safety, establish regulatory compliance, determine causality or measure transport latency.

Development

python -m venv .venv
.venv/Scripts/activate        # Windows; use `source .venv/bin/activate` elsewhere
pip install -e ".[dev]"
python -m pytest

After an intentional behaviour change, regenerate the golden results shared by both test suites and review the diff:

tracecheck samples && python tools/make_golden.py

Website (Node 20+):

cd web
npm install
npm test          # engine parity tests against examples/ and the Python engine
npm run dev       # local dev server
npm run build     # static site in web/dist (deploy to Cloudflare Pages)

Repository layout

License

Apache-2.0. See LICENSE and NOTICE. Copyright 2026 Backplane Robotics LLC.