ioping.1

.TH IOPING "1" "Oct 2014" "" "User Commands"
.SH NAME
ioping \- simple disk I/O latency monitoring tool
.SH SYNOPSYS
.SY ioping
.OP \-ABCDEJLNRWGYykq
.OP \-a count
.OP \-b count
.OP \-c count
.OP \-e seed
.OP \-i interval
.OP \-l speed
.OP \-r rate
.OP \-t time
.OP \-T time
.OP \-s size
.OP \-S wsize
.OP \-o offset
.OP \-w deadline
.OP \-p period
.OP \-P period
.OP \-I [format]
.IR directory | file | device
.br
.SY ioping
.B -h
|
.B -v
.br
.SH DESCRIPTION
This tool generates various I/O patterns and lets you monitor I/O speed and
latency in real time.
.SH OPTIONS
.TP
\fB\-a\fR, \fB\-warmup\fR \fIcount\fR
Ignore in statistics first \fIcount\fR requests, default 1.
First request usually is much slower due to power-saving features.
.TP
\fB\-b\fR, \fB\-burst\fR \fIcount\fR
Make series of \fIcount\fR requests without delay, default \fB0\fR (off).
Aggressive power-saving features slow down requests even after short delay.
.TP
\fB\-c\fR, \fB\-count\fR \fIcount\fR
Stop after \fIcount\fR requests, default \fB0\fR (infinite).
.TP
\fB\-e\fR, \fB\-entropy\fR \fIseed\fR
Set seed for random number generator, default \fB0\fR (random).
.TP
\fB\-i\fR, \fB\-interval\fR \fItime\fR
Set \fItime\fR between requests, default \fB1s\fR.
.TP
\fB\-l\fR, \fB\-speed-limit\fR \fIsize\fR
Limit generated load with \fIsize\fR per second.
Increases interval to request-size * burst / speed-limit.
.TP
\fB\-r\fR, \fB\-rate-limit\fR \fIcount\fR
Limit generated load with \fIcount\fR IOPS.
Increases interval to burst / rate.
.TP
\fB\-t\fR, \fB\-min\-time\fR \fItime\fR
Minimal valid request time (\fB0us\fR).
Too fast requests are ignored in statistics.
.TP
\fB\-T\fR, \fB\-max\-time\fR \fItime\fR
Maximum valid request time.
Too slow requests are ignored in statistics.
.TP
\fB\-s\fR, \fB\-size\fR \fIsize\fR
Request size, default \fB4k\fR.
.TP
\fB\-S\fR, \fB\-work\-size\fR \fIsize\fR
Working set size (\fB1m\fR for directory, whole size for file or device).
.TP
\fB\-o\fR, \fB\-work\-offset\fR \fIsize\fR
Starting offset in the file/device (0).
.TP
\fB\-w\fR, \fB\-work\-time\fR \fItime\fR
Stop after \fItime\fR passed, default \fB0\fR (infinite).
.TP
\fB\-p\fR, \fB\-print\-count\fR \fIcount\fR
Print raw statistics for every \fIcount\fR requests (see format below).
.TP
\fB\-P\fR, \fB\-print\-interval\fR \fItime\fR
Print raw statistics for every \fItime\fR.
.TP
\fB\-A\fR, \fB\-async\fR
Use asynchronous I/O (\fBio_setup\fR(2), \fBio_submit\fR(2) etc syscalls).
.TP
\fB\-B\fR, \fB\-batch\fR
Batch mode. Be quiet and print final statistics in raw format.
.TP
\fB\-C\fR, \fB\-cached\fR
Use cached I/O. Suppress cache invalidation via \fBposix_fadvise\fR(2)) before
read and \fBfdatasync\fR(2) after each write.
.TP
\fB\-D\fR, \fB\-direct\fR
Use direct I/O (see \fBO_DIRECT\fR in \fBopen\fR(2)).
.TP
\fB\-E\fR, \fB\-ignore-error\fR
Continue after request failure.
.TP
\fB\-I\fR, \fB\-time\fR \fI[format]\fR
Print current time for each request.
Optional argument defines time format in \fBstrftime\fR(3) notation,
default is "%b %d %T" (Jan 01 00:00:00).
.TP
\fB\-J\fR, \fB\-json\fR
Print output in JSON format.
.TP
\fB\-L\fR, \fB\-linear\fR
Use sequential operations rather than random. This also sets default request
size to \fB256k\fR (as in \fB-size 256k\fR).
.TP
\fB\-N\fR, \fB\-nowait\fR
Set RWF_NOWAIT on I/O, indicating to the kernel to do not wait if request
cannot be executed immediately. (see \fBRWF_NOWAIT\fR in \fBpreadv2\fR(2))
.TP
\fB\-H\fR, \fB\-hipri\fR
Set RWF_HIPRI on I/O. (see \fBpreadv2\fR(2))
.TP
\fB\-R\fR, \fB\-rapid\fR
Disk seek rate test, or bandwidth test if used together with \fB-linear\fR.

This option suppress human-readable output for each request
(as \fB-quiet\fR), sets default interval to zero (\fB-interval 0\fR),
stops measurement after 3 seconds (\fB-work-time 3\fR) and
increases default working set size to 64m (\fB-work-size 64m\fR).
Working set (\fB-work-size\fR) should be increased accordingly if disk has
huge hardware cache.
.TP
\fB\-W\fR, \fB\-write\fR
Use writes rather than reads. Safe for temporary file in directory target.
Write I/O gives more reliable results for systems where non-cached reads are
not supported or cached at some level.
.IP
Might be \fB*DANGEROUS*\fR for file/device: it will shred your data.
In this case should be repeated three times (\fB-WWW\fR).
.TP
\fB\-G\fR, \fB\-read\-write\fR
Alternate read and write requests.
.TP
\fB\-Y\fR, \fB\-sync\fR
Use sync I/O (see \fBO_SYNC\fR in \fBopen\fR(2)).
.TP
\fB\-y\fR, \fB\-dsync\fR
Use data sync I/O (see \fBO_DSYNC\fR in \fBopen\fR(2)).
.TP
\fB\-k\fR, \fB\-keep\fR
Keep and reuse temporary working file "ioping.tmp" (only for directory target).
.TP
\fB\-q\fR, \fB\-quiet\fR
Suppress periodical human-readable output.
.TP
\fB\-h\fR, \fB\-help\fR
Display help message and exit.
.TP
\fB\-v\fR, \fB\-version\fR
Display version and exit.
.SS Argument suffixes
For options that expect time argument (\fB\-interval\fR, \fB\-print-interval\fR and \fB\-work-time\fR),
default is seconds, unless you specify one of the following suffixes
(case-insensitive):
.TP
.BR ns ,\  nsec
nanoseconds (a billionth of a second, 1 / 1 000 000 000)
.TP
.BR us ,\  usec
microseconds (a millionth of a second, 1 / 1 000 000)
.TP
.BR ms ,\  msec
milliseconds (a thousandth of a second, 1 / 1 000)
.TP
.BR s ,\  sec
seconds
.TP
.BR m ,\  min
minutes
.TP
.BR h ,\  hour
hours
.PP
For options that expect "size" argument (\fB\-size\fR, \fB-speed-limit\fR,
\fB\-work-size\fR and \fB\-work-offset\fR),
default is bytes, unless you specify one of the following suffixes
(case-insensitive):
.TP
.B sector
disk sectors (a sector is always 512).
.TP
.BR KiB ,\  k ,\  kb
kilobytes (1 024 bytes)
.TP
.B page
memory pages (a page is always 4KiB).
.TP
.BR MiB ,\  m ,\  mb
megabytes (1 048 576 bytes)
.TP
.BR GiB ,\  g ,\  gb
gigabytes (1 073 741 824 bytes)
.TP
.BR TiB ,\  t ,\  tb
terabytes (1 099 511 627 776 bytes)
.PP
For options that expect "number" argument (\fB-count\fR and \fB-print-count\fR) you
can optionally specify one of the following suffixes (case-insensitive):
.TP
.B k
kilo (thousands, 1 000)
.TP
.B m
mega (millions, 1 000 000)
.TP
.B g
giga (billions, 1 000 000 000)
.TP
.B t
tera (trillions, 1 000 000 000 000)
.SH EXIT STATUS
Returns \fB0\fR upon success. The following error codes are defined:
.TP
.B 1
Invalid usage (error in arguments).
.TP
.B 2
Error during preparation stage.
.TP
.B 3
Error during runtime.
.SH RAW STATISTICS
.B ioping -print-count 100 -count 200 -interval 0 -quiet .
.ad l
.br
\f(CW99 10970974 9024 36961531 90437 110818 358872 30756 100 12516420
.br
100 9573265 10446 42785821 86849 95733 154609 10548 100 10649035
.br
(1) (2)     (3)   (4)      (5)   (6)   (7)    (8)   (9) (10)
.br

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

.SH JSON OUTPUT
With option -J|--json ioping prints json array of objects:
.br
\fB[\fR
.br
\fB...\fR
.br
{
  // 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"),
    "offset": (request offset in bytes),
    "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),
    "failed": (nr failed requests),
    "size": (total io size in bytes),
    "time": (total real time in ns),
    "iops": (avg iops),
    "bps": (avg rate)
  },
.br
},
.br
\fB...\fR
.br
\fB]\fR

.SH EXAMPLES
.TP
.B ioping .
Show disk I/O latency using the default values and the current directory,
until interrupted. This command prepares temporary (unlinked/hidden) working
file and reads random chunks from it using non-cached read requests.
.TP
.B ioping -c 10 -s 1M /tmp
Measure latency on \fB/tmp\fR using 10 requests of 1 megabyte each.
.TP
.B ioping -R /dev/sda
Measure disk seek rate.
.TP
.B ioping -RL /dev/sda
Measure disk sequential speed.
.TP
.B ioping -RLB . | awk '{print $4}'
Get disk sequential speed in bytes per second.
.TP
.B ioping -J . | jq -r --stream 'fromstream(1|truncate_stream(inputs)) | [.localtime, .io.time/1000000] | @tsv'
Select localtime and io time in milliseconds from json outout.
.SH SEE ALSO
.BR iostat (1),
.BR dd (1),
.BR fio (1),
.BR stress (1),
.BR stress-ng (1),
.BR dbench (1),
.BR sysbench (1),
.BR fsstress,
.BR xfstests,
.BR hdparm (8),
.BR badblocks (8),
.BR
.SH HOMEPAGE
.UR https://github.com/koct9i/ioping/
.UE .
.SH AUTHORS
This program was written by Konstantin Khlebnikov
.MT koct9i@gmail.com
.ME .
.br
Man-page was written by Kir Kolyshkin
.MT kir@openvz.org
.ME .