1 .\" Copyright 2016 Garrett D'Amore
   2 .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common
   4 .\" Development and Distribution License (the "License").  You may not use this
   5 .\" file except in compliance with the License. You can obtain a copy of the
   6 .\" license at usr/src/OPENSOLARIS.LICENSE or
   7 .\" http://www.opensolaris.org/os/licensing.
   8 .\"
   9 .\" See the License for the specific language governing permissions and
  10 .\" limitations under the License. When distributing Covered Code, include this
  11 .\" CDDL HEADER in each file and include the License file at
  12 .\" usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this
  13 .\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your
  14 .\" own identifying information: Portions Copyright [yyyy] [name of copyright
  15 .\" owner]
  16 .\"
  17 .Dd Jan 27, 2016
  18 .Dt KSTAT 1M
  19 .Os
  20 .Sh NAME
  21 .Nm kstat
  22 .Nd display kernel statistics
  23 .Sh SYNOPSIS
  24 .Nm
  25 .Op Fl Cjlpq
  26 .Op Fl T Cm "u|d"
  27 .Op Fl c Ar class
  28 .Op Fl m Ar module
  29 .Op Fl i Ar instance
  30 .Op Fl n Ar name
  31 .Op Fl s Ar statistic
  32 .Op Fl H Cm "o|b|u|d|n|I|Z"
  33 .Op interval Op count
  34 .Nm
  35 .Op Fl Cjlpq
  36 .Op Fl T Cm "u|d"
  37 .Op Fl c Ar class
  38 .Op Fl H Cm "o|b|u|d|n|I|Z"
  39 .Op Ar module Ns Op ":" Ns Ar instance Ns Op ":" Ns Ar name Ns Op ":" Ns Ar statistic
  40 .Ar ...
  41 .Op interval Op count
  42 .
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility examines the available kernel statistics, or kstats, on
  47 the system and reports those statistics which match the criteria specified on
  48 the command line. Each matching statistic is printed with its module, instance,
  49 and name fields, as well as its actual value.
  50 .Lp
  51 Kernel statistics may be published by various kernel subsystems, such as
  52 drivers or loadable modules; each kstat has a module field that denotes its
  53 publisher. Since each module might have countable entities (such as multiple
  54 disks associated with the
  55 .Xr sd 7
  56 driver) for which it wishes to report
  57 statistics, the kstat also has an instance field to index the statistics for
  58 each entity; kstat instances are numbered starting from zero. Finally, the
  59 kstat is given a name unique within its module.
  60 .Lp
  61 Each kstat may be a special kstat type, an array of name-value pairs, or raw
  62 data. In the name-value case, each reported value is given a label, which we
  63 refer to as the statistic. Known raw and special kstats are given statistic
  64 labels for each of their values by
  65 .Va kstat ;
  66 thus, all published values can
  67 be referenced as
  68 .Ar module Ns : Ns Ar instance Ns : Ns Ar name Ns : Ns Ar statistic Ns .
  69 .Lp
  70 When invoked without any module operands or options, kstat will match all
  71 defined statistics on the system. Example invocations are provided below.
  72 .
  73 .Sh OPTIONS
  74 .
  75 The tests specified by the following options are logically ANDed, and all
  76 matching kstats will be selected. A regular expression containing shell
  77 metacharacters must be protected from the shell by enclosing it with the
  78 appropriate quotes.
  79 .Lp
  80 The argument for the
  81 .Fl c , i , m , n , No and Fl s
  82 options may be specified as a shell glob pattern, or a regular expression
  83 enclosed in '/' characters.
  84 .
  85 .Bl -tag -width Ds
  86 .It Fl C
  87 Displays output in parseable format with a colon as separator.
  88 .It Fl H Cm o|b|u|d|n|I|Z
  89 Displays times in the specified format, after normalizing them.
  90 This can be any of the following:
  91 .Bl -tag -width Ds
  92 .It Sy o
  93 Displays snapshot and creation times as a fractional number of seconds
  94 since boot, and other times as a whole number of nanoseconds since boot.
  95 This the default behavior.
  96 .It Sy b
  97 Displays a fractional number of seconds since system boot.
  98 .It Sy u
  99 Displays a fractional number of seconds since the epoch (Jan 1, 1970 UTC).
 100 .It Sy d
 101 Displays in the same format as from
 102 .Xr date 1 .
 103 .It Sy n
 104 Displays a whole number of nanoseconds since the epoch.
 105 .It Sy I
 106 Displays an ISO 8601:2000 standard time format in the local timezone.
 107 .It Sy Z
 108 Displays an ISO 8601:2000 standard time format in UTC.
 109 .El
 110 .Lp
 111 Note that when using normalized time formats, the accuracy of
 112 the result will depend on the resolution of the realtime clock (see
 113 .Xr clock_gettime 3C ),
 114 and in no case will be more accurate to absolute time than one microsecond.
 115 However, any offset error between timestamps will be the same for all values
 116 displayed within a single kstat snapshot.
 117 .
 118 .It Fl c Ar class
 119 Displays only kstats that match the specified class.
 120 .Ar class
 121 is a kernel-defined string which classifies the "type" of the kstat.
 122 .It Fl i Ar instance
 123 Displays only kstats that match the specified instance.
 124 .It Fl j
 125 Displays output in JSON format.
 126 .It Fl l
 127 Lists matching kstat names without displaying values.
 128 .It Fl m Ar module
 129 Displays only kstats that match the specified module.
 130 .It Fl n Ar name
 131 Displays only kstats that match the specified name.
 132 .It Fl p
 133 Displays output in parseable format. All example output in this document is
 134 given in this format. If this option is not specified,
 135 .Nm
 136 produces output in a human-readable, table format.
 137 .It Fl q
 138 Displays no output, but return appropriate exit status for matches against
 139 given criteria.
 140 .It Fl s Ar statistic
 141 Displays only kstats that match the specified statistic.
 142 .It Fl T Cm "d|u"
 143 Displays a time stamp before each statistics block, either in
 144 .Xr date 1
 145 format (\fBd\fR) or as an alphanumeric representation of the value returned by
 146 .Xr time 2
 147 (\fBu\fR).
 148 .El
 149 .Sh OPERANDS
 150 The following operands are supported:
 151 .Bl -tag -width Ds
 152 .It Ar module Ns : Ns Ar instance Ns : Ns Ar name Ns : Ns Ar statistic Ns
 153 Alternate method of specifying module, instance, name, and statistic as
 154 described above. Each of the module, instance, name, or statistic specifiers
 155 may be a shell glob pattern or a regular expression enclosed by '/'
 156 characters. It is possible to use both specifier types within a single operand.
 157 Leaving a specifier empty is equivalent to using the '*' glob pattern for that
 158 specifier.
 159 .It Ar interval
 160 The number of seconds between reports.
 161 .It Ar count
 162 The number of reports to be printed.
 163 .El
 164 .Sh FILES
 165 .Bl -tag -width Ds
 166 .It Pa /dev/kstat
 167 kernel statistics driver
 168 .El
 169 .Sh EXIT STATUS
 170 The following exit values are returned:
 171 .Lp
 172 .Bl -tag -width Ds -compact
 173 .It 0
 174 One or more statistics were matched.
 175 .It 1
 176 No statistics were matched.
 177 .It 2
 178 Invalid command line options were specified.
 179 .It 3
 180 A fatal error occurred.
 181 .El
 182 .Sh EXAMPLES
 183 In the following examples, all the command lines in a block produce the same
 184 output, as shown immediately below. The exact statistics and values will of
 185 course vary from machine to machine.
 186 .
 187 .Ss Example 1: Using the kstat Command
 188 .Bd -literal -offset indent
 189 example$ \fBlstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
 190 example$ \fBkstat -p -s 'avenrun*'\fR
 191 example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
 192 example$ \fBkstat -p ':::avenrun*'\fR
 193 example$ \fBkstat -p ':::/^avenrun_[0-9]+min$/'\fR
 194 .sp
 195 unix:0:system_misc:avenrun_15min        3
 196 unix:0:system_misc:avenrun_1min 4
 197 unix:0:system_misc:avenrun_5min 2
 198 .Ed
 199 .
 200 .Ss Example 2: Using the kstat Command
 201 .Bd -literal -offset indent
 202 example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
 203 example$ \fBkstat -p cpu_stat:::/^intr/\fR
 204 .sp
 205 cpu_stat:0:cpu_stat0:intr       29682330
 206 cpu_stat:0:cpu_stat0:intrblk    87
 207 cpu_stat:0:cpu_stat0:intrthread 15054222
 208 cpu_stat:1:cpu_stat1:intr       426073
 209 cpu_stat:1:cpu_stat1:intrblk    51
 210 cpu_stat:1:cpu_stat1:intrthread 289668
 211 cpu_stat:2:cpu_stat2:intr       134160
 212 cpu_stat:2:cpu_stat2:intrblk    0
 213 cpu_stat:2:cpu_stat2:intrthread 131
 214 cpu_stat:3:cpu_stat3:intr       196566
 215 cpu_stat:3:cpu_stat3:intrblk    30
 216 cpu_stat:3:cpu_stat3:intrthread 59626
 217 .Ed
 218 .
 219 .Ss Example 3: Using the kstat Command
 220 .Bd -literal -offset indent
 221 example$ \fBkstat -p :::state ':::avenrun*'\fR
 222 example$ \fBkstat -p :::state :::/^avenrun/\fR
 223 .sp
 224 cpu_info:0:cpu_info0:state      on-line
 225 cpu_info:1:cpu_info1:state      on-line
 226 cpu_info:2:cpu_info2:state      on-line
 227 cpu_info:3:cpu_info3:state      on-line
 228 unix:0:system_misc:avenrun_15min        4
 229 unix:0:system_misc:avenrun_1min 10
 230 unix:0:system_misc:avenrun_5min 3
 231 .Ed
 232 .
 233 .Ss Example 4: Using the kstat Command
 234 .Bd -literal -offset indent
 235 example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
 236 unix:0:system_misc:avenrun_15min        15
 237 unix:0:system_misc:avenrun_1min 11
 238 unix:0:system_misc:avenrun_5min 21
 239 .sp
 240 unix:0:system_misc:avenrun_15min        15
 241 unix:0:system_misc:avenrun_1min 11
 242 unix:0:system_misc:avenrun_5min 21
 243 .sp
 244 unix:0:system_misc:avenrun_15min        15
 245 unix:0:system_misc:avenrun_1min 11
 246 unix:0:system_misc:avenrun_5min 21
 247 .Ed
 248 .
 249 .Ss Example 5: Using the kstat Command
 250 .Bd -literal -offset indent
 251 example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
 252 Thu Jul 22 19:39:50 1999
 253 unix:0:system_misc:avenrun_15min        12
 254 unix:0:system_misc:avenrun_1min 0
 255 unix:0:system_misc:avenrun_5min 11
 256 .sp
 257 Thu Jul 22 19:39:55 1999
 258 unix:0:system_misc:avenrun_15min        12
 259 unix:0:system_misc:avenrun_1min 0
 260 unix:0:system_misc:avenrun_5min 11
 261 .Ed
 262 .
 263 .Ss Example 6: Using the kstat Command
 264 .Bd -literal -offset indent
 265 example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
 266 932668656
 267 unix:0:system_misc:avenrun_15min        14
 268 unix:0:system_misc:avenrun_1min 5
 269 unix:0:system_misc:avenrun_5min 18
 270 .Ed
 271 .Sh SEE ALSO
 272 .Xr date 1 ,
 273 .Xr sh 1 ,
 274 .Xr time 2 ,
 275 .Xr clock_gettime 3C ,
 276 .Xr gmatch 3GEN ,
 277 .Xr kstat 3KSTAT ,
 278 .Xr regex 5 ,
 279 .Xr kstat 7D ,
 280 .Xr sd 7D ,
 281 .Xr kstat 9S
 282 .Sh NOTES
 283 If the pattern argument contains glob or RE metacharacters which are also
 284 shell metacharacters, it will be necessary to enclose the pattern with
 285 appropriate shell quotes.