Velune Trace · 오픈소스

먼저 볼 곳을
찾으세요.

Velune Trace는 대용량 MCAP 로그를 내 컴퓨터에서 읽고, topic별로 메시지 타이밍이 가장 불규칙한 시간 구간을 순서대로 정리합니다. 전체를 재생하는 대신 그 구간부터 Foxglove, PlotJuggler, 기존 도구에서 여세요.

GitHub에서 보기 Quickstart

MIT 라이선스
로컬 실행 — telemetry·업로드 없음
입력: MCAP 파일

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

번들 샘플을 Trace v0.5.2 소스로 실행. 값은 그대로, 배치만 압축. 순위는 검토 순서이며 결함 확률이 아닙니다.

Quickstart

샘플로 먼저, 그다음 내 로그로.

Python 3.12가 필요합니다. 샘플 실행에는 내부 데이터가 필요 없습니다.

소스에서 설치

저장소를 clone하고 가상환경에 두 개의 의존성(mcap, zstandard)을 설치합니다.

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

샘플 실행

작은 합성 MCAP을 만들고 로컬 리포트를 생성합니다.

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

내 MCAP으로 실행

입력 경로만 바꾸세요. --top 10, 15, 30으로 검토 목록을 늘릴 수 있습니다. 구간의 길이가 아니라 나열되는 구간의 개수가 바뀝니다.
```
./bin/velune validation-report /path/to/your_log.mcap \
  --export-dir velune_report --window-sec 1 --top 10 --allowed-lateness-sec 2
```
velune_report/summary.md 열기

나열된 구간을 기존 viewer에서 열고 그곳에서 조사하세요.

버전. 저장소의 main 브랜치는 Trace v0.5.2입니다. 가장 최근에 패키징된 GitHub 릴리스는 v0.5.1 (ZIP, SHA256SUMS)입니다. 전체 설치 안내: INSTALL.md.

출력

로컬에, 재현 가능한 evidence 파일로.

아무것도 업로드되지 않으며 원본 로그는 수정되지 않습니다.

summary.md

topic별 타이밍 요약과 상위 evidence window.

evidence_windows.json

메시지 수, 기대 메시지 수, 최대 gap, jitter가 포함된 순위별 구간.

topic_profile.json

로그 전체에 대한 topic 단위 타이밍 프로파일.

shareable_anonymous_report.json

원본 센서 payload를 포함하지 않도록 설계된 공유용 선택 리포트.

report_manifest.json

번들 식별자, provenance, SHA-256 무결성 메타데이터.

SCHEMA.md

모든 리포트 필드에 대한 설명.

CLI

9개의 명령, 하나의 목적: 탐색 범위 줄이기.

명령	기능
`validation-report`	전체 로컬 evidence 리포트 — 권장 시작점
`windowed-verify`	한 topic에서 타이밍이 불규칙한 구간 순위화
`evidence-window`	시작·끝 시각으로 재현 가능한 evidence window 하나 추출
`profile`	topic 빈도와 타이밍 안정성
`compare` / `compare-all`	한 로그 안의 두 시간 구간 사이에서 하나 또는 모든 공통 topic 비교
`inspect` / `chunks` / `read`	MCAP 메타데이터, chunk 인덱스, 선택한 chunk·시간 구간 읽기

Trace의 compare 명령은 한 로그 안의 구간을 비교합니다. 서로 다른 두 실행을 비교하는 것은 VeluneOS Compare의 역할입니다.

분리 측정

한 번 인덱싱하고, 이후 evidence는 빠르게.

9,237,885개 이벤트가 담긴 합성 10.7 GB 로그에 대한 내부 벤치마크에서, 저장소의 indexer는 약 276초 만에 인덱스를 만들었고 이후 관련 evidence chain 조회는 약 0.002초가 걸렸습니다.

입력

10.7 GB

합성 벤치마크 로그

최초 인덱스 생성

≈ 276 s

전체 첫 스캔

인덱스 이후 조회

≈ 0.002 s

evidence chain 조회 1회

개발 장비 한 대에서 indexer 컴포넌트로 측정한 합성 벤치마크입니다 (벤치마크 기록). 결과는 하드웨어, 스토리지, 압축, 메시지 구조에 따라 달라집니다. 최초 스캔 시간과 인덱스 이후 조회 시간은 서로 다른 측정입니다.

경계

결론이 아니라 시작점.

Trace가 하는 일

MCAP 파일을 전부 내 컴퓨터에서 읽기
topic별 메시지 타이밍 프로파일링
관측된 gap, jitter, 메시지 수 부족, 순서 차이로 구간 순위화
무결성 해시가 포함된 재현 가능한 Markdown·JSON 작성

Trace가 하지 않는 일

MCAP, rosbag2, Foxglove 등 viewer 대체
근본 원인, 결함, 안전 위험 판단
구간이 정상인지 비정상인지 판정
telemetry 전송이나 로그 업로드

변경 전후의 실행을 비교하시나요?

Trace는 로그 하나의 범위를 줄입니다. VeluneOS Compare는 두 실행 사이에 무엇이 달라졌는지 보여줍니다.

GitHub에서 Trace 받기 VeluneOS Compare 보기

먼저 볼 곳을찾으세요.