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.4. Validated on Ubuntu 24.04 with Python 3.12; other environments may work but are not claimed.
- Download
velune-trace-v0.5.4.zipandSHA256SUMSfrom the v0.5.4 release into the same directory. - Verify, extract, and install the pinned dependencies:
$ sha256sum -c SHA256SUMS # expect: velune-trace-v0.5.4.zip: OK $ unzip velune-trace-v0.5.4.zip $ cd velune-trace-v0.5.4 $ 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.
You can also install from source with git clone https://github.com/veluneos/velune-trace.git and the same venv steps (requirements.txt is not version-pinned; requirements-lock.txt is). 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 my_report --window-sec 1 --top 10 --allowed-lateness-sec 2
Use a separate --export-dir for each run. If the directory already holds a report, validation-report stops without changing it; add --overwrite to replace the report on purpose.
--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 asexpected_hzandsensor_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 | Machine-readable copy of the report. The name is kept for compatibility; the file is not anonymized |
report_manifest.json | Bundle identity, provenance and SHA-256 integrity metadata |
SCHEMA.md | Description of every report field |
summary.md, evidence_windows.json, topic_profile.json and shareable_anonymous_report.json contain your original topic names and the absolute recording times; summary.md, shareable_anonymous_report.json and report_manifest.json name your source file. None of them contains local paths, user or host names, or credentials. Before any of these files leaves your environment, the data owner must review and approve it. See Data boundaries.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.
compare commands work inside one log. Comparing two separate runs is what VeluneOS Compare is for. Trace is not required for Compare.