zpool-iostat —
display logical I/O statistics for ZFS storage
pools
| zpool |
iostat
[[[-c
SCRIPT]
[-lq]]|-rw]
[-T
u|d]
[-ghHLnpPvy]
[pool…|[pool
vdev…]|vdev…]
[interval
[count]] |
Displays logical I/O statistics for the given pools/vdevs. Physical I/O
statistics may be observed via
iostat(1). If
writes are located nearby, they may be merged into a single larger operation.
Additional I/O may be generated depending on the level of vdev redundancy. To
filter output, you may pass in a list of pools, a pool and list of vdevs in
that pool, or a list of any vdevs from any pool. If no items are specified,
statistics for every pool in the system are shown. When given an
interval, the statistics are printed every
interval seconds until killed. If
-n flag is specified the headers are displayed
only once, otherwise they are displayed periodically. If
count is specified, the command exits after
count reports are printed. The first report
printed is always the statistics since boot regardless of whether
interval and
count are passed. However, this behavior can
be suppressed with the
-y flag. Also note that
the units of
K,
M,
G… that are printed in the report are in
base 1024. To get the raw values, use the
-p
flag.
-
-c
[SCRIPT1[,SCRIPT2]…]
- Run a script (or scripts) on each vdev and include the
output as a new column in the zpool
iostat output. Users can run any script found
in their ~/.zpool.d directory or from the
system /etc/zfs/zpool.d directory. Script
names containing the slash (/) character are
not allowed. The default search path can be overridden by setting the
ZPOOL_SCRIPTS_PATH environment variable. A
privileged user can only run -c if they have
the ZPOOL_SCRIPTS_AS_ROOT environment
variable set. If a script requires the use of a privileged command, like
smartctl(8), then it's recommended you allow
the user access to it in /etc/sudoers or add
the user to the /etc/sudoers.d/zfs file.
If -c is passed without a script name, it
prints a list of all scripts. -c also sets
verbose mode
(-v).
Script output should be in the form of "name=value". The column
name is set to "name" and the value is set to "value".
Multiple lines can be used to output multiple columns. The first line of
output not in the "name=value" format is displayed without a
column title, and no more output after that is displayed. This can be
useful for printing error messages. Blank or NULL values are printed as a
'-' to make output AWKable.
The following environment variables are set before running each script:
- VDEV_PATH
- Full path to the vdev
- VDEV_UPATH
- Underlying path to the vdev
(/dev/sd*). For use with device mapper,
multipath, or partitioned vdevs.
- VDEV_ENC_SYSFS_PATH
- The sysfs path to the enclosure for the vdev (if
any).
-
-T
u|d
- Display a time stamp. Specify
u for a printed representation of the
internal representation of time. See time(2).
Specify d for standard date format. See
date(1).
- -g
- Display vdev GUIDs instead of the normal device names.
These GUIDs can be used in place of device names for the zpool
detach/offline/remove/replace commands.
- -H
- Scripted mode. Do not display headers, and separate fields
by a single tab instead of arbitrary space.
- -L
- Display real paths for vdevs resolving all symbolic links.
This can be used to look up the current block device name regardless of
the /dev/disk/ path used to open it.
- -n
- Print headers only once when passed
- -p
- Display numbers in parsable (exact) values. Time values are
in nanoseconds.
- -P
- Display full paths for vdevs instead of only the last
component of the path. This can be used in conjunction with the
-L flag.
- -r
- Print request size histograms for the leaf vdev's I/O. This
includes histograms of individual I/O (ind) and aggregate I/O (agg). These
stats can be useful for observing how well I/O aggregation is working.
Note that TRIM I/O may exceed 16M, but will be counted as 16M.
- -v
- Verbose statistics Reports usage statistics for individual
vdevs within the pool, in addition to the pool-wide statistics.
- -y
- Normally the first line of output reports the statistics
since boot: suppress it.
- -w
- Display latency histograms:
- total_wait
- Total I/O time (queuing + disk I/O time).
- disk_wait
- Disk I/O time (time reading/writing the disk).
- syncq_wait
- Amount of time I/O spent in synchronous priority
queues. Does not include disk time.
- asyncq_wait
- Amount of time I/O spent in asynchronous priority
queues. Does not include disk time.
- scrub
- Amount of time I/O spent in scrub queue. Does not
include disk time.
- -l
- Include average latency statistics:
- total_wait
- Average total I/O time (queuing + disk I/O time).
- disk_wait
- Average disk I/O time (time reading/writing the
disk).
- syncq_wait
- Average amount of time I/O spent in synchronous
priority queues. Does not include disk time.
- asyncq_wait
- Average amount of time I/O spent in asynchronous
priority queues. Does not include disk time.
- scrub
- Average queuing time in scrub queue. Does not include
disk time.
- trim
- Average queuing time in trim queue. Does not include
disk time.
- -q
- Include active queue statistics. Each priority queue has
both pending (pend) and active
(activ) I/O requests. Pending requests are
waiting to be issued to the disk, and active requests have been issued to
disk and are waiting for completion. These stats are broken out by
priority queue:
- syncq_read/write
- Current number of entries in synchronous priority
queues.
- asyncq_read/write
- Current number of entries in asynchronous priority
queues.
- scrubq_read
- Current number of entries in scrub queue.
- trimq_write
- Current number of entries in trim queue.
All queue statistics are instantaneous measurements of the number of entries
in the queues. If you specify an interval, the measurements will be
sampled from the end of the interval.
iostat(1),
smartctl(8),
zpool-list(8),
zpool-status(8)