Before replaying the entire log, narrow the investigation window.

The Cost Before Investigation

Searching the entire log is recurring work before root-cause analysis begins.

When an autonomous robot issue occurs, replaying the full log, searching topics one by one, and repeatedly aligning timestamps consumes engineering time before the actual cause can even be examined.

As logs grow, this search cost returns with every incident. Failing to narrow the first review range is an expensive use of engineering time.

Ranked Evidence Windows

Choose the review depth needed for the investigation.

The default Quickstart returns the top five timing evidence windows. For a broader investigation view, use --top 10, --top 15, or --top 30 to change the number of results presented for review.

--top controls the number of evidence windows, not their duration. Ranking orders review candidates using observed timing evidence. It is not a root-cause probability or safety-risk score.

Observable Timing Evidence

Observable timing evidence, not a system judgment.

Velune Trace structures timing signals visible in the log. It does not conclude that a signal represents a defect or the cause of an incident.

Quick Test to Real Workflow

Do not take the description on trust. Run the sample.

You can test the ranked evidence-window workflow without providing an internal log or raw MCAP file. After the sample run, replace only the input path to apply the same local workflow to your own MCAP.

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
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

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

Pre-viewer Triage Layer

Velune Trace does not replace your existing viewer.

It is a pre-viewer triage layer that narrows the timestamps and topic ranges worth reviewing before opening Foxglove, PlotJuggler, or an existing analysis workflow.

Core Bundle Comparison v1

Stop replaying two logs side by side. Start with the evidence that changed.

Velune Trace compares two completed and verified Core Report Bundles locally. It structures observed differences in topic sets, timing profiles, and ranked evidence-window summaries so engineers can begin with what changed.

./bin/velune compare-bundles   /path/to/reference_bundle   /path/to/target_bundle   --export-dir comparison_output

A Reference Bundle is not ground truth or a definition of normality. The report presents observed differences only. It does not determine root cause, fault, safety risk, or regression. This is pairwise Core Bundle Comparison, not the complete Private Baseline workflow.

Measured Separately

Initial indexing and post-index retrieval are separate.

In an internal large-scale expansion benchmark, the initial scan and indexing of a 10.7GB log containing 9,237,885 events took approximately 276 seconds. Retrieval of a selected evidence chain after indexing took approximately 0.002 seconds.

This was a synthetic large-scale expansion benchmark. Results depend on hardware, storage, compression, message structure, and dataset characteristics. Initial indexing time and post-index retrieval time are reported separately.

Evidence, Not Judgment

Velune narrows the starting point and leaves judgment open.

Velune Trace performs no automatic raw-log upload, telemetry, or Velune server call. Engineers with system and operational context make the final cause determination.

Private Validation

Validate whether it reduces the starting range in a real operational investigation.

The validation question is deliberately narrow: does evidence-window ranking reduce the time engineers spend searching logs during real autonomous-robot incidents?

Private Validation does not require external upload of a raw MCAP or internal log. Validation can use results produced in the team's local environment and feedback on the existing investigation workflow.