Docs Install and run Trace

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.

  1. Download velune-trace-v0.5.4.zip and SHA256SUMS from the v0.5.4 release into the same directory.
  2. 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 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

FileContents
summary.mdReadable timing summary and top evidence windows per topic
evidence_windows.jsonRanked windows with count, expected count, max gap and jitter
topic_profile.jsonTopic-level timing profile across the log
shareable_anonymous_report.jsonMachine-readable copy of the report. The name is kept for compatibility; the file is not anonymized
report_manifest.jsonBundle identity, provenance and SHA-256 integrity metadata
SCHEMA.mdDescription of every report field
Review before sharing. The report files contain no raw payloads, but that does not make them anonymous or safe to share. 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

CommandWhat it does
validation-reportFull local evidence report — the recommended starting point
windowed-verifyRank timing-irregular windows for one topic (--topic)
evidence-windowExtract one reproducible window by --start-sec / --end-sec
profileTopic frequency and timing stability
compare / compare-allCompare one or all common topics between two windows of the same log
inspect / chunks / readMCAP 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.