Docs / Velune Trace

Install and run Velune Trace

Trace reads one MCAP log on your machine and ranks, per topic, the time windows with the most irregular message timing. It sends no telemetry and uploads nothing.

Install from the release

The latest packaged release is v0.5.1. Validated on Ubuntu 24.04 with Python 3.12; other environments may work but are not claimed.

Download velune-trace-v0.5.1.zip and SHA256SUMS from the v0.5.1 release into the same directory.
Verify, extract, and install the pinned dependencies:

$ sha256sum -c SHA256SUMS            # expect: velune-trace-v0.5.1.zip: OK
$ unzip velune-trace-v0.5.1.zip
$ cd velune-trace-v0.5.1
$ python3 -m venv .venv
$ .venv/bin/pip install -r requirements-lock.txt
$ ./bin/velune --help

./bin/velune uses ./.venv/bin/python automatically when it exists. To use another interpreter, set VELUNE_PYTHON=/path/to/python.

The repository's main branch carries v0.5.2 (install from source with git clone https://github.com/veluneos/velune-trace.git, then the same venv steps using requirements.txt). The full instructions ship in the archive as release/INSTALL.md.

Try it on the bundled sample

$ .venv/bin/python tools/create_sample_mcap.py
created examples/sample.mcap
$ ./bin/velune validation-report examples/sample.mcap \
    --export-dir velune_report --window-sec 1 --top 5 --allowed-lateness-sec 2
…
LOCAL_ONLY_NOTICE=No telemetry or automatic upload was performed.
LOCAL_OUTPUTS_NOTICE=All report files were written locally. Review velune_report/summary.md first.

Open velune_report/summary.md. For the sample, the top window for /lidar_top is window 2 (count 19 of an expected 20, max gap 0.1 s).

Run on your own log

$ ./bin/velune validation-report /path/to/your_log.mcap \
    --export-dir velune_report --window-sec 1 --top 10 --allowed-lateness-sec 2

--window-sec — window length in seconds.
--top — how many windows to list per topic (for example 10, 15 or 30). It changes the length of the review queue, not the window length.
--allowed-lateness-sec — how long a window stays open for late, out-of-order messages before it is finalized.
--topic-profile — optional JSON with topic metadata such as expected_hz and sensor_category; without it, the expected count is inferred from the observed median.

Then open the listed windows in your existing viewer and investigate there.

Output files

File	Contents
`summary.md`	Readable timing summary and top evidence windows per topic
`evidence_windows.json`	Ranked windows with count, expected count, max gap and jitter
`topic_profile.json`	Topic-level timing profile across the log
`shareable_anonymous_report.json`	Optional report designed to leave out raw sensor payloads. Review it before sharing; it still describes your topics and timing.
`report_manifest.json`	Bundle identity, provenance and SHA-256 integrity metadata
`SCHEMA.md`	Description of every report field

Commands

Command	What it does
`validation-report`	Full local evidence report — the recommended starting point
`windowed-verify`	Rank timing-irregular windows for one topic (`--topic`)
`evidence-window`	Extract one reproducible window by `--start-sec` / `--end-sec`
`profile`	Topic frequency and timing stability
`compare` / `compare-all`	Compare one or all common topics between two windows of the same log
`inspect` / `chunks` / `read`	MCAP metadata, chunk index, and reading a selected chunk or time window

Run ./bin/velune --help for examples. Set VELUNE_DEBUG=1 for debugging output.

Trace's compare commands work inside one log. Comparing two separate runs is what VeluneOS Compare is for. Trace is not required for Compare.