Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ZPOOL-IOSTAT(8)		FreeBSD	System Manager's Manual	       ZPOOL-IOSTAT(8)

     zpool-iostat -- display logical I/O statistics for	ZFS storage pools

     zpool iostat [[[-c	SCRIPT]	[-lq]]|-rw] [-T	u|d] [-ghHLnpPvy]
	   [poola||[pool vdeva|]|vdeva|] [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, statis-
     tics 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 dis-
     played periodically.  If count is specified, the command exits after
     count reports are printed.	 The first report printed is always the	sta-
     tistics 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, Ga| that are printed in the report	are in base
     1024.  To get the raw values, use the -p flag.

     -c	[SCRIPT1[,SCRIPT2]a|]
	     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 vari-
	     able.  A privileged user can only run -c if they have the
	     ZPOOL_SCRIPTS_AS_ROOT environment variable	set.  If a script re-
	     quires 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 col-
	     umn 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
	     VDEV_PATH		  Full path to the vdev
	     VDEV_UPATH		  Underlying path to the vdev (/dev/sd*).  For
				  use with device mapper, multipath, or	parti-
				  tioned 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 de-
	     tach/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

     -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 in-
	     cludes histograms of individual I/O (ind) and aggregate I/O
	     (agg).  These stats can be	useful for observing how well I/O ag-
	     gregation 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	prior-
				ity queues.  Does not include disk time.
	     asyncq_wait	Amount of time I/O spent in asynchronous pri-
				ority 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
	     disk_wait		Average	disk I/O time (time reading/writing
				the disk).
	     syncq_wait		Average	amount of time I/O spent in synchro-
				nous priority queues.  Does not	include	disk
	     asyncq_wait	Average	amount of time I/O spent in asynchro-
				nous priority queues.  Does not	include	disk
	     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 pri-
				ority queues.
	     asyncq_read/write	Current	number of entries in asynchronous pri-
				ority 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	mea-
	     surements will be sampled from the	end of the interval.

     iostat(1),	smartctl(8), zpool-list(8), zpool-status(8)

FreeBSD	13.0			 May 27, 2021			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help