diff options
Diffstat (limited to 'upstream/debian-unstable/man1/iostat.1')
| -rw-r--r-- | upstream/debian-unstable/man1/iostat.1 | 479 |
1 files changed, 479 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/iostat.1 b/upstream/debian-unstable/man1/iostat.1 new file mode 100644 index 00000000..f7e45e29 --- /dev/null +++ b/upstream/debian-unstable/man1/iostat.1 @@ -0,0 +1,479 @@ +.\" iostat manual page - (C) 1998-2020 Sebastien Godard (sysstat <at> orange.fr) +.TH IOSTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- +.SH NAME +iostat \- Report Central Processing Unit (CPU) statistics and input/output +statistics for devices and partitions. + +.SH SYNOPSIS +.ie 'yes'no' \{ +.B iostat [ \-c ] [ \-d ] [ \-h ] [ \-k | \-m ] [ \-N ] [ \-s ] [ \-t ] [ \-V ] [ \-x ] [ \-y ] [ \-z ] +.BI "[ \-\-compact ] [ \-\-dec={ 0 | 1 | 2 } ] [ { \-f | +f } " "directory" " ] [ \-j { ID | LABEL | PATH | UUID | ... } ] " +.BI "[ \-o JSON ] [ [ \-H ] \-g " "group_name " "] [ \-\-human ] [ \-\-pretty ] [ \-p [ " "device" "[,...] | ALL ] ] [" +.IB "device " "[...] | ALL ] [ \-\-debuginfo ] [ " "interval " "[ " "count " "] ] " +.\} +.el \{ +.B iostat [ \-c ] [ \-d ] [ \-h ] [ \-k | \-m ] [ \-N ] [ \-s ] [ \-t ] [ \-V ] [ \-x ] [ \-y ] [ \-z ] +.BI "[ \-\-compact ] [ \-\-dec={ 0 | 1 | 2 } ] [ { \-f | +f } " "directory" " ] [ \-j { ID | LABEL | PATH | UUID | ... } ] " +.BI "[ \-o JSON ] [ [ \-H ] \-g " "group_name " "] [ \-\-human ] [ \-\-pretty ] [ \-p [ " "device" "[,...] | ALL ] ] [" +.IB "device " "[...] | ALL ] [ " "interval " "[ " "count " "] ]" +.\} + +.SH DESCRIPTION +.RB "The " "iostat" +command is used for monitoring system input/output device +loading by observing the time the devices are active in relation +to their average transfer rates. The +.B iostat +command generates reports +that can be used to change system configuration to better balance +the input/output load between physical disks. +.PP +The first report generated by the +.B iostat +command provides statistics +concerning the time since the system was booted, unless the +.B \-y +option is used (in this case, this first report is omitted). +Each subsequent report +covers the time since the previous report. All statistics are reported +each time the +.B iostat +command is run. The report consists of a +CPU header row followed by a row of +CPU statistics. On +multiprocessor systems, CPU statistics are calculated system-wide +as averages among all processors. A device header row is displayed +followed by a line of statistics for each device that is configured. +.PP +The +.I interval +parameter specifies the amount of time in seconds between +each report. The +.IR "count " "parameter can be specified in conjunction with the " "interval" +.RI "parameter. If the " "count " "parameter is specified, the value of " "count" +.RI "determines the number of reports generated at " "interval " "seconds apart. If the" +.IR "interval " "parameter is specified without the " "count " "parameter, the" +.B iostat +command generates reports continuously. + +.SH REPORTS +The +.B iostat +command generates two types of reports, the CPU +Utilization report and the Device Utilization report. + +.IP "CPU Utilization Report" +The first report generated by the +.B iostat +command is the CPU Utilization Report. For multiprocessor systems, the CPU values are +global averages among all processors. +The report has the following format: +.RS +.IP %user +Show the percentage of CPU utilization that occurred while +executing at the user level (application). +.IP %nice +Show the percentage of CPU utilization that occurred while +executing at the user level with nice priority. +.IP %system +Show the percentage of CPU utilization that occurred while +executing at the system level (kernel). +.IP %iowait +Show the percentage of time that the CPU or CPUs were idle during which +the system had an outstanding disk I/O request. +.IP %steal +Show the percentage of time spent in involuntary wait by the virtual CPU +or CPUs while the hypervisor was servicing another virtual processor. +.IP %idle +Show the percentage of time that the CPU or CPUs were idle and the system +did not have an outstanding disk I/O request. +.RE +.PP +.IP "Device Utilization Report" +The second report generated by the +.B iostat +command is the Device Utilization Report. +The device report provides statistics on a per physical device +or partition basis. Block devices and partitions for which statistics are +to be displayed may be entered on the command line. +If no device nor partition is entered, then statistics are displayed +for every device used by the system, and +providing that the kernel maintains statistics for it. +If the +.B ALL +keyword is given on the command line, then statistics are +displayed for every device defined by the system, including those +that have never been used. +Transfer rates are shown in 1K blocks by default, unless the environment +variable +.B POSIXLY_CORRECT +is set, in which case 512-byte blocks are used. +The report may show the following fields, depending on the flags used (e.g. +.BR "\-x" ", " "\-s " "and " "\-k " "or " "\-m" "):" +.RS +.IP Device: +This column gives the device (or partition) name as listed in the +.IR "/dev " "directory." +.IP tps +Indicate the number of transfers per second that were issued +to the device. A transfer is an I/O request to the +device. Multiple logical requests can be combined into a single I/O +request to the device. A transfer is of indeterminate size. +.IP "Blk_read/s (kB_read/s, MB_read/s)" +Indicate the amount of data read from the device expressed in a number of +blocks (kilobytes, megabytes) per second. Blocks are equivalent to sectors +and therefore have a size of 512 bytes. +.IP "Blk_wrtn/s (kB_wrtn/s, MB_wrtn/s)" +Indicate the amount of data written to the device expressed in a number of +blocks (kilobytes, megabytes) per second. +.IP "Blk_dscd/s (kB_dscd/s, MB_dscd/s)" +Indicate the amount of data discarded for the device expressed in a number of +blocks (kilobytes, megabytes) per second. +.IP "Blk_w+d/s (kB_w+d/s, MB_w+d/s)" +Indicate the amount of data written to or discarded for the device expressed +in a number of blocks (kilobytes, megabytes) per second. +.IP "Blk_read (kB_read, MB_read)" +The total number of blocks (kilobytes, megabytes) read. +.IP "Blk_wrtn (kB_wrtn, MB_wrtn)" +The total number of blocks (kilobytes, megabytes) written. +.IP "Blk_dscd (kB_dscd, MB_dscd)" +The total number of blocks (kilobytes, megabytes) discarded. +.IP "Blk_w+d (kB_w+d, MB_w+d)" +The total number of blocks (kilobytes, megabytes) written or discarded. +.IP r/s +The number (after merges) of read requests completed per second for the device. +.IP w/s +The number (after merges) of write requests completed per second for the device. +.IP d/s +The number (after merges) of discard requests completed per second for the device. +.IP f/s +The number (after merges) of flush requests completed per second for the device. +This counts flush requests executed by disks. Flush requests are not tracked for partitions. +Before being merged, flush operations are counted as writes. +.IP "sec/s (kB/s, MB/s)" +The number of sectors (kilobytes, megabytes) read from, written to or +discarded for the device per second. +.IP "rsec/s (rkB/s, rMB/s)" +The number of sectors (kilobytes, megabytes) read from the device per second. +.IP "wsec/s (wkB/s, wMB/s)" +The number of sectors (kilobytes, megabytes) written to the device per second. +.IP "dsec/s (dkB/s, dMB/s)" +The number of sectors (kilobytes, megabytes) discarded for the device per second. +.IP rqm/s +The number of I/O requests merged per second that were queued to the device. +.IP rrqm/s +The number of read requests merged per second that were queued to the device. +.IP wrqm/s +The number of write requests merged per second that were queued to the device. +.IP drqm/s +The number of discard requests merged per second that were queued to the device. +.IP %rrqm +The percentage of read requests merged together before being sent to the device. +.IP %wrqm +The percentage of write requests merged together before being sent to the device. +.IP %drqm +The percentage of discard requests merged together before being sent to the device. +.IP areq\-sz +The average size (in kilobytes) of the I/O requests that were issued to the device. +.br +Note: In previous versions, this field was known as avgrq\-sz and was expressed in sectors. +.IP rareq\-sz +The average size (in kilobytes) of the read requests that were issued to the device. +.IP wareq\-sz +The average size (in kilobytes) of the write requests that were issued to the device. +.IP dareq\-sz +The average size (in kilobytes) of the discard requests that were issued to the device. +.IP await +The average time (in milliseconds) for I/O requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP r_await +The average time (in milliseconds) for read requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP w_await +The average time (in milliseconds) for write requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP d_await +The average time (in milliseconds) for discard requests issued to the device +to be served. This includes the time spent by the requests in queue and +the time spent servicing them. +.IP f_await +The average time (in milliseconds) for flush requests issued to the device +to be served. +The block layer combines flush requests and executes at most one at a time. +Thus flush operations could be twice as long: Wait for current flush request, +then execute it, then wait for the next one. +.IP aqu\-sz +The average queue length of the requests that were issued to the device. +.br +Note: In previous versions, this field was known as avgqu\-sz. +.IP %util +Percentage of elapsed time during which I/O requests were issued to the device +(bandwidth utilization for the device). Device saturation occurs when this +value is close to 100% for devices serving requests serially. +But for devices serving requests in parallel, such as RAID arrays and +modern SSDs, this number does not reflect their performance limits. +.RE + +.SH OPTIONS +.TP +.B \-c +Display the CPU utilization report. +.TP +.B \-\-compact +Don't break the Device Utilization Report into sub-reports so that all the metrics get displayed +on a single line. +.TP +.B \-d +Display the device utilization report. +.if 'yes'no' \{ +.TP +.B \-\-debuginfo +Print debug output to stderr. +.\} +.TP +.B \-\-dec={ 0 | 1 | 2 } +Specify the number of decimal places to use (0 to 2, default value is 2). +.TP +.BI "\-f " "directory" +.RE +.BI "+f " "directory" +.RS +Specify an alternative directory for +.B iostat +to read devices statistics. Option +.BR "\-f " "tells " "iostat " "to use only the files located in the alternative directory, " +whereas option +.B +f +tells it to use both the standard kernel files and the files located in the alternative directory +to read device statistics. + +.IR "directory" " is a directory containing files with statistics for devices managed in userspace." +It may contain: + +- a "diskstats" file whose format is compliant with that located in "/proc", +.br +- statistics for individual devices contained in files whose format is compliant with that of files located in +"/sys". + +In particular, the following files located in +.I "directory" +.RB "may be used by " "iostat" ":" + +.IR "directory" "/block/" "device" "/stat" +.br +.IR "directory" "/block/" "device" "/" "partition" "/stat" + +.IR "partition" " files must have an entry in " "directory" "/dev/block/ directory, e.g.:" + +.IR "directory" "/dev/block/" "major" ":" "minor" " --> ../../block/" "device" "/" "partition" +.RE +.TP +.BI "\-g " "group_name " "{ " "device " "[...] | ALL }" +Display statistics for a group of devices. +The +.B iostat +command reports statistics for each individual device in the list +then a line of global statistics for the group displayed as +.I group_name +and made up of all the devices in the list. The +.B ALL +keyword means that all the block devices defined by the system shall be +included in the group. +.TP +.B \-H +This option must be used with option +.B \-g +and indicates that only global +statistics for the group are to be displayed, and not statistics for +individual devices in the group. +.TP +.B \-h +This option is equivalent to specifying +.BR "\-\-human \-\-pretty" "." +.TP +.B \-\-human +Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.) +The units displayed with this option supersede any other default units (e.g. +kilobytes, sectors...) associated with the metrics. +.TP +.BI "\-j { ID | LABEL | PATH | UUID | ... } [ " "device " "[...] | ALL ]" +Display persistent device names. Keywords +.BR "ID" ", " "LABEL" ", " +etc. specify the type of the persistent name. These keywords are not limited, +only prerequisite is that directory with required persistent names is present in +.IR "/dev/disk" "." +Optionally, multiple devices can be specified in the chosen persistent name type. +Because persistent device names are usually long, option +.B \-\-pretty +is implicitly set with this option. +.TP +.B \-k +Display statistics in kilobytes per second. +.TP +.B \-m +Display statistics in megabytes per second. +.TP +.B \-N +Display the registered device mapper names for any device mapper devices. +Useful for viewing LVM2 statistics. +.TP +.B \-o JSON +Display the statistics in JSON (JavaScript Object Notation) format. +JSON output field order is undefined, and new fields may be added +in the future. +.TP +.BI "\-p [ { " "device" "[,...] | ALL } ]" +Display statistics for +block devices and all their partitions that are used by the system. +If a device name is entered on the command line, then statistics for it +and all its partitions are displayed. Last, the +.B ALL +keyword indicates that statistics have to be displayed for all the block +devices and partitions defined by the system, including those that have +never been used. If option +.B \-j +is defined before this option, devices entered on the command line can be +specified with the chosen persistent name type. +.TP +.B \-\-pretty +Make the Device Utilization Report easier to read by a human. +The device name will be printed on the right side. The report may also be broken +into sub-reports if there are many metrics to display (use +.B \-\-compact +option to prevent this). +.TP +.B \-s +Display a short (narrow) version of the report that should fit in 80 +characters wide screens. +.TP +.B \-t +Print the time for each report displayed. The timestamp format may depend +on the value of the +.BR "S_TIME_FORMAT " "environment variable (see below)." +.TP +.B \-V +Print version number then exit. +.TP +.B \-x +Display extended statistics. +.TP +.B \-y +Omit first report with statistics since system boot, if displaying +multiple records at given interval. +.TP +.B \-z +Tell +.B iostat +to omit output for any devices for which there was no activity +during the sample period. + +.SH ENVIRONMENT +The +.B iostat +command takes into account the following environment variables: +.TP +.B POSIXLY_CORRECT +When this variable is set, transfer rates are shown in 512-byte blocks instead +of the default 1K blocks. +.TP +.B S_COLORS +By default statistics are displayed in color when the output is connected to a terminal. +Use this variable to change the settings. Possible values for this variable are +.IR "never" ", " "always " "or " "auto" +(the latter is equivalent to the default settings). +.br +Please note that the color (being red, yellow, or some other color) used to display a value +is not indicative of any kind of issue simply because of the color. It only indicates different +ranges of values. +.TP +.B S_COLORS_SGR +Specify the colors and other attributes used to display statistics on the terminal. +Its value is a colon-separated list of capabilities that defaults to +.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "." +Supported capabilities are: +.RS +.TP +.B I= +SGR (Select Graphic Rendition) substring for device names. +.TP +.B N= +SGR substring for non-zero statistics values. +.TP +.BR "W=" " (or " "M=" ")" +SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the +metric's meaning). +.TP +.BR "X=" " (or " "H=" ")" +SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the +metric's meaning). +.TP +.B Z= +SGR substring for zero values. +.RE +.TP +.B S_TIME_FORMAT +If this variable exists and its value is +.B ISO +then the current locale will be ignored when printing the date in the report +header. The +.B iostat +command will use the ISO 8601 format (YYYY-MM-DD) instead. +The timestamp displayed with option +.B \-t +will also be compliant with ISO 8601 format. + +.SH EXAMPLES +.TP +.B iostat +Display a single history since boot report for all CPU and Devices. +.TP +.B iostat \-d 2 +Display a continuous device report at two second intervals. +.TP +.B iostat \-d 2 6 +Display six reports at two second intervals for all devices. +.TP +.B iostat \-x sda sdb 2 6 +Display six reports of extended statistics at two second intervals for devices +sda and sdb. +.TP +.B iostat \-p sda 2 6 +Display six reports at two second intervals for device sda and all its +partitions (sda1, etc.) + +.SH BUGS +.IR "/proc " "filesystem must be mounted for" +.BR "iostat " "to work." +.PP +Kernels older than 2.6.x are no longer supported. +.PP +.RB "Although " "iostat" +speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)... +A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes. + +.SH FILES +.IR "/proc/stat " "contains system statistics." +.br +.IR "/proc/uptime " "contains system uptime." +.br +.IR "/proc/diskstats " "contains disks statistics." +.br +.IR "/sys " "contains statistics for block devices." +.br +.IR "/proc/self/mountstats " "contains statistics for network filesystems." +.br +.IR "/dev/disk " "contains persistent device names." + +.SH AUTHOR +Sebastien Godard (sysstat <at> orange.fr) + +.SH SEE ALSO +.BR "sar" "(1), " "pidstat" "(1), " "mpstat" "(1), " "vmstat" "(8), " "tapestat" "(1), " "nfsiostat" "(1)," +.BR "cifsiostat" "(1)" +.PP +.I https://github.com/sysstat/sysstat +.br +.I https://sysstat.github.io/ |