IOPING(1)

💖 ioping(1) — the manual, but make it make sense 💖

okay bestie, welcome to IOPING, a User Commands classic, and honestly? she's iconic. she generates every I/O pattern you could want and lets you watch your disk's speed and latency in real time like it's a livestream. no cap. 🫶

---

✨ NAME ✨

ioping — simple disk I/O latency monitoring tool

---

🌸 SYNOPSYS 🌸

ioping [-ABCDJLNRWGYykq] [-a count] [-b count] [-c count] [-e seed]
       [-i interval] [-l speed] [-r rate] [-t time] [-T time] [-s size]
       [-S wsize] [-o offset] [-w deadline] [-p period] [-P period]
       [-I [format]] directory|file|device
ioping -h | -v

---

🦋 DESCRIPTION 🦋

so like, this tool generates a whole bunch of different I/O patterns and lets you monitor I/O speed and latency in real time. it's giving observability. it's giving main character energy for your disk. ✨

---

💅 OPTIONS 💅

• -a, -warmup count — skips the first count requests when it's doing statistics, default is 1. why? bc that very first request is usually way slower than the rest (power-saving features waking up and being dramatic 💀). so we just... ignore her.
• -b, -burst count — fires off a series of count requests with no delay between them, default 0. bc aggressive power-saving features can still slow requests down even after a short lil delay. annoying fr.
• -c, -count count — stop after count requests. default 0, which means infinite. she'll go forever, bestie. 😭
• -e, -entropy seed — set the seed for the random number generator. default 0, which means actually random.
• -i, -interval time — set the time between requests, default 1s.
• -l, -speed-limit size — set a speed limit in size per second. it increases the interval to request-size / speed.
• -r, -rate-limit count — set a rate limit in count per second. it increases the interval to 1 / rate.
• -t, -min-time time — the minimal valid request time, default 0us. requests that are too fast get ignored in the statistics. bye girl.
• -T, -max-time time — the maximum valid request time. requests that are too slow also get ignored in the statistics. sorry babe.
• -s, -size size — request size, default 4k.
• -S, -work-size size — working set size. default is 1m for a directory, and the whole size for a file or device.
• -o, -work-offset size — starting offset in the file/device, default 0.
• -w, -work-time time — stop after time has passed, default 0 (infinite). she's immortal by default, periodt.
• -p, -print-count count — print raw statistics for every count requests (see the format below, bestie 👀).
• -P, -print-interval time — print raw statistics every time.
• -A, -async — use asynchronous I/O (io_setup(2), io_submit(2) etc syscalls). fancy.
• -B, -batch — batch mode. be quiet and print the final statistics in raw format. lowkey introvert mode.
• -C, -cached — use cached I/O. this suppresses cache invalidation via posix_fadvise(2) before read and fdatasync(2) after each write.
• -D, -direct — use direct I/O (see O_DIRECT in open(2)).
• -I, -time [format] — print the current time for each request. the optional argument defines the time format in strftime(3) notation, and the default is "%b %d %T" (so like Jan 01 00:00:00).
• -J, -json — print output in JSON format. for the girlies who pipe things into jq 💜
• -L, -linear — use sequential operations instead of random ones. this also sets the default request size to 256k (as in -size 256k).
• -N, -nowait — set RWF_NOWAIT on I/O, which tells the kernel "do not wait if the request cannot be executed immediately" (see RWF_NOWAIT in preadv2(2)). she's impatient and honestly? valid.
• -R, -rapid — disk seek rate test, or a bandwidth test if you use it together with -linear.

this option suppresses human-readable output for each request (like -quiet does), sets the default interval to zero (-interval 0), stops measurement after 3 seconds (-work-time 3) and increases the default working set size to 64m (-work-size 64m). also: the working set (-work-size) should be increased accordingly if the disk has a huge hardware cache. keep that in mind bestie.

• -W, -write — use writes rather than reads. safe for a temporary file in a directory target. write I/O gives more reliable results for systems where non-cached reads aren't supported or are cached at some level.

⚠️ this might be DANGEROUS for a file/device: it will shred your data. in this case it should be repeated three times (-WWW). i am not kidding. she will eat your data. 💀

• -G, -read-write — alternate read and write requests. she can't pick a lane and that's fine.
• -Y, -sync — use sync I/O (see O_SYNC in open(2)).
• -y, -dsync — use data sync I/O (see O_DSYNC in open(2)).
• -k, -keep — keep and reuse the temporary working file "ioping.tmp" (only for a directory target). she's a keeper, literally.
• -q, -quiet — suppress the periodical human-readable output.
• -h, -help — display the help message and exit.
• -v, -version — display the version and exit.

🌈 Argument suffixes 🌈

for options that expect a time argument (-interval, -print-interval and -work-time), the default is seconds, unless you specify one of these suffixes (and they're case-insensitive, we're not gatekeeping):

• ns, nsec — nanoseconds (a billionth of a second, 1 / 1 000 000 000)
• us, usec — microseconds (a millionth of a second, 1 / 1 000 000)
• ms, msec — milliseconds (a thousandth of a second, 1 / 1 000)
• s, sec — seconds
• m, min — minutes
• h, hour — hours

for options that expect a "size" argument (-size, -speed-limit, -work-size and -work-offset), the default is bytes, unless you specify one of these suffixes (also case-insensitive bestie):

• sector — disk sectors (a sector is always 512).
• KiB, k, kb — kilobytes (1 024 bytes)
• page — memory pages (a page is always 4KiB).
• MiB, m, mb — megabytes (1 048 576 bytes)
• GiB, g, gb — gigabytes (1 073 741 824 bytes)
• TiB, t, tb — terabytes (1 099 511 627 776 bytes)

and for options that expect a "number" argument (-count and -print-count) you can optionally specify one of these suffixes (case-insensitive, ofc):

• k — kilo (thousands, 1 000)
• m — mega (millions, 1 000 000)
• g — giga (billions, 1 000 000 000)
• t — tera (trillions, 1 000 000 000 000)

---

🔥 EXIT STATUS 🔥

returns 0 upon success. and the following error codes are defined, so you know exactly what went wrong:

1. invalid usage (error in arguments). skill issue tbh.
2. error during the preparation stage.
3. error during runtime.

---

📊 RAW STATISTICS 📊

ioping -print-count 100 -count 200 -interval 0 -quiet .
99 10970974 9024 36961531 90437 110818 358872 30756 100 12516420
100 9573265 10446 42785821 86849 95733 154609 10548 100 10649035
(1) (2)     (3)   (4)      (5)   (6)   (7)    (8)   (9) (10)

and here's what each lil number is, bestie:

• (1) count of requests in statistics
• (2) running time (nanoseconds)
• (3) requests per second (iops)
• (4) transfer speed (bytes per second)
• (5) minimal request time (nanoseconds)
• (6) average request time (nanoseconds)
• (7) maximum request time (nanoseconds)
• (8) request time standard deviation (nanoseconds)
• (9) total requests (including warmup, too slow or too fast ones)
• (10) total running time (nanoseconds)

---

💜 JSON OUTPUT 💜

with option -J|--json, ioping prints a json array of objects, like so:

[
...
{
  // timestamps
  "timestamp": (unix time in seconds as float),
  "localtime": (local time ISO 8601),

  // io target
  "target": {
    "path": (target path),
    "fstype": (filesystem name),
    "device": (device name),
    "device_size": (device size in bytes)
  },

  // io request
  "io": {
    "request": (request index),
    "operation": (request type: "read" | "write"),
    "size": (request size in bytes),
    "time": (io time in ns),
    "ignored": (ignored in statistics: true | false)
  },

  // statistics
  "stat": {
    "count": (nr reqeusts),
    "size": (total io size in bytes),
    "time": (total io time in ns),
    "iops": (avg iops),
    "bps": (avg rate),
    "min": (min io time in ns),
    "avg": (avg io time in ns),
    "max": (max io time in ns),
    "mdev": (standard deviation in ns)
  },

  // load statistics
  "load": {
    "count": (nr requests),
    "size": (total io size in bytes),
    "time": (total real time in ns),
    "iops": (avg iops),
    "bps": (avg rate)
  },
},
...
]

---

🎀 EXAMPLES 🎀

• ioping . — show disk I/O latency using the default values and the current directory, until you interrupt it. this command prepares a temporary (unlinked/hidden) working file and reads random chunks from it using non-cached read requests. she's sneaky but productive.
• ioping -c 10 -s 1M /tmp — measure latency on /tmp using 10 requests of 1 megabyte each. quick lil vibe check.
• ioping -R /dev/sda — measure disk seek rate.
• ioping -RL /dev/sda — measure disk sequential speed.
• ioping -RLB . | awk '{print $4}' — get disk sequential speed in bytes per second. piping queen 👑
• ioping -J . | jq -r --stream 'fromstream(1|truncate_stream(inputs)) | [.localtime, .io.time/1000000] | @tsv' — select localtime and io time in milliseconds from the json outout.

---

🫶 SEE ALSO 🫶

iostat(1), dd(1), fio(1), stress(1), stress-ng(1), dbench(1), sysbench(1), fsstress, xfstests, hdparm(8), badblocks(8)

---

🌟 HOMEPAGE 🌟

https://github.com/koct9i/ioping/

---

👑 AUTHORS 👑

this program was written by Konstantin Khlebnikov koct9i@gmail.com. the man-page was written by Kir Kolyshkin kir@openvz.org.

---

and that's the whole thing bestie, tysm for reading 🥹💖 this page is from IOPING(1), dated Oct 2014, and it's part of the User Commands section — go forth and measure your I/O latency, you absolute icon. slay ✨💅🦋