OS-3043 vfsstat man page should live in the same repo as the command

3 files changed, 167 insertions, 0 deletions

diff --git a/manifest b/manifest
index 598525775b..01fa3a3e0d 100644
--- a/manifest
+++ b/manifest
@@ -12184,6 +12184,7 @@ f usr/share/man/man1m/useradd.1m 0444 root bin
 f usr/share/man/man1m/userdel.1m 0444 root bin
 f usr/share/man/man1m/usermod.1m 0444 root bin
 f usr/share/man/man1m/utmpd.1m 0444 root bin
+f usr/share/man/man1m/vfsstat.1m 0444 root bin
 f usr/share/man/man1m/vmstat.1m 0444 root bin
 f usr/share/man/man1m/vndadm.1m 0444 root bin
 f usr/share/man/man1m/vndstat.1m 0444 root bin
diff --git a/usr/src/man/man1m/Makefile b/usr/src/man/man1m/Makefile
index d9d901e7c7..ad0df61c3c 100644
--- a/usr/src/man/man1m/Makefile
+++ b/usr/src/man/man1m/Makefile
@@ -565,6 +565,7 @@ _MANFILES=	6to4relay.1m		\
 		uucleanup.1m		\
 		uusched.1m		\
 		uuxqt.1m		\
+		vfsstat.1m		\
 		vmstat.1m		\
 		vndadm.1m		\
 		vndstat.1m		\
diff --git a/usr/src/man/man1m/vfsstat.1m b/usr/src/man/man1m/vfsstat.1m
new file mode 100644
index 0000000000..702291a19d
--- /dev/null
+++ b/usr/src/man/man1m/vfsstat.1m
@@ -0,0 +1,165 @@
+'\" te
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\" 
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\" Copyright 2014 Joyent, Inc. All rights reserved.
+.\"
+.TH "VFSSTAT" "1m" "May 2014" "" ""
+.
+.SH "NAME"
+\fBvfsstat\fR \-\- Report VFS read and write activity
+.
+.SH "SYNOPSIS"
+.
+.nf
+vfsstat [\-hIMrzZ] [interval [count]]
+.
+.fi
+.
+.SH "DESCRIPTION"
+The vfsstat utility reports a summary of VFS read and write
+activity per zone\.  It first prints all activity since boot, then
+reports activity over a specified interval\.
+.
+.P
+When run from a non\-global zone (NGZ), only activity from that NGZ
+can be observed\.  When run from a the global zone (GZ), activity
+from the GZ and all other NGZs can be observed\.
+.
+.P
+This tool is convenient for examining I/O performance as
+experienced by a particular zone or application\.  Other tools
+which examine solely disk I/O do not report reads and writes which
+may use the filesystem\'s cache\.  Since all read and write system
+calls pass through the VFS layer, even those which are satisfied
+by the filesystem cache, this tool is a useful starting point when
+looking at a potential I/O performance problem\.  The vfsstat
+command reports the most accurate reading of I/O performance as
+experienced by an application or zone\.
+.
+.P
+One additional feature is that ZFS zvol performance is also reported
+by this tool, even though zvol I/O does not go through the VFS
+layer\. This is done so that this single tool can be used to monitor
+I/O performance and because its not unreasonable to think of zvols
+as being included along with other ZFS filesystems\.
+.
+.P
+The calculations and output fields emulate those from iostat(1m)
+as closely as possible\.  When only one zone is actively performing
+disk I/O, the results from iostat(1m) in the global zone and
+vfsstat in the local zone should be almost identical\.  Note that
+many VFS read operations may be handled by the filesystem cache,
+so vfsstat and iostat(1m) will be similar only when most
+operations require a disk access\.
+.
+.P
+As with iostat(1m), a result of 100% for VFS read and write
+utilization does not mean that the VFS layer is fully saturated\.
+Instead, that measurement just shows that at least one operation
+was pending over the last interval of time examined\.  Since the
+VFS layer can process more than one operation concurrently, this
+measurement will frequently be 100% but the VFS layer can still
+accept additional requests\.
+.
+.SH "OUTPUT"
+The vfsstat utility reports the following information:
+.
+.IP "" 4
+.
+.nf
+r/s	reads per second
+
+w/s	writes per second
+
+kr/s	kilobytes read per second
+
+kw/s	kilobytes written per second
+
+ractv	average number of read operations actively being
+		serviced by the VFS layer
+
+wactv	average number of write operations actively being
+		serviced by the VFS layer
+
+read_t	average VFS read latency, in microseconds
+
+writ_t	average VFS write latency, in microseconds
+
+%r	percent of time there is a VFS read operation
+	pending
+
+%w	percent of time there is a VFS write operation
+	pending	
+
+d/s	VFS operations per second delayed by the ZFS I/O
+	throttle
+
+del_t	average ZFS I/O throttle delay, in microseconds
+.
+.fi
+.
+.IP "" 0
+.
+.SH "OPTIONS"
+The following options are supported:
+.
+.P
+\-h	Show help message and exit
+.
+.P
+\-I	Print results per interval, rather than per second (where
+	applicable)
+.
+.P
+\-M	Print results in MB/s instead of KB/s
+.
+.P
+\-r	Show results in a comma\-separated format
+.
+.P
+\-z	Hide zones with no VFS activity
+.
+.P
+\-Z	Print results for all zones, not just the current zone
+.
+.SH "OPERANDS"
+interval
+.
+.P
+Specifies the length in seconds to pause between each interval
+report\.  If not specified, vfsstat will print a summary since boot
+and exit\.
+.
+.P
+count
+.
+.P
+Specifies the number of intervals to report\.  Defaults to
+unlimited if not specified\.
+.
+.SH "SEE ALSO"
+.
+.nf
+iostat(1m), ziostat(1m), mpstat(1m)
+.
+.fi
+.
+.SH "NOTES"
+This command does not examine readdir or any other VFS operations,
+only read and write operations\.
+.
+.P
+This command does not look at network I/O, only I/O operations to
+or from a file\.
+.
+.P
+The output format from vfsstat may change over time; use the
+comma\-separated output for a stable output format\.