From 1db4e610c260be43123c0ee8ea9e0795fb573009 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Thu, 19 Mar 2026 15:27:02 +0200 Subject: docs: refresh README for current workflow --- README.md | 176 +++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 95 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index e164685..f02ccd9 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,17 @@ -...is an I/O benchmarking tool for Linux based operating systems which captures I/O operations on a (possibly production) server in order to replay the exact same I/O operations on a load test machine. - -I/O Riot is operated in 5 steps: - -1. Capture: Record all I/O operations over a given period of time to a capture log. -2. Initialize: Copy the log to a load test machine and initialize the load test environment. -3. Replay: Drop all OS caches and replay all I/O operations. -4. Analyze: Look at the OS and hardware stats (throughput, I/O ops, load average) from the run phase and draw conclusions. The aim is to identify possible I/O bottlenecks. -5. Repeat: Repeat steps 2-4 multiple times but adjust OS and hardware settings in order to improve I/O performance. +...is an I/O benchmarking tool for Linux systems which captures file-I/O +operations on one host and replays the same workload on another host or test +environment. + +I/O Riot is normally operated in 5 steps: + +1. Capture: Record all I/O operations over a given period of time to a capture log. +2. Generate: Transform the `.capture` log into a `.replay` file with replay-local paths and metadata. +3. Initialize: Create the directory, file, and symlink skeleton required for replay. +4. Replay: Optionally drop caches and replay the recorded workload with configurable worker and thread parallelism. +5. Analyze and repeat: Inspect replay stats and storage behavior, then rerun with different hardware, file-system, or tuning choices. Examples of OS and hardware settings and adjustments: @@ -49,78 +51,90 @@ This is also potentially a great tool just for analysing (not replaying) the I/O Future work will also include file hole support and I/O support for memory mapped files. -# How to install I/O Riot - -I/O Riot depends on SystemTap and a compatible version of the Linux Kernel. To get started have a read through the [installation guide](doc/markdown/installation.md). - -# How to use I/O Riot - -Check out the [I/O Riot usage guide](doc/markdown/usage.md) for a full usage workflow demonstration. - -# Appendix - -## Supported file systems - -Currently I/O Riot supports replaying I/O on ``ext2``, ``ext3``, ``ext4`` and ``xfs``. However, it should be straightforward add additional file systems. - -## Supported syscalls - -Currently, these file I/O related syscalls are supported (as of CentOS 7): - -```code -open -openat -lseek -llseek -fcntl -creat -write -writev -unlink -unlinkat -rename -renameat -renameat2 -read -readv -readahead - Initial support only -readdir -readlink -readlinkat -fdatasync -fsync -sync_file_range - Initial support only -sync -syncfs -close -getdents -mkdir -rmdir -mkdirat -stat -statfs - Initial support only -statfs64 - Initial support only -fstatfs - Initial support only -fstatfs64 - Initial support only -lstat -fstat -fstatat -chmod -fchmodat -fchmod -chown -chown16 -lchown -lchown16 -fchown -fchown16 -fchownat -mmap2 - Initial support only -mremap - Initial support only -munmap - Initial support only -msync - Initial support only -exit_group - To detect process termination (closing all open file handles) -``` +# How to install I/O Riot + +I/O Riot depends on SystemTap and a compatible version of the Linux Kernel. To get started have a read through the [installation guide](doc/markdown/installation.md). + +Once the prerequisites are in place, the normal build and install flow is: + +```bash +make clean all test +sudo make install +``` + +# How to use I/O Riot + +Check out the [I/O Riot usage guide](doc/markdown/usage.md) for a full usage workflow demonstration. + +The current CLI workflow is: + +```bash +# Capture all supported file I/O, or target a specific PID with -x +sudo /opt/ioriot/bin/ioriot -c io.capture [-x PID] + +# Generate a replay file from the capture log +sudo /opt/ioriot/bin/ioriot -c io.capture -r io.replay -u "$USER" -n test1 \ + -w /home/"$USER"/.ioriot-wd + +# Initialize the replay tree +sudo /opt/ioriot/bin/ioriot -i io.replay -w /home/"$USER"/.ioriot-wd + +# Replay the workload +sudo /opt/ioriot/bin/ioriot -r io.replay -S stats.txt +``` + +Notes: + +* Targeted capture (`-x PID`) automatically uses `targetedioriot.ko` unless `-m` overrides the module name. +* Replay data is created under per-test directories such as `/home/.ioriot//...`. +* Captured symlink targets are rewritten to replay-local relative paths, and replay refuses to create symlinks that would resolve outside the corresponding replay tree. + +# Appendix + +## Supported file systems + +Replay path rewriting currently recognizes `ext2`, `ext4`, `xfs`, `zfs`, and +`btrfs` mount points. + +## Supported syscalls + +The generator and replay engine currently support these operations end to end +on the native syscall surface: + +```text +open, openat, creat +close +lseek +fcntl +read, readv, readahead +write, writev +stat, lstat, fstat, fstatat +statfs, fstatfs +readdir, getdents +readlink, readlinkat +rename, renameat, renameat2 +unlink, unlinkat, rmdir +mkdir, mkdirat +fsync, fdatasync, sync, syncfs, sync_file_range +chmod, fchmod, fchmodat +chown, lchown, fchown, fchownat +``` + +Additional legacy compat syscall names are supported when they are captured via +the 32-bit ABI on a compatible host: + +```text +llseek +statfs64, fstatfs64 +chown16, lchown16, fchown16 +``` + +The capture layer also records some mmap-related operations, but they are still +ignored during replay generation: + +```text +mmap2, mremap, munmap, msync +``` ## Source code documentation -- cgit v1.2.3