kstat2 - display kernel statistics
kstat2 [[-j | -l | -p | -q] | [-h] [-d]] [-m] [-i N] [-c N] [-T d|u] [[-g <glob_uri>] ...] [[-r <re_uri>] ...] [[uri] ...]
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>/...
Mandatory category that each kstat belongs to. For example, cpu, disk, network, and io.
Mandatory name of the kernel subsystem that publishes a particular kstat. For example, nfs, vmem, e1000g, and zfs.
Mandatory identifier that names this kstat. For example, arcstats, ip6stats, and inode_cache.
Optional instance identifier if there are multiple instances of a kstat.
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 semicolon 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 semicolon separated list of fields, with each field's 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.
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:
The number of reports to be printed.
Includes the statistic description in the output
Displays only kstats where the kstat URI matches the given shell glob pattern.
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.
The number of seconds between reports.
Displays output in JSON output format.
Lists matching kstat URIs without displaying values.
Includes metadata for the kstat or statistic in the displayed output.
Displays output in parseable format.
Displays no output, but returns appropriate exit status for matches against given criteria.
Displays only kstats where the kstat URI matches the given Perl Compatible Regular expression(PCRE).
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).
The following operand is supported:
Displays only kstats where the kstat URI is equal to the specified URI.
The following exit values are returned:
One or more statistics were matched.
No statistics were matched.
Invalid command line options were specified.
A fatal error occurred.
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 Statisticexample$ kstat2 -p /system/cpu/0/sys:syscall kstat:/system/cpu/0/sys;syscall 123476655Example 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 17901110Example 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 1729929193897329Example 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 123869051Example 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 124204228Example 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 124308113Example 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 bytesExample 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,5Example 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}
kernel statistics driver
kstat JSON schema
See attributes(7) for descriptions of the following attributes:
|
date(1), sh(1), time(2), gmatch(3GEN), kstat2(3KSTAT2), kstat(4D), attributes(7), kstat2(9S)
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.