| 1 |
.\" mpstat manual page - (C) 2000-2020 Sebastien Godard (sysstat <at> orange.fr) |
| 2 |
.TH MPSTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- |
| 3 |
.SH NAME |
| 4 |
mpstat \- Report processors related statistics. |
| 5 |
|
| 6 |
.SH SYNOPSIS |
| 7 |
.B mpstat [ \-A ] [ \-\-dec={ 0 | 1 | 2 } ] [ \-H ] [ \-n ] [ \-u ] [ \-T ] [ \-V ] [ \-I { |
| 8 |
.IB "keyword" "[,...] | ALL } ] [ \-N { " "node_list " "| ALL } ] [ \-o JSON ] [ \-P {" |
| 9 |
.IB "cpu_list " "| ALL } ] [ " "interval " "[ " "count " "] ]" |
| 10 |
|
| 11 |
.SH DESCRIPTION |
| 12 |
.RB "The " "mpstat" |
| 13 |
command writes to standard output activities for each available processor, |
| 14 |
processor 0 being the first one. |
| 15 |
Global average activities among all processors are also reported. |
| 16 |
.RB "The " "mpstat" |
| 17 |
command can be used on both SMP and UP machines, but in the latter, only global |
| 18 |
average activities will be printed. If no activity has been selected, then the |
| 19 |
default report is the CPU utilization report. |
| 20 |
.PP |
| 21 |
.RI "The " "interval" |
| 22 |
parameter specifies the amount of time in seconds between each report. |
| 23 |
A value of 0 (or no parameters at all) indicates that processors statistics are |
| 24 |
to be reported for the time since system startup (boot). The |
| 25 |
.IR "count " "parameter can be specified in conjunction with the " "interval" |
| 26 |
parameter if this one is not set to zero. The value of |
| 27 |
.I count |
| 28 |
determines the number of reports generated at |
| 29 |
.IR "interval " "seconds apart. If the " "interval" |
| 30 |
parameter is specified without the |
| 31 |
.IR "count " "parameter, the" |
| 32 |
.B mpstat |
| 33 |
command generates reports continuously. |
| 34 |
|
| 35 |
.SH OPTIONS |
| 36 |
.TP |
| 37 |
.B \-A |
| 38 |
This option is equivalent to specifying |
| 39 |
.BR "\-n \-u \-I ALL" "." |
| 40 |
This option also implies specifying |
| 41 |
.B "\-N ALL \-P ALL" |
| 42 |
unless these options are explicitly set on the command line. |
| 43 |
.TP |
| 44 |
.B \-\-dec={ 0 | 1 | 2 } |
| 45 |
Specify the number of decimal places to use (0 to 2, default value is 2). |
| 46 |
.TP |
| 47 |
.B \-H |
| 48 |
Also detect and display statistics for physically hotplugged vCPUs. |
| 49 |
.TP |
| 50 |
.BI "\-I { " "keyword" "[,...] | ALL }" |
| 51 |
Report interrupts statistics. |
| 52 |
.RI "Possible " "keywords " "are" |
| 53 |
.BR "CPU" ", " "SCPU" ", and " "SUM" "." |
| 54 |
.PP |
| 55 |
.RS |
| 56 |
.RB "With the " "CPU" |
| 57 |
keyword, the number of each individual interrupt received per |
| 58 |
second by the CPU or CPUs is displayed. Interrupts are those listed in |
| 59 |
.IR "/proc/interrupts " "file." |
| 60 |
.PP |
| 61 |
.RB "With the " "SCPU" |
| 62 |
keyword, the number of each individual software interrupt received per |
| 63 |
second by the CPU or CPUs is displayed. This option works only |
| 64 |
with kernels 2.6.31 and later. Software interrupts are those listed in |
| 65 |
.IR "/proc/softirqs " "file." |
| 66 |
.PP |
| 67 |
.RB "With the " "SUM " "keyword, the " "mpstat" |
| 68 |
command reports the total number of interrupts per processor. |
| 69 |
The following values are displayed: |
| 70 |
|
| 71 |
.IP CPU |
| 72 |
Processor number. The keyword |
| 73 |
.B all |
| 74 |
indicates that statistics are calculated as averages among all processors. |
| 75 |
|
| 76 |
.IP intr/s |
| 77 |
Show the total number of interrupts received per second by |
| 78 |
the CPU or CPUs. |
| 79 |
.RE |
| 80 |
.IP |
| 81 |
.RB "The " "ALL" |
| 82 |
keyword is equivalent to specifying all the keywords above and |
| 83 |
therefore all the interrupts statistics are displayed. |
| 84 |
.TP |
| 85 |
.BI "\-N { " "node_list " "| ALL }" |
| 86 |
Indicate the NUMA nodes for which statistics are to be reported. |
| 87 |
.I node_list |
| 88 |
is a list of comma-separated values or range of values (e.g., |
| 89 |
.BR "0,2,4\-7,12\-" "). Note that node " "all" |
| 90 |
is the global average among all nodes. The |
| 91 |
.B ALL |
| 92 |
keyword indicates that statistics are to be reported for all nodes. |
| 93 |
.TP |
| 94 |
.B \-n |
| 95 |
Report summary CPU statistics based on NUMA node placement. The following |
| 96 |
values are displayed: |
| 97 |
.RS |
| 98 |
.IP NODE |
| 99 |
Logical NUMA node number. The keyword |
| 100 |
.B all |
| 101 |
indicates that statistics are calculated as averages among all nodes. |
| 102 |
.RE |
| 103 |
.IP |
| 104 |
All the other fields are the same as those displayed with option |
| 105 |
.BR "\-u " "(see below)." |
| 106 |
.TP |
| 107 |
.B \-o JSON |
| 108 |
Display the statistics in JSON (JavaScript Object Notation) format. |
| 109 |
JSON output field order is undefined, and new fields may be added |
| 110 |
in the future. |
| 111 |
.TP |
| 112 |
.BI "\-P { " "cpu_list " "| ALL }" |
| 113 |
Indicate the processors for which statistics are to be reported. |
| 114 |
.I cpu_list |
| 115 |
is a list of comma-separated values or range of values (e.g., |
| 116 |
.BR "0,2,4\-7,12\-" ")." |
| 117 |
Note that processor 0 is the first processor, and processor |
| 118 |
.B all |
| 119 |
is the global average among all processors. |
| 120 |
.RB "The " "ALL" |
| 121 |
keyword indicates that statistics are to be reported for all processors. |
| 122 |
Offline processors are not displayed. |
| 123 |
.TP |
| 124 |
.B \-T |
| 125 |
Display topology elements in the CPU report (see option |
| 126 |
.B \-u |
| 127 |
below). The following elements are displayed: |
| 128 |
.RS |
| 129 |
.IP CORE |
| 130 |
Logical core number. |
| 131 |
.IP SOCK |
| 132 |
Logical socket number. |
| 133 |
.IP NODE |
| 134 |
Logical NUMA node number. |
| 135 |
.RE |
| 136 |
.TP |
| 137 |
.B \-u |
| 138 |
Report CPU utilization. The following values are displayed: |
| 139 |
.RS |
| 140 |
.IP CPU |
| 141 |
Processor number. The keyword |
| 142 |
.I all |
| 143 |
indicates that statistics are calculated as averages among all processors. |
| 144 |
.IP %usr |
| 145 |
Show the percentage of CPU utilization that occurred while |
| 146 |
executing at the user level (application). |
| 147 |
.IP %nice |
| 148 |
Show the percentage of CPU utilization that occurred while |
| 149 |
executing at the user level with nice priority. |
| 150 |
.IP %sys |
| 151 |
Show the percentage of CPU utilization that occurred while |
| 152 |
executing at the system level (kernel). Note that this does not |
| 153 |
include time spent servicing hardware and software interrupts. |
| 154 |
.IP %iowait |
| 155 |
Show the percentage of time that the CPU or CPUs were idle during which |
| 156 |
the system had an outstanding disk I/O request. |
| 157 |
.IP %irq |
| 158 |
Show the percentage of time spent by the CPU or CPUs to service hardware interrupts. |
| 159 |
.IP %soft |
| 160 |
Show the percentage of time spent by the CPU or CPUs to service software interrupts. |
| 161 |
.IP %steal |
| 162 |
Show the percentage of time spent in involuntary wait by the virtual CPU |
| 163 |
or CPUs while the hypervisor was servicing another virtual processor. |
| 164 |
.IP %guest |
| 165 |
Show the percentage of time spent by the CPU or CPUs to run a virtual processor. |
| 166 |
.IP %gnice |
| 167 |
Show the percentage of time spent by the CPU or CPUs to run a niced guest. |
| 168 |
.IP %idle |
| 169 |
Show the percentage of time that the CPU or CPUs were idle and the system |
| 170 |
did not have an outstanding disk I/O request. |
| 171 |
.RE |
| 172 |
.TP |
| 173 |
.B \-V |
| 174 |
Print version number then exit. |
| 175 |
|
| 176 |
.SH ENVIRONMENT |
| 177 |
.RB "The " "mpstat" |
| 178 |
command takes into account the following environment variable: |
| 179 |
.TP |
| 180 |
.B S_COLORS |
| 181 |
By default statistics are displayed in color when the output is connected to a terminal. |
| 182 |
Use this variable to change the settings. Possible values for this variable are |
| 183 |
.IR "never" ", " "always " "or " "auto" |
| 184 |
(the latter is equivalent to the default settings). |
| 185 |
.br |
| 186 |
Please note that the color (being red, yellow, or some other color) used to display a value |
| 187 |
is not indicative of any kind of issue simply because of the color. It only indicates different |
| 188 |
ranges of values. |
| 189 |
.TP |
| 190 |
.B S_COLORS_SGR |
| 191 |
Specify the colors and other attributes used to display statistics on the terminal. |
| 192 |
Its value is a colon-separated list of capabilities that defaults to |
| 193 |
.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "." |
| 194 |
Supported capabilities are: |
| 195 |
.RS |
| 196 |
.TP |
| 197 |
.B I= |
| 198 |
SGR (Select Graphic Rendition) substring for CPU number. |
| 199 |
.TP |
| 200 |
.B N= |
| 201 |
SGR substring for non-zero statistics values. |
| 202 |
.TP |
| 203 |
.BR "W=" " (or " "M=" ")" |
| 204 |
SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the |
| 205 |
metric's meaning). |
| 206 |
.TP |
| 207 |
.BR "X=" " (or " "H=" ")" |
| 208 |
SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the |
| 209 |
metric's meaning). |
| 210 |
.TP |
| 211 |
.B Z= |
| 212 |
SGR substring for zero values. |
| 213 |
.RE |
| 214 |
.TP |
| 215 |
.B S_TIME_FORMAT |
| 216 |
If this variable exists and its value is |
| 217 |
.BR ISO |
| 218 |
then the current locale will be ignored when printing the date in the report header. |
| 219 |
.RB "The " "mpstat" |
| 220 |
command will use the ISO 8601 format (YYYY-MM-DD) instead. |
| 221 |
The timestamp will also be compliant with ISO 8601 format. |
| 222 |
|
| 223 |
.SH EXAMPLES |
| 224 |
.TP |
| 225 |
.B mpstat 2 5 |
| 226 |
Display five reports of global statistics among all processors at two second intervals. |
| 227 |
.TP |
| 228 |
.B mpstat \-P ALL 2 5 |
| 229 |
Display five reports of statistics for all processors at two second intervals. |
| 230 |
|
| 231 |
.SH BUGS |
| 232 |
.IR "/proc " "filesystem must be mounted for the" |
| 233 |
.BR "mpstat " "command to work." |
| 234 |
|
| 235 |
.SH FILES |
| 236 |
.IR "/proc " "contains various files with system statistics." |
| 237 |
|
| 238 |
.SH AUTHOR |
| 239 |
Sebastien Godard (sysstat <at> orange.fr) |
| 240 |
|
| 241 |
.SH SEE ALSO |
| 242 |
.BR "sar" "(1), " "pidstat" "(1), " "iostat" "(1), " "vmstat" "(8)" |
| 243 |
.PP |
| 244 |
.I https://github.com/sysstat/sysstat |
| 245 |
.br |
| 246 |
.I https://sysstat.github.io/ |