Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2 (8)

Name

kstat2 - display kernel statistics

Synopsis

kstat2 [[-j | -l | -p | -q] | [-h] [-d]]
[-m] [-i N] [-c N] [-T d|u]
[[-g <glob_uri>] ...] [[-r <re_uri>] ...] [[uri] ...]

Description

The kstat2 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 URI and its actual value.

Kernel statistics may be published by various kernel subsystems, such as drivers or loadable modules. Each kstat is identified by a unique URI that consists of multiple mandatory and optional path components.

kstat:/<category>/<component>/<name>/<instance>/<subinstance>/...
category

Mandatory category that each kstat belongs to. For example, cpu, disk, network, and io.

component

Mandatory name of the kernel subsystem that publishes a particular kstat. For example, nfs, vmem, e1000g, and zfs.

name

Mandatory identifier that names this kstat. For example, arcstats, ip6stats, and inode_cache.

instance

Optional instance identifier if there are multiple instances of a kstat.

subinstance(s)

Optional sub-instance identifiers that further identify kstats. There may be multiple subinstances. For example, TCP connections and VM partitions.

Kstats may be selected for display by providing a selector URI either as a plain string for direct comparison with the kstat URI, or as a shell glob pattern or Perl Compatible Regular expression(PCRE) to match against the kstat URI. When specifying a selector URI, the URI scheme is optional. For example, the following two selectors are equivalent.

/<category>/<component>/<name>
kstat:/<category>/<component>/<name>

Each kstat consists of an array of name-value pairs, each being a statistic the kstat is publishing. Specific statistics may be selected for display by specifying the name of the statistic as a path parameter in the kstat URI. Note that as semi-colon is not a shell-safe character, colon will also be accepted.

kstat:/<category>/<component>/<name>/<instance>;<statistic>
kstat:/<category>/<component>/<name>/<instance>:<statistic>

When invoked without any operands or options, kstat2 will match all statistics on the system.

The default output format outputs the raw value along with the scale and unit. If the scale is 1, it is omitted from the output. A scale larger than the base unit is expressed as a multiplier. A scale smaller than the base unit is expressed as a fraction.

<name> <value> [*|/ <scale> ]<units>

Human readable output allows easier human interpretation of the kstat values. This output is identical to the default readable output format, except that the statistic values are more human readable. Values are formatted based on their type and metadata and scaled to an appropriate SI prefix with a maximum of 2 decimal places, where applicable. This output is intended for a higher level view of the kstat values as some loss of precision will occur due to scaling.

Parseable output provides tab separated output, consisting of the kstat URI, the statistics value, and optionally the metadata.

<URI>[TAB]<value>
<URI>[TAB]<value>[TAB]<metadata>

Kstat values that are an array of integers or strings will be displayed as a comma separated list. All string values will be surrounded by quotes, with any quotes or backslashes in the string being backslash escaped.

<URI>[TAB]<valueA>,<valueB>,<valueC>
<URI>[TAB]<valueA>,<valueB>,<valueC>[TAB]<metadata>

If the kstats are requested multiple times over a time period, each set of kstats is separated with a blank line.

<URI_A>[TAB]<value>[TAB]<metadata>
<URI_B>[TAB]<value>[TAB]<metadata>
              
<URI_A>[TAB]<value>[TAB]<metadata>
<URI_B>[TAB]<value>[TAB]<metadata>

The parseable metadata format consists of a semi-colon separated list of fields, with each fields name or value separated by a colon. The flags field may contain multiple values, therefore is a comma separated list. The description will be in quotes in the same way that kstat string values are quoted.

type:<type>;flags:<flag_a>,<flag_b>;scale:<N>;description:<desc>

JSON output provides output consisting of the kstat URI, the statistics value and optionally the metadata. All kstats that match the selectors provided will be output as a single JSON result set, in the following format (For readability, this is formatted over multiple lines. The result set is actually output on a single line.)

{
          "<URI_A>": {
            "metadata": {
              "type": "<metadata_type>",
              "flags": "<flag_a>,<flag_b>",
              "description": "<desc>"
            },
            "values": {
              "<value_1>": {
                "value": <value>,
                "flags": "<flag_a>,<flag_b>",
                "metadata": {
                  "type": "<metadata_type>",
                  "flags": "<flag_a>,<flag_b>",
                  "scale": <scale>,
                  "description": "<desc>"
                }
              },
              "<value_2>": {
                "value": <value>,
                "flags": "<flag_a>,<flag_b>",
                "metadata": {
                  "type": "<metadata_type>",
                  "flags": "<flag_a>,<flag_b>",
                  "scale": <scale>,
                  "description": "<desc>"
                }
              },
              ...
            }
          },
          ...
}

If the kstats are requested multiple times over a time period, each set of kstats is prepended with an ASCII record separator character (0x1E) and line feed (0x1A) and will be terminated by a line feed (0x1A), as defined in RFC 7464.

Options

The URIs specified by the following options/operands 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.

The following options are supported:

–c --count=N

The number of reports to be printed.

–d --desc

Includes the statistic description in the output

–g --glob=glob_uri

Displays only kstats where the kstat URI matches the given shell glob pattern.

–h --human-readable

Displays output in a human readable format. This differs from the default output format in that kstat values are scaled and formatted to make them more human readable.

–i --interval=N

The number of seconds between reports.

–j --json

Displays output in JSON output format.

–l --list

Lists matching kstat URIs without displaying values.

–m --metadata

Includes metadata for the kstat or statistic in the displayed output.

–p --parseable

Displays output in parseable format.

–q --quiet

Displays no output, but returns appropriate exit status for matches against given criteria.

–r --regex=re_uri

Displays only kstats where the kstat URI matches the given Perl Compatible Regular expression(PCRE).

–T --timestamp d | u

Displays a time stamp before each statistics block, either in date(1) format (d) or as an alphanumeric representation of the value returned by time(2) (u).

Operands

The following operand is supported:

uri

Displays only kstats where the kstat URI is equal to the specified URI.

Exit Status

The following exit values are returned:

0

One or more statistics were matched.

1

No statistics were matched.

2

Invalid command line options were specified.

3

A fatal error occurred.

Examples

In the following examples, all the command lines in a block produce the same output, as shown. The exact statistics and values will vary from machine to machine.

Example 1 Displaying a Specific Statistic
example$ kstat2 -p /system/cpu/0/sys:syscall
kstat:/system/cpu/0/sys;syscall	  123476655
Example 2 Using Globs and PCREs
example$ kstat2 -p -g kstat:/system/cpu/0/sys\;sys*
example$ kstat2 -p -g /system/cpu/0/sys\:sys*
example$ kstat2 -p -r 'kstat:/system/cpu/0/sys:(^sys[a-z]+)'

kstat:/system/cpu/0/sys;syscall     123032271
kstat:/system/cpu/0/sys;sysexec     1397
kstat:/system/cpu/0/sys;sysfork     1087
kstat:/system/cpu/0/sys;sysread     18300125
kstat:/system/cpu/0/sys;sysvfork    415
kstat:/system/cpu/0/sys;syswrite    17901110
Example 3 Specifying Multiple URI Selectors
example$ kstat2 -p -g kstat:/system/cpu/*/*:state \
    -r '/misc/unix/system_misc/\d+:avenrun_\d+min'
kstat:/system/cpu/0/info;state		 "on-line"
kstat:/system/cpu/1/info;state		 "on-line"
kstat:/system/cpu/2/info;state		 "on-line"
kstat:/system/cpu/3/info;state		 "on-line"

kstat:/misc/unix/system_misc/0;avenrun_15min	37
kstat:/misc/unix/system_misc/0;avenrun_1min	39
kstat:/misc/unix/system_misc/0;avenrun_5min	34
Example 4 Displaying a kstat and all sub-kstats
example$ kstat2 -p -g kstat:/misc/sd/fm/*

kstat:/misc/sd/fm/0;acc_err	0
kstat:/misc/sd/fm/0;crtime	1396300378030300
kstat:/misc/sd/fm/0;dma_err	0
kstat:/misc/sd/fm/0;erpt_dropped	0
kstat:/misc/sd/fm/0;fm_cache_full	0
kstat:/misc/sd/fm/0;fm_cache_miss	0
kstat:/misc/sd/fm/0;snaptime	1729929193573329
kstat:/misc/sd/fm/1;acc_err	0
kstat:/misc/sd/fm/1;crtime	1396300452673900
kstat:/misc/sd/fm/1;dma_err	0
kstat:/misc/sd/fm/1;erpt_dropped	0
kstat:/misc/sd/fm/1;fm_cache_full	0
kstat:/misc/sd/fm/1;fm_cache_miss	0
kstat:/misc/sd/fm/1;snaptime	1729929193778581
kstat:/misc/sd/fm/2;acc_err	0
kstat:/misc/sd/fm/2;crtime	1396300537414196
kstat:/misc/sd/fm/2;dma_err	0
kstat:/misc/sd/fm/2;erpt_dropped	0
kstat:/misc/sd/fm/2;fm_cache_full	0
kstat:/misc/sd/fm/2;fm_cache_miss	0
kstat:/misc/sd/fm/2;snaptime	1729929193897329
Example 5 Displaying Statistics Over a Time Period
example$ kstat2 -p -i1 -c3 kstat:/system/cpu/0/sys:syscall

kstat:/system/cpu/0/sys;syscall     123868937

kstat:/system/cpu/0/sys;syscall     123868992
kstat:/system/cpu/0/sys;syscall     123869051
Example 6 Displaying date Timestamp With Statistics
example$ kstat2 -p -T d -i5 -c2 kstat:/system/cpu/0/sys:syscall

Tuesday, March 10, 2015 04:48:57 PM GMT
kstat:/system/cpu/0/sys;syscall     124200181

Tuesday, March 10, 2015 04:49:02 PM GMT
kstat:/system/cpu/0/sys;syscall     124204228
Example 7 Displaying time Timestamp With Statistics
example$ kstat2 -p -T u -i5 -c2 kstat:/system/cpu/0/sys:syscall

1426006184
kstat:/system/cpu/0/sys;syscall     124305293

1426006189
kstat:/system/cpu/0/sys;syscall     124308113
Example 8 Display Readable Statistics
example$ kstat2 kstat:/vm/unix/vminfo:swap_free kstat:/vm/unix/vminfo:snaptime
snaptime                        2193622143290103 / 1000000000 seconds
	swap_free                       1262611263678 * 4096 bytes
Example 9 Displaying Readable Statistic Metadata
example$ kstat2 -m kstat:/vm/unix/vminfo:swap_free kstat:/vm/unix/vminfo:snaptime

snaptime                        2193622143290103 / 1000000000 seconds
type: Relative time
flags: KSTAT2_NVMF_FRACT
scale: 1000000000
description: "kstat snapshot time"

swap_free                       1262611263678 * 4096 bytes
type: Byte count
flags: KSTAT2_NVMF_NONE
scale: 4096
description: "Unallocated swap space"
Example 10 Displaying kstat Arrays
example$ kstat2 -p -g /misc/foo/bar:*arr

kstat:/misc/foo/bar;strarr	"foo","bar","quo\"te"
kstat:/misc/foo/bar;intarr	0,1,2,3,4,5
Example 11 Displaying Quoted Strings
example$ kstat2 -mp /misc/foo/bar:str

kstat:/misc/foo/bar;str	"quote \"me\""	type:KSTAT2_MT_UNK;flags:KSTAT2_MF_NONE;description:
                                                    "Shows \"quoted\" value"
Example 12 Display Human Readable Values
example$ kstat2 -h -r "/system/cpu/0/sys:crtime|readch|syscall"

         kstat:/system/cpu/0/sys
               crtime                          2DT14H50M49S from boot
               readch                          467.16 GiB 
               syscall                         2.97 G 
Example 13 Display JSON Values
example$ kstat2 -j -r "/system/cpu/0/sys:crtime|readch|syscall"
         
         {"kstat:/system/cpu/0/sys":{"values":{"crtime":{"value":226249412205913,
         "flags":"KSTAT2_NVF_NONE"},"readch":{"value":503096314603,
         "flags":"KSTAT2_NVF_NONE"},"syscall":{"value":2996723957,
         "flags":"KSTAT2_NVF_NONE"}}}}
Example 14 Display JSON Over a Time Period
example$ kstat2 -Tu -j -c2 "/system/cpu/0/sys:syscall"
         <0x1E>
         {"kstat:/system/cpu/0/sys":{"values":{"syscall":{"value":1509153472,
         "flags":"KSTAT2_NVF_NONE"}}},"timestamp_u":1439887046}
         <0x1E>
         {"kstat:/system/cpu/0/sys":{"values":{"syscall":{"value":1509153472,
         "flags":"KSTAT2_NVF_NONE"}}},"timestamp_u":1439887047}

Files

/dev/kstat

kernel statistics driver

/usr/share/kstats/schema.json

kstat JSON schema

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os

See Also

date(1), sh(1), time(2), gmatch(3GEN), kstat2(3KSTAT2), kstat(4D), attributes(7), kstat2(9S)

Williams, N., "JavaScript Object Notation (JSON) Text Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015

"JSON Schema: core definitions and terminology", Francis Galiegue, Kris Zyp and Gary Court, January 2013. Internet Draft. http://tools.ietf.org/html/draft-zyp-json-schema-04 http://json-schema.org/

Notes

If the pattern argument contains glob or Perl RE metacharacters which are also shell metacharacters, it will be necessary to enclose the pattern with appropriate shell quotes.