path: root/usr/src/man/man3kstat/kstat.3kstat

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\" 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]
.TH KSTAT 3KSTAT "Jan 29, 2007"
.SH NAME
kstat \- kernel statistics facility
.SH DESCRIPTION
.sp
.LP
The \fBkstat\fR facility is a general-purpose mechanism for providing kernel
statistics to users.
.SS "The kstat model"
.sp
.LP
The kernel maintains a linked list of statistics structures, or kstats. Each
kstat has a common header section and a type-specific data section. The header
section is defined by the \fBkstat_t\fR structure:
.SS "kstat header"
.sp
.in +2
.nf
typedef   int kid_t;    /* unique kstat id */

typedef struct kstat {
   /*
    * Fields relevant to both kernel and user
    */
   hrtime_t      ks_crtime;               /* creation time */
   struct kstat  *ks_next;                /* kstat chain linkage */
   kid_t         ks_kid;                  /* unique kstat ID */
   char          ks_module[KSTAT_STRLEN]; /* module name */
   uchar_t       ks_resv;                 /* reserved */
   int           ks_instance;             /* module's instance */
   char          ks_name[KSTAT_STRLEN];   /* kstat name */
   uchar_t       ks_type;                 /* kstat data type */
   char          ks_class[KSTAT_STRLEN];  /* kstat class */
   uchar_t       ks_flags;                /* kstat flags */
   void          *ks_data;                /* kstat type-specific
                                             data */
   uint_t        ks_ndata;                /* # of data records */
   size_t        ks_data_size;            /* size of kstat data
                                             section */
   hrtime_t      ks_snaptime;             /* time of last data
                                             snapshot */

   /*
    * Fields relevant to kernel only
    */
   int(*ks_update)(struct kstat *, int);
   void  *ks_private;
   int(*ks_snapshot)(struct kstat *, void *, int);
   void  *ks_lock;
} kstat_t;
.fi
.in -2

.sp
.LP
The fields that are of significance to the user are:
.sp
.ne 2
.na
\fB\fBks_crtime\fR\fR
.ad
.RS 16n
The time the kstat was created. This allows you to compute the rates of various
counters since the kstat was created; "rate since boot" is replaced by the more
general concept of "rate since kstat creation". All times associated with
kstats (such as creation time, last snapshot time, \fBkstat_timer_t\fR and
\fBkstat_io_t\fR timestamps, and the like) are 64-bit nanosecond values. The
accuracy of kstat timestamps is machine dependent, but the precision (units) is
the same across all platforms. See \fBgethrtime\fR(3C) for general information
about high-resolution timestamps.
.RE

.sp
.ne 2
.na
\fB\fBks_next\fR\fR
.ad
.RS 16n
kstats are stored as a linked list, or chain. \fBks_next\fR points to the next
kstat in the chain.
.RE

.sp
.ne 2
.na
\fB\fBks_kid\fR\fR
.ad
.RS 16n
A unique identifier for the kstat.
.RE

.sp
.ne 2
.na
\fB\fBks_module\fR,\fR
.ad
.br
.na
\fB\fBks_instance\fR\fR
.ad
.RS 16n
contain the name and instance of the module that created the kstat. In cases
where there can only be one instance, \fBks_instance\fR is 0.
.RE

.sp
.ne 2
.na
\fB\fBks_name\fR\fR
.ad
.RS 16n
gives a meaningful name to a kstat. The full kstat namespace is
<\fBks_module\fR,\fBks_instance\fR,\fBks_name\fR>, so the name only need be
unique within a module.
.RE

.sp
.ne 2
.na
\fB\fBks_type\fR\fR
.ad
.RS 16n
The type of data in this kstat. kstat data types are discussed below.
.RE

.sp
.ne 2
.na
\fB\fBks_class\fR\fR
.ad
.RS 16n
Each kstat can be characterized as belonging to some broad class of statistics,
such as disk, tape, net, vm, and streams. This field can be used as a filter to
extract related kstats. The following values are currently in use: \fBdisk\fR,
\fBtape\fR, \fBcontroller\fR, \fBnet\fR, \fBrpc\fR, \fBvm\fR, \fBkvm\fR,
\fBhat\fR, \fBstreams\fR, \fBkmem\fR, \fBkmem_cache\fR, \fBkstat\fR, and
\fBmisc\fR. (The kstat class encompasses things like \fIkstat_types\fR.)
.RE

.sp
.ne 2
.na
\fB\fBks_data\fR,\fR
.ad
.br
.na
\fB\fBks_ndata\fR,\fR
.ad
.br
.na
\fB\fBks_data_size\fR\fR
.ad
.RS 16n
\fBks_data\fR is a pointer to the kstat's data section. The type of data stored
there depends on \fBks_type\fR. \fBks_ndata\fR indicates the number of data
records. Only some kstat types support multiple data records. Currently,
\fBKSTAT_TYPE_RAW\fR, \fBKSTAT_TYPE_NAMED\fR and \fBKSTAT_TYPE_TIMER\fR kstats
support multiple data records. \fBKSTAT_TYPE_INTR\fR and \fBKSTAT_TYPE_IO\fR
kstats support only one data record. \fBks_data_size\fR is the total size of
the data section, in bytes.
.RE

.sp
.ne 2
.na
\fB\fBks_snaptime\fR\fR
.ad
.RS 16n
The timestamp for the last data snapshot. This allows you to compute activity
rates:
.sp
\fBrate = (new_count - old_count) / (new_snaptime - old_snaptime);\fR
.RE

.SS "kstat data types"
.sp
.LP
The following types of kstats are currently available:
.sp
.in +2
.nf
#define KSTAT_TYPE_RAW    0   /* can be anything */
#define KSTAT_TYPE_NAMED  1   /* name/value pairs */
#define KSTAT_TYPE_INTR   2   /* interrupt statistics */
#define KSTAT_TYPE_IO     3   /* I/O statistics */
#define KSTAT_TYPE_TIMER  4   /* event timers */
.fi
.in -2

.sp
.LP
To get a list of all kstat types currently supported in the system, tools can
read out the standard system kstat \fIkstat_types\fR (full name spec is
\fI<``unix'', 0, ``kstat_types''>\fR). This is a \fBKSTAT_TYPE_NAMED\fR kstat
in which the \fIname\fR field describes the type of kstat, and the \fIvalue\fR
field is the kstat type number (for example, \fBKSTAT_TYPE_IO\fR is type 3 --
see above).
.SS "Raw kstat"
.sp
.ne 2
.na
\fB\fBKSTAT_TYPE_RAW\fR\fR
.ad
.RS 18n
raw data
.RE

.sp
.LP
The "raw" kstat type is just treated as an array of bytes. This is generally
used to export well-known structures, like \fIsysinfo\fR.
.SS "Name=value kstat"
.sp
.ne 2
.na
\fB\fBKSTAT_TYPE_NAMED\fR\fR
.ad
.RS 20n
A list of arbitrary \fIname=value\fR statistics.
.RE

.sp
.in +2
.nf
typedef struct kstat_named {
   char    name[KSTAT_STRLEN];    /* name of counter */
   uchar_t data_type;             /* data type */
   union {
            charc[16];            /* enough for 128-bit ints */
            struct {
               union {
                   char *ptr;    /* NULL-terminated string */
               } addr;
               uint32_t len;     /* length of string */
            } str;
            int32_t   i32;
            uint32_t  ui32;
            int64_t   i64;
            uint64_t  ui64;

  /* These structure members are obsolete */

            int32_t   l;
            uint32_t  ul;
            int64_t   ll;
            uint64_t  ull;
         } value;                /* value of counter */
} kstat_named_t;

/* The following types are Stable

KSTAT_DATA_CHAR
KSTAT_DATA_INT32
KSTAT_DATA_LONG
KSTAT_DATA_UINT32
KSTAT_DATA_ULONG
KSTAT_DATA_INT64
KSTAT_DATA_UINT64

/* The following type is Evolving */

KSTAT_DATA_STRING

/* The following types are Obsolete */

KSTAT_DATA_LONGLONG
KSTAT_DATA_ULONGLONG
KSTAT_DATA_FLOAT
KSTAT_DATA_DOUBLE
.fi
.in -2

.sp
.LP
Some devices need to publish strings that exceed the maximum value for
\fBKSTAT_DATA_CHAR\fR in length; \fBKSTAT_DATA_STRING\fR is a data type that
allows arbitrary-length strings to be associated with a named kstat. The macros
below are the supported means to read the pointer to the string and its length.
.sp
.in +2
.nf
#define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr)
#define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len)
.fi
.in -2
.sp

.sp
.LP
\fBKSTAT_NAMED_STR_BUFLEN()\fR returns the number of bytes required to store
the string pointed to by \fBKSTAT_NAMED_STR_PTR()\fR; that is,
\fBstrlen(KSTAT_NAMED_STR_PTR()) + 1\fR.
.SS "Interrupt kstat"
.sp
.ne 2
.na
\fB\fBKSTAT_TYPE_INTR\fR\fR
.ad
.RS 19n
Interrupt statistics.
.RE

.sp
.LP
An interrupt is a hard interrupt (sourced from the hardware device itself), a
soft interrupt (induced by the system via the use of some system interrupt
source), a watchdog interrupt (induced by a periodic timer call), spurious (an
interrupt entry point was entered but there was no interrupt to service), or
multiple service (an interrupt was detected and serviced just prior to
returning from any of the other types).
.sp
.in +2
.nf
#define KSTAT_INTR_HARD      0
#define KSTAT_INTR_SOFT      1
#define KSTAT_INTR_WATCHDOG  2
#define KSTAT_INTR_SPURIOUS  3
#define KSTAT_INTR_MULTSVC   4
#define KSTAT_NUM_INTRS      5

typedef struct kstat_intr {
   uint_t intrs[KSTAT_NUM_INTRS]; /* interrupt counters */
} kstat_intr_t;
.fi
.in -2

.SS "Event timer kstat"
.sp
.ne 2
.na
\fB\fBKSTAT_TYPE_TIMER\fR\fR
.ad
.RS 20n
Event timer statistics.
.RE

.sp
.LP
These provide basic counting and timing information for any type of event.
.sp
.in +2
.nf
typedef struct kstat_timer {
   char         name[KSTAT_STRLEN]; /* event name */
   uchar_t      resv;               /* reserved */
   u_longlong_t num_events;         /* number of events */
   hrtime_t     elapsed_time;       /* cumulative elapsed time */
   hrtime_t     min_time;           /* shortest event duration */
   hrtime_t     max_time;           /* longest event duration */
   hrtime_t     start_time;         /* previous event start time */
   hrtime_t     stop_time;          /* previous event stop time */
} kstat_timer_t;
.fi
.in -2

.SS "I/O kstat"
.sp
.ne 2
.na
\fB\fBKSTAT_TYPE_IO\fR\fR
.ad
.RS 17n
I/O statistics.
.RE

.sp
.in +2
.nf
typedef struct kstat_io {
/*
 * Basic counters.
 */
u_longlong_t     nread;      /* number of bytes read */
u_longlong_t     nwritten;   /* number of bytes written */
uint_t           reads;      /* number of read operations */
uint_t           writes;     /* number of write operations */
/*
* Accumulated time and queue length statistics.
*
* Time statistics are kept as a running sum of "active" time.
* Queue length statistics are kept as a running sum of the
* product of queue length and elapsed time at that length --
* that is, a Riemann sum for queue length integrated against time.
*
*               ^
*               |                       _________
*               8                       | i4    |
*               |                       |       |
*       Queue   6                       |       |
*       Length  |       _________       |       |
*               4       | i2    |_______|       |
*               |       |       i3              |
*               2_______|                       |
*               |    i1                         |
*               |_______________________________|
*               Time->  t1      t2      t3      t4
*
* At each change of state (entry or exit from the queue),
* we add the elapsed time (since the previous state change)
* to the active time if the queue length was non-zero during
* that interval; and we add the product of the elapsed time
* times the queue length to the running length*time sum.
*
* This method is generalizable to measuring residency
* in any defined system: instead of queue lengths, think
* of "outstanding RPC calls to server X".
*
* A large number of I/O subsystems have at least two basic
* "lists" of transactions they manage: one for transactions
* that have been accepted for processing but for which processing
* has yet to begin, and one for transactions which are actively
* being processed (but not done). For this reason, two cumulative
* time statistics are defined here: pre-service (wait) time,
* and service (run) time.
*
* The units of cumulative busy time are accumulated nanoseconds.
* The units of cumulative length*time products are elapsed time
* times queue length.
*/
hrtime_t   wtime;            /* cumulative wait (pre-service) time */
hrtime_t   wlentime;         /* cumulative wait length*time product*/
hrtime_t   wlastupdate;      /* last time wait queue changed */
hrtime_t   rtime;            /* cumulative run (service) time */
hrtime_t   rlentime;         /* cumulative run length*time product */
hrtime_t   rlastupdate;      /* last time run queue changed */
uint_t     wcnt;             /* count of elements in wait state */
uint_t     rcnt;             /* count of elements in run state */
} kstat_io_t;
.fi
.in -2
.sp

.SS "Using libkstat"
.sp
.LP
The kstat library, \fBlibkstat\fR, defines the user interface (API) to the
system's kstat facility.
.sp
.LP
You begin by opening libkstat with \fBkstat_open\fR(3KSTAT), which returns a
pointer to a fully initialized kstat control structure. This is your ticket to
subsequent libkstat operations:
.sp
.in +2
.nf
typedef struct kstat_ctl {
   kid_t     kc_chain_id;    /* current kstat chain ID */
   kstat_t   *kc_chain;      /* pointer to kstat chain */
   int       kc_kd;          /* /dev/kstat descriptor */
} kstat_ctl_t;
.fi
.in -2

.sp
.LP
Only the first two fields, \fBkc_chain_id\fR and \fBkc_chain\fR, are of
interest to \fBlibkstat\fR clients. (\fIkc_kd\fR is the descriptor for
\fB/dev/kstat\fR, the kernel statistics driver. libkstat functions are built on
top of \fB/dev/kstat\fR \fBioctl\fR(2) primitives. Direct interaction with
\fB/dev/kstat\fR is strongly discouraged, since it is \fInot\fR a public
interface.)
.sp
.LP
\fBkc_chain\fR points to your copy of the kstat chain. You typically walk the
chain to find and process a certain kind of kstat. For example, to display all
\fBI/O\fR kstats:
.sp
.in +2
.nf
kstat_ctl_t    *kc;
kstat_t        *ksp;
kstat_io_t     kio;

kc = kstat_open();
for (ksp = kc->kc_chain; ksp != NULL; ksp = ksp->ks_next) {
        if (ksp->ks_type == KSTAT_TYPE_IO) {
              kstat_read(kc, ksp, &kio);
                my_io_display(kio);
        }
}
.fi
.in -2

.sp
.LP
\fBkc_chain_id\fR is the kstat chain \fBID\fR, or \fBKCID\fR, of your copy of
the kstat chain. See \fBkstat_chain_update\fR(3KSTAT) for an explanation of
\fBKCID\fRs.
.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/kstat\fR\fR
.ad
.RS 28n
kernel statistics driver
.RE

.sp
.ne 2
.na
\fB\fB/usr/include/kstat.h\fR\fR
.ad
.RS 28n
header
.RE

.sp
.ne 2
.na
\fB\fB/usr/include/sys/kstat.h\fR\fR
.ad
.RS 28n
header
.RE

.SH SEE ALSO
.sp
.LP
\fBioctl\fR(2), \fBgethrtime\fR(3C), \fBgetloadavg\fR(3C),
\fBkstat_chain_update\fR(3KSTAT), \fBkstat_close\fR(3KSTAT),
\fBkstat_data_lookup\fR(3KSTAT), \fBkstat_lookup\fR(3KSTAT),
\fBkstat_open\fR(3KSTAT), \fBkstat_read\fR(3KSTAT), \fBkstat_write\fR(3KSTAT),
\fBattributes\fR(5)