diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 41 |
1 files changed, 21 insertions, 20 deletions
@@ -12,52 +12,53 @@ This works only on Linux! ## Demo -A short guided tour with animated GIFs of every major surface lives in [`docs/tutorial/TUTORIAL.md`](./docs/tutorial/TUTORIAL.md). Two teasers: +A short guided tour with animated GIFs of every major surface lives in [`docs/tutorial/tutorial.md`](./docs/tutorial/tutorial.md). Two teasers: + +**Startup — the PID picker:** `sudo ./ior` opens a searchable process list. Navigate with arrow keys, filter by typing, and press `Enter` to start tracing. The dashboard appears immediately after. <img src=docs/tutorial/assets/01-launch.gif width=720 alt="Cold start: PID picker, then the dashboard appears" /> +**Live flamegraph tab:** Once tracing, tab `1` shows a live flamegraph that rebuilds in real time as I/O events arrive. Bars grow and shift with the workload — this is the default landing tab. + <img src=docs/tutorial/assets/13-tui-flamegraph.gif width=720 alt="Live in-TUI flamegraph rebuilding from real workload" /> -The demo is fully reproducible: `mage installDemoTools` once, then `sudo -v && mage demo` regenerates every GIF and screenshot. See the [tutorial](./docs/tutorial/TUTORIAL.md) for the full walkthrough. +The demo is fully reproducible: `mage installDemoTools` once, then `sudo -v && mage demo` regenerates every GIF and screenshot. See the [tutorial](./docs/tutorial/tutorial.md) for the full walkthrough. ## Requirements -- Go 1.26 or newer (ior relies on cgo via libbpfgo). -- Linux with a BTF-enabled kernel (`/sys/kernel/btf/vmlinux` present). +- Docker (for the official build) **or** a Linux host with Go 1.26+, clang, and libbpfgo for native development builds. +- Linux with a BTF-enabled kernel (`/sys/kernel/btf/vmlinux` present) to run `ior`. ## Build -### Docker build (recommended — no toolchain setup required) +The officially supported build method is Docker — no local Go, clang, or libbpfgo setup needed. Native builds are supported for contributors who want to iterate quickly without Docker. -Builds the static `ior` binary inside a Rocky Linux 9 container and writes it -to the repo root. Requires only Docker and a Linux host with tracefs and BTF: +### Docker build (official) + +Builds a fully static `ior` binary inside a Rocky Linux 9 container and writes +it to the repo root: ```shell mage buildDocker ``` -On first run this takes ~15–20 minutes to build the image. Subsequent runs -reuse the cached image and finish in under a minute. To skip the image build: +First run takes ~15–20 minutes to build the image; subsequent runs reuse the +cached image and finish in under a minute. To skip the image rebuild: ```shell ./scripts/build-with-docker.sh --run ``` -### Native build +### Native build (development) -`ior` links against a locally built `libbpfgo`. Clone it as a sibling of this -repo and build the static archive once: +For local development, `ior` links against a locally built `libbpfgo`. Clone it +as a sibling of this repo and build the static archive once: ```shell git clone https://github.com/aquasecurity/libbpfgo ../libbpfgo git -C ../libbpfgo checkout v0.9.2-libbpf-1.5.1 git -C ../libbpfgo submodule update --init --recursive make -C ../libbpfgo libbpfgo-static -``` - -Then build everything: - -```shell mage world ``` @@ -77,8 +78,8 @@ explanation. ## TUI Press **H** inside the dashboard to toggle the built-in help panel. Tabs are -reachable with **tab/shift+tab** or number keys **1–6**. Full hotkey reference: -[docs/tutorial/TUTORIAL.md](./docs/tutorial/TUTORIAL.md#hotkey-quick-reference). +reachable with **tab/shift+tab** or number keys **1–7**. Full hotkey reference: +[docs/tutorial/tutorial.md](./docs/tutorial/tutorial.md#hotkey-quick-reference). ## Recording Modes @@ -92,4 +93,4 @@ reachable with **tab/shift+tab** or number keys **1–6**. Full hotkey reference | Parquet recording | press `R` in TUI, or `-parquet <file>` | streaming Parquet file | Full details and the `.ior.zst` vs Parquet trade-off: -[docs/tutorial/TUTORIAL.md](./docs/tutorial/TUTORIAL.md#recording-for-offline-analysis). +[docs/tutorial/tutorial.md](./docs/tutorial/tutorial.md#recording-for-offline-analysis). |