1IOPING(1) User Commands IOPING(1)
2
6 ioping - simple disk I/O latency monitoring tool
7
9 ioping [-ABCDJLNRWGYykq] [-a count] [-b count] [-c count] [-e seed]
10 [-i interval] [-l speed] [-r rate] [-t time] [-T time] [-s size]
11 [-S wsize] [-o offset] [-w deadline] [-p period] [-P period]
12 [-I [format]] directory|file|device
13 ioping -h | -v
14
16 This tool generates various I/O patterns and lets you monitor I/O speed
17 and latency in real time.
18
20 -a, -warmup count
21 Ignore in statistics first count requests, default 1. First
22 request usually is much slower due to power-saving features.
23 -b, -burst count
25 Make series of count requests without delay, default 0.
26 Aggressive power-saving features slow down requests even after
27 short delay.
28 -c, -count count
30 Stop after count requests, default 0 (infinite).
31 -e, -entropy seed
33 Set seed for random number generator, default 0 (random).
34 -i, -interval time
36 Set time between requests, default 1s.
37 -l, -speed-limit size
39 Set speed limit in size per second. Increases interval to
40 request-size / speed.
41 -r, -rate-limit count
43 Set rate limit in count per second. Increases interval to 1 /
44 rate.
45 -t, -min-time time
47 Minimal valid request time (0us). Too fast requests are ignored
48 in statistics.
49 -T, -max-time time
51 Maximum valid request time. Too slow requests are ignored in
52 statistics.
53 -s, -size size
55 Request size, default 4k.
56 -S, -work-size size
58 Working set size (1m for directory, whole size for file or
59 device).
60 -o, -work-offset size
62 Starting offset in the file/device (0).
63 -w, -work-time time
65 Stop after time passed, default 0 (infinite).
66 -p, -print-count count
68 Print raw statistics for every count requests (see format
69 below).
70 -P, -print-interval time
72 Print raw statistics for every time.
73 -A, -async
75 Use asynchronous I/O (io_setup(2), io_submit(2) etc syscalls).
76 -B, -batch
78 Batch mode. Be quiet and print final statistics in raw format.
79 -C, -cached
81 Use cached I/O. Suppress cache invalidation via
82 posix_fadvise(2)) before read and fdatasync(2) after each write.
83 -D, -direct
85 Use direct I/O (see O_DIRECT in open(2)).
86 -I, -time [format]
88 Print current time for each request. Optional argument defines
89 time format in strftime(3) notation, default is "%b %d %T" (Jan
90 01 00:00:00).
91 -J, -json
93 Print output in JSON format.
94 -L, -linear
96 Use sequential operations rather than random. This also sets
97 default request size to 256k (as in -size 256k).
98 -N, -nowait
100 Set RWF_NOWAIT on I/O, indicating to the kernel to do not wait
101 if request cannot be executed immediately. (see RWF_NOWAIT in
102 preadv2(2))
103 -R, -rapid
105 Disk seek rate test, or bandwidth test if used together with
106 -linear.
107 This option suppress human-readable output for each request (as
109 -quiet), sets default interval to zero (-interval 0), stops
110 measurement after 3 seconds (-work-time 3) and increases default
111 working set size to 64m (-work-size 64m). Working set (-work-
112 size) should be increased accordingly if disk has huge hardware
113 cache.
114 -W, -write
116 Use writes rather than reads. Safe for temporary file in
117 directory target. Write I/O gives more reliable results for
118 systems where non-cached reads are not supported or cached at
119 some level.
120 Might be *DANGEROUS* for file/device: it will shred your data.
122 In this case should be repeated three times (-WWW).
123 -G, -read-write
125 Alternate read and write requests.
126 -Y, -sync
128 Use sync I/O (see O_SYNC in open(2)).
129 -y, -dsync
131 Use data sync I/O (see O_DSYNC in open(2)).
132 -k, -keep
134 Keep and reuse temporary working file "ioping.tmp" (only for
135 directory target).
136 -q, -quiet
138 Suppress periodical human-readable output.
139 -h, -help
141 Display help message and exit.
142 -v, -version
144 Display version and exit.
145 Argument suffixes
147 For options that expect time argument (-interval, -print-interval and
148 -work-time), default is seconds, unless you specify one of the
149 following suffixes (case-insensitive):
150 ns, nsec
152 nanoseconds (a billionth of a second, 1 / 1 000 000 000)
153 us, usec
155 microseconds (a millionth of a second, 1 / 1 000 000)
156 ms, msec
158 milliseconds (a thousandth of a second, 1 / 1 000)
159 s, sec seconds
161 m, min minutes
163 h, hour
165 hours
166 For options that expect "size" argument (-size, -speed-limit, -work-
168 size and -work-offset), default is bytes, unless you specify one of the
169 following suffixes (case-insensitive):
170 sector disk sectors (a sector is always 512).
172 KiB, k, kb
174 kilobytes (1 024 bytes)
175 page memory pages (a page is always 4KiB).
177 MiB, m, mb
179 megabytes (1 048 576 bytes)
180 GiB, g, gb
182 gigabytes (1 073 741 824 bytes)
183 TiB, t, tb
185 terabytes (1 099 511 627 776 bytes)
186 For options that expect "number" argument (-count and -print-count) you
188 can optionally specify one of the following suffixes (case-
189 insensitive):
190 k kilo (thousands, 1 000)
192 m mega (millions, 1 000 000)
194 g giga (billions, 1 000 000 000)
196 t tera (trillions, 1 000 000 000 000)
198
200 Returns 0 upon success. The following error codes are defined:
201 1 Invalid usage (error in arguments).
203 2 Error during preparation stage.
205 3 Error during runtime.
207
209 ioping -print-count 100 -count 200 -interval 0 -quiet .
210 99 10970974 9024 36961531 90437 110818 358872 30756 100 12516420
211 100 9573265 10446 42785821 86849 95733 154609 10548 100 10649035
212 (1) (2) (3) (4) (5) (6) (7) (8) (9) (10)
213 (1) count of requests in statistics
215 (2) running time (nanoseconds)
216 (3) requests per second (iops)
217 (4) transfer speed (bytes per second)
218 (5) minimal request time (nanoseconds)
219 (6) average request time (nanoseconds)
220 (7) maximum request time (nanoseconds)
221 (8) request time standard deviation (nanoseconds)
222 (9) total requests (including warmup, too slow or too fast)
223 (10) total running time (nanoseconds)
224
227 With option -J|--json ioping prints json array of objects:
228 [
229 ...
230 {
231 // timestamps
232 "timestamp": (unix time in seconds as float),
233 "localtime": (local time ISO 8601),
234 // io target
236 "target": {
237 "path": (target path),
238 "fstype": (filesystem name),
239 "device": (device name),
240 "device_size": (device size in bytes)
241 },
242 // io request
244 "io": {
245 "request": (request index),
246 "operation": (request type: "read" | "write"),
247 "size": (request size in bytes),
248 "time": (io time in ns),
249 "ignored": (ignored in statistics: true | false)
250 },
251 // statistics
253 "stat": {
254 "count": (nr reqeusts),
255 "size": (total io size in bytes),
256 "time": (total io time in ns),
257 "iops": (avg iops),
258 "bps": (avg rate),
259 "min": (min io time in ns),
260 "avg": (avg io time in ns),
261 "max": (max io time in ns),
262 "mdev": (standard deviation in ns)
263 },
264 // load statistics
266 "load": {
267 "count": (nr requests),
268 "size": (total io size in bytes),
269 "time": (total real time in ns),
270 "iops": (avg iops),
271 "bps": (avg rate)
272 },
273 },
274 ...
275 ]
276
279 ioping .
280 Show disk I/O latency using the default values and the current
281 directory, until interrupted. This command prepares temporary
282 (unlinked/hidden) working file and reads random chunks from it
283 using non-cached read requests.
284 ioping -c 10 -s 1M /tmp
286 Measure latency on /tmp using 10 requests of 1 megabyte each.
287 ioping -R /dev/sda
289 Measure disk seek rate.
290 ioping -RL /dev/sda
292 Measure disk sequential speed.
293 ioping -RLB . | awk '{print $4}'
295 Get disk sequential speed in bytes per second.
296 ioping -J . | jq -r --stream 'fromstream(1|truncate_stream(inputs)) |
298 [.localtime, .io.time/1000000] | @tsv'
299 Select localtime and io time in milliseconds from json outout.
300
302 iostat(1), dd(1), fio(1), stress(1), stress-ng(1), dbench(1),
303 sysbench(1), fsstress, xfstests, hdparm(8), badblocks(8),
304
306 ⟨https://github.com/koct9i/ioping/⟩.
307
309 This program was written by Konstantin Khlebnikov ⟨koct9i@gmail.com⟩.
310 Man-page was written by Kir Kolyshkin ⟨kir@openvz.org⟩.
311 Oct 2014 IOPING(1)