man/man8/kstat.8

.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2025 Edgecast Cloud LLC.
.\"
.Dd June 19, 2025
.Dt KSTAT 8
.Os
.Sh NAME
.Nm kstat
.Nd display kernel statistics
.Sh SYNOPSIS
.Nm
.Op Fl Cjlq
.Op Fl p Op Fl V
.Op Fl T Ar u Ns | Ns Ar d
.Op Fl c Ar class
.Op Fl m Ar module
.Op Fl i Ar instance
.Op Fl n Ar name
.Op Fl s Ar statistic
.Op Ar interval Op Ar count
.Nm
.Op Fl Cjlq
.Op Fl p Op Fl V
.Op Fl T Ar u Ns | Ns Ar d
.Op Fl c Ar class
.Oo
.Ar module Ns
.Oo : Ns Ar instance Ns
.Oo : Ns Ar name Ns
.Oo : Ns Ar statistic Oc Oc Oc Oc Ns ...
.Op Ar interval Op Ar count
.Sh DESCRIPTION
The
.Nm
utility examines the available kernel statistics, or kstats, on
the system and reports those statistics which match the criteria specified on
the command line.
Each matching statistic is printed with its module, instance,
and name fields, as well as its actual value.
.Pp
Kernel statistics may be published by various kernel subsystems, such as
drivers or loadable modules; each kstat has a module field that denotes its
publisher.
Since each module might have countable entities
.Po such as multiple disks associated with the
.Xr sd 4D
driver
.Pc
for which it wishes to report statistics, the kstat also has an instance field
to index the statistics for each entity; kstat instances are numbered starting
from zero.
Finally, the kstat is given a name unique within its module.
.Pp
Each kstat may be a special kstat type, an array of name-value pairs, or raw
data.
In the name-value case, each reported value is given a label, which we
refer to as the statistic.
Known raw and special kstats are given statistic labels for each of their
values by
.Nm ;
thus, all published values can be referenced as
.Ar module : Ns Ar instance : Ns Ar name : Ns Ar statistic .
.Pp
When invoked without any module operands or options,
.Nm
will match all defined statistics on the system.
Example invocations are provided below.
All times are displayed as fractional seconds since system boot.
.Sh OPTIONS
The tests specified by the following options are logically ANDed, and all
matching kstats will be selected.
A regular expression containing shell metacharacters must be protected from
the shell by enclosing it with the appropriate quotes.
.Pp
The argument for the
.Fl c , i , m , n ,
and
.Fl s
options may be specified as a shell glob pattern, or a regular expression
enclosed in '/' characters.
.Bl -tag -width ""
.It Fl C
Displays output in parsable format with a colon as separator.
.It Fl c Ar class
Displays only kstats that match the specified class.
.Ar class
is a kernel-defined string which classifies the
.Qq type
of the kstat.
.It Fl i Ar instance
Displays only kstats that match the specified instance.
.It Fl j
Displays output in JSON format.
.It Fl l
Lists matching kstat names without displaying values.
.It Fl m Ar module
Displays only kstats that match the specified module.
.It Fl n Ar name
Displays only kstats that match the specified name.
.It Fl p Op Fl V
Displays output in parsable format, with
.Fl V
used, only values are displayed.
All example output in this document is given in this format.
If this option is not specified,
.Nm
produces output in a human-readable, table format.
.It Fl q
Displays no output, but return appropriate exit status for matches against
given criteria.
.It Fl s Ar statistic
Displays only kstats that match the specified statistic.
.It Fl T Ar d | Ar u
Displays a time stamp before each statistics block, either in
.Xr date 1
format
.Pq Ar d
or as an alphanumeric representation of the value returned by
.Xr time 2
.Pq Ar u .
.El
.Sh OPERANDS
The following operands are supported:
.Bl -tag -width ""
.It Ar module : Ns Ar instance : Ns Ar name : Ns Ar statistic
Alternate method of specifying module, instance, name, and statistic as
described above.
Each of the module, instance, name, or statistic specifiers
may be a shell glob pattern or a regular expression enclosed by
.Sq /
characters.
It is possible to use both specifier types within a single operand.
Leaving a specifier empty is equivalent to using the
.Sq *
glob pattern for that specifier.
.It Ar interval
The number of seconds between reports.
.It Ar count
The number of reports to be printed.
.El
.Sh FILES
.Bl -tag -width ""
.It Sy /dev/kstat
kernel statistics driver
.El
.Sh EXIT STATUS
The following exit values are returned:
.Bl -tag -width ""
.It Sy 0
One or more statistics were matched.
.It Sy 1
No statistics were matched.
.It Sy 2
Invalid command line options were specified.
.It Sy 3
A fatal error occurred.
.El
.Sh EXAMPLES
In the following examples, all the command lines in a block produce the same
output, as shown immediately below.
The exact statistics and values will of course vary from machine to machine.
.Bl -tag -width ""
.It Sy Example 1 No Using the Nm kstat No Command
.Bd -literal
example$ \fBkstat -p -m unix -i 0 -n system_misc -s 'avenrun*'\fR
example$ \fBkstat -p -s 'avenrun*'\fR
example$ \fBkstat -p 'unix:0:system_misc:avenrun*'\fR
example$ \fBkstat -p ':::avenrun*'\fR
example$ \fBkstat -p ':::/^avenrun_[0-9]+min$/'\fR

unix:0:system_misc:avenrun_15min        3
unix:0:system_misc:avenrun_1min 4
unix:0:system_misc:avenrun_5min 2
.Ed
.It Sy Example 2 No Using the Nm kstat No Command
.Bd -literal
example$ \fBkstat -p -m cpu_stat -s 'intr*'\fR
example$ \fBkstat -p cpu_stat:::/^intr/\fR

cpu_stat:0:cpu_stat0:intr       29682330
cpu_stat:0:cpu_stat0:intrblk    87
cpu_stat:0:cpu_stat0:intrthread 15054222
cpu_stat:1:cpu_stat1:intr       426073
cpu_stat:1:cpu_stat1:intrblk    51
cpu_stat:1:cpu_stat1:intrthread 289668
cpu_stat:2:cpu_stat2:intr       134160
cpu_stat:2:cpu_stat2:intrblk    0
cpu_stat:2:cpu_stat2:intrthread 131
cpu_stat:3:cpu_stat3:intr       196566
cpu_stat:3:cpu_stat3:intrblk    30
cpu_stat:3:cpu_stat3:intrthread 59626
.Ed
.It Sy Example 3 No Using the Nm kstat No Command
.Bd -literal
example$ \fBkstat -p :::state ':::avenrun*'\fR
example$ \fBkstat -p :::state :::/^avenrun/\fR

cpu_info:0:cpu_info0:state      on-line
cpu_info:1:cpu_info1:state      on-line
cpu_info:2:cpu_info2:state      on-line
cpu_info:3:cpu_info3:state      on-line
unix:0:system_misc:avenrun_15min        4
unix:0:system_misc:avenrun_1min 10
unix:0:system_misc:avenrun_5min 3
.Ed
.It Sy Example 4 No Using the Nm kstat No Command
.Bd -literal
example$ \fBkstat -p 'unix:0:system_misc:avenrun*' 1 3\fR
unix:0:system_misc:avenrun_15min        15
unix:0:system_misc:avenrun_1min 11
unix:0:system_misc:avenrun_5min 21

unix:0:system_misc:avenrun_15min        15
unix:0:system_misc:avenrun_1min 11
unix:0:system_misc:avenrun_5min 21

unix:0:system_misc:avenrun_15min        15
unix:0:system_misc:avenrun_1min 11
unix:0:system_misc:avenrun_5min 21
.Ed
.It Sy Example 5 No Using the Nm kstat No Command
.Bd -literal
example$ \fBkstat -p -T d 'unix:0:system_misc:avenrun*' 5 2\fR
Thu Jul 22 19:39:50 1999
unix:0:system_misc:avenrun_15min        12
unix:0:system_misc:avenrun_1min 0
unix:0:system_misc:avenrun_5min 11

Thu Jul 22 19:39:55 1999
unix:0:system_misc:avenrun_15min        12
unix:0:system_misc:avenrun_1min 0
unix:0:system_misc:avenrun_5min 11
.Ed
.It Sy Example 6 No Using the Nm kstat No Command
.Bd -literal
example$ \fBkstat -p -T u 'unix:0:system_misc:avenrun*'\fR
932668656
unix:0:system_misc:avenrun_15min        14
unix:0:system_misc:avenrun_1min 5
unix:0:system_misc:avenrun_5min 18
.Ed
.El
.Sh SEE ALSO
.Xr date 1 ,
.Xr sh 1 ,
.Xr time 2 ,
.Xr gmatch 3GEN ,
.Xr kstat 3KSTAT ,
.Xr kstat 4D ,
.Xr sd 4D ,
.Xr attributes 7 ,
.Xr regex 7 ,
.Xr kstat 9S
.Sh NOTES
If the pattern argument contains glob or RE metacharacters which are also
shell metacharacters, it will be necessary to enclose the pattern with
appropriate shell quotes.