Velune Trace · open source

Find where to look first.

Velune Trace reads a large MCAP log on your machine and ranks, per topic, the time windows with the most irregular message timing. Open those windows first in Foxglove, PlotJuggler or your own tools — instead of replaying everything.

View on GitHub Quickstart

MIT licensed
Runs locally — no telemetry, no upload
Input: MCAP files

velune validation-report bundled sample.mcap

$ ./bin/velune validation-report examples/sample.mcap \
    --export-dir velune_report --window-sec 1 --top 5
LOCAL_ONLY_NOTICE=No telemetry or automatic upload was performed.

# velune_report/summary.md (condensed)
## /lidar_top   count 99 · expected 20/window
Top evidence windows:
#1 window 2   count 19/20  max_gap 100.0 ms  jitter 11.45 ms
#2 window 0   count 20/20  max_gap  50.0 ms  jitter  0.00 ms
#3 window 1   count 20/20  max_gap  50.0 ms  jitter  0.00 ms

## /imu        count 500 · expected 100/window
#1 window 0   count 100/100  max_gap 10.0 ms  jitter 0.00 ms

Bundled sample, run on Trace v0.5.2 source. Values exact, layout condensed. Ranking is a review order, not a fault probability.

Quickstart

Try it on the sample, then on your own log.

Requires Python 3.12. The sample run needs no internal data.

Install from source

Clone the repository and install the two dependencies (mcap, zstandard) into a virtual environment.

git clone https://github.com/veluneos/velune-trace.git
cd velune-trace
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the sample

Generate a small synthetic MCAP and produce a local report.

python3 tools/create_sample_mcap.py
./bin/velune validation-report examples/sample.mcap \
  --export-dir velune_report \
  --window-sec 1 \
  --top 5 \
  --allowed-lateness-sec 2

Run on your MCAP

Replace the input path. Use --top 10, 15 or 30 for a deeper review queue; it changes how many windows are listed, not their length.
```
./bin/velune validation-report /path/to/your_log.mcap \
  --export-dir velune_report --window-sec 1 --top 10 --allowed-lateness-sec 2
```
Open velune_report/summary.md

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

Versions. The repository's main branch carries Trace v0.5.2. The latest packaged GitHub release is v0.5.1 (ZIP and SHA256SUMS). Full instructions: INSTALL.md.

What you get

Local, reproducible evidence files.

Nothing is uploaded and the source log is not modified.

summary.md

Human-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 whole log.

shareable_anonymous_report.json

An optional report designed to avoid raw sensor payloads, for sharing outside your environment.

report_manifest.json

Bundle identity, provenance and SHA-256 integrity metadata.

SCHEMA.md

Description of every report field.

CLI

Nine commands, one job: narrow the search.

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

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

Measured separately

Index once. Retrieve evidence quickly afterwards.

In an internal benchmark on a synthetic 10.7 GB log with 9,237,885 events, the repository's indexer built its index in about 276 seconds; retrieving a related evidence chain afterwards took about 0.002 seconds.

Input

10.7 GB

synthetic benchmark log

Initial index build

≈ 276 s

full first scan

Post-index retrieval

≈ 0.002 s

one evidence-chain query

Synthetic benchmark on one development machine, measured with the indexer component (benchmark record). Results depend on hardware, storage, compression and message structure. The first-scan time and the post-index query time are different measurements.

Boundaries

A starting point, not a conclusion.

Trace does

Read MCAP files entirely on your machine
Profile per-topic message timing
Rank windows by observed gaps, jitter, count shortfall and ordering
Write reproducible Markdown and JSON with integrity hashes

Trace does not

Replace MCAP, rosbag2, Foxglove or your viewer
Determine root cause, fault or safety risk
Tell you whether a window is normal or abnormal
Send telemetry or upload your logs

Comparing a run before and after a change?

Trace narrows one log. VeluneOS Compare shows what changed between two runs.

Get Trace on GitHub See VeluneOS Compare