ebpf-syscall

Observe real storage IO at the layer where it actually happens — syscalls, io_uring, mmap page faults, and NVMe device commands — and turn those captures into things you can look at (Perfetto timelines) and reproduce (fio replays). The recurring idea across every tool here is the two-witness join: the application knows intent (what it asked for), the kernel or device knows mechanism (what actually moved), and the interesting number is the gap between them.

These pages are the reStructuredText build of the project’s case studies, so they are searchable and viewable anywhere. Each one also has a dark-themed standalone HTML version — richer to look at, identical in content — served under /showcase/ below and reachable via htmlpreview from the repository’s docs/*.html.

Case studies

• kvio GPU-free KV-cache-offload storage-IO projector & replayer
  • What it is
  • How it works
  • The cross-layer trace_id join
  • Components
  • Dependencies
  • How to run
  • Fidelity metrics
  • Validated results
• The QD~1 KV-load bottleneck found with eBPF, fixed with parallel loads
  • The symptom
  • The wire evidence
  • Why this matters — the crossover turns on it
  • Reproduce it
  • The fix
  • End to end, in a live serving stack
  • See it — the crossover on one timeline
  • What’s left — honest status
• kvio × Perfetto see every KV object and every NVMe command on one timeline
  • Why a converter is the only way in
  • Quickstart
  • What the timeline shows
  • The metrics report (P4 pack)
  • Trace schema (what the producers emit)
  • SQL cookbook (trace_processor)
• A GNN reads 431× more off the SSD than it needs — watch it, then replay it without the data
  • The gap between two witnesses
  • The A/B: naive access vs the architectural fix
  • What the Perfetto timeline shows
  • Capture a confidential workload, share only the shape
  • Reproduce it
  • Where the pieces live

Tools

• NVMe io_uring_cmd DMA-mapping matrix

Styled showcase pages

The standalone dark-themed pages (same content, rich figures) are served straight from this build:

• kvio — GPU-free KV-offload IO projector and replayer

• kvio load path — the QD~1 case study

• kvio × Perfetto — cross-layer KV-offload introspection

• GNN read amplification — see it, replay it without the data

• hardware-model visualization (an interactive plot; it stays HTML rather than reStructuredText)

Reproduce

Every case study has a reproduce recipe under tools/reproduce/ in the repository, and the tracers, converters, and replay tools it uses are described in CLAUDE.md. The GNN read-amplification recipe (tools/reproduce/gnn-readamp/) is the worked end-to-end example: capture with eBPF, chart the A/B on Perfetto, and replay from a data-free fio iolog.