home | help
kstat(3KSTAT)	       Kernel Statistics Library Functions	   kstat(3KSTAT)

NAME
     kstat - kernel statistics facility

DESCRIPTION
     The kstat facility is a general-purpose mechanism for providing kernel sta-
     tistics to users.

   The kstat model
     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 kstat_t structure:

   kstat header
     typedef   intkid_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;

     The fields that are of significance to the user are:

     ks_crtime	     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,
		     kstat_timer_t and kstat_io_t 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 gethrtime(3C) for general  infor-
		     mation about high-resolution timestamps.

     ks_next	     kstats  are  stored  as  a  linked  list, or chain. ks_next
		     points to the next kstat in the chain.

     ks_kid	     A unique identifier for the kstat.

     ks_module,      contain the name and instance of the  module  that  created
     ks_instance     the  kstat.  In cases where there can only be one instance,
		     ks_instance is 0.

     ks_name	     gives a meaningful name to a kstat. The  full  kstat  name-
		     space  is <ks_module,ks_instance,ks_name>, so the name only
		     need be unique within a module.

     ks_type	     The type of data in this kstat. kstat data types  are  dis-
		     cussed below.

     ks_class	     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 re-
		     lated kstats. The following values are  currently	in  use:
		     disk,  tape,  controller,	net, rpc, vm, kvm, hat, streams,
		     kmem, kmem_cache, kstat, and misc. (The kstat class  encom-
		     passes things like kstat_types.)

     ks_data,	     ks_data  is a pointer to the kstat's data section. The type
     ks_ndata,	     of data stored there depends on ks_type. ks_ndata indicates
     ks_data_size    the number of data records. Only some kstat  types  support
		     multiple	 data	 records.   Currently,	 KSTAT_TYPE_RAW,
		     KSTAT_TYPE_NAMED and KSTAT_TYPE_TIMER kstats support multi-
		     ple data records. KSTAT_TYPE_INTR and KSTAT_TYPE_IO  kstats
		     support  only  one  data  record. ks_data_size is the total
		     size of the data section, in bytes.

     ks_snaptime     The timestamp for the last data snapshot. This  allows  you
		     to compute activity rates:

		     rate = (new_count - old_count) / (new_snaptime - old_snaptime);

   kstat data types
     The following types of kstats are currently available:

     #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 */

     To  get  a list of all kstat types currently supported in the system, tools
     can read out the standard system  kstat  kstat_types  (full  name	spec  is
     <``unix'',  0, ``kstat_types''>). This is a KSTAT_TYPE_NAMED kstat in which
     the name field describes the type of kstat, and  the  value  field  is  the
     kstat type number (for example, KSTAT_TYPE_IO is type 3 -- see above).

   Raw kstat
     KSTAT_TYPE_RAW	     raw data

     The  "raw"  kstat type is just treated as an array of bytes. This is gener-
     ally used to export well-known structures, like sysinfo.

   Name=value kstat
     KSTAT_TYPE_NAMED	     A list of arbitrary name=value statistics.

     typedef struct kstat_named {
	charname[KSTAT_STRLEN];        /* name of counter */
	uchar_tdata_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 */
		 } string;
		 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

     Some devices need to publish strings that	exceed	the  maximum  value  for
     KSTAT_DATA_CHAR in length; KSTAT_DATA_STRING is a data type that allows ar-
     bitrary-length  strings to be associated with a named kstat. The macros be-
     low are the supported means to read the  pointer  to  the	string	and  its
     length.

     #define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.string.addr.ptr)
     #define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.string.len)

     KSTAT_NAMED_STR_BUFLEN()  returns the number of bytes required to store the
     string    pointed	   to	  by	 KSTAT_NAMED_STR_PTR();     that     is,
     strlen(KSTAT_NAMED_STR_PTR()) + 1.

   Interrupt kstat
     KSTAT_TYPE_INTR	     Interrupt statistics.

     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 inter-
     rupt source), a watchdog interrupt (induced by a periodic timer call), spu-
     rious (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).

     #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;

   Event timer kstat
     KSTAT_TYPE_TIMER	     Event timer statistics.

     These provide basic counting and timing information for any type of event.

     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;

   I/O kstat
     KSTAT_TYPE_IO	     I/O statistics.

     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;

   Using libkstat
     The kstat library, libkstat, defines the user interface (API) to  the  sys-
     tem's kstat facility.

     You  begin  by  opening  libkstat	with kstat_open(3KSTAT), which returns a
     pointer to a fully initialized kstat control structure. This is your ticket
     to subsequent libkstat operations:

     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;

     Only the first two fields, kc_chain_id and kc_chain,  are	of  interest  to
     libkstat  clients. (kc_kd is the descriptor for /dev/kstat, the kernel sta-
     tistics driver. libkstat functions are built on top of /dev/kstat	ioctl(2)
     primitives.  Direct  interaction  with  /dev/kstat is strongly discouraged,
     since it is not a public interface.)

     kc_chain 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 I/O kstats:

     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);
	     }
     }

     kc_chain_id is the kstat chain ID, or KCID,  of  your  copy  of  the  kstat
     chain. See kstat_chain_update(3KSTAT) for an explanation of KCIDs.

FILES
     /dev/kstat 		     kernel statistics driver

     /usr/include/kstat.h

     /usr/include/sys/kstat.h

SEE ALSO
     ioctl(2),	  gethrtime(3C),   getloadavg(3C),   kstat_chain_update(3KSTAT),
     kstat_close(3KSTAT),    kstat_data_lookup(3KSTAT),    kstat_lookup(3KSTAT),
     kstat_open(3KSTAT), kstat_read(3KSTAT), kstat_write(3KSTAT), attributes(5)

SunOS 5.10			   25 Apr 2002			   kstat(3KSTAT)

home | help