Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       statistics 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 sec-
       tion. 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 com-
		       pute  the rates of various counters since the kstat was
		       created;	"rate since boot" is replaced by the more gen-
		       eral  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	 accu-
		       racy  of	kstat timestamps is machine dependent, but the
		       precision (units) is the	same across all	platforms. See
		       gethrtime(3C)  for general information about high-reso-
		       lution 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 cre-
       ks_instance     ated 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
		       namespace 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
		       discussed 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  ex-
		       tract  related  kstats.	The  following values are cur-
		       rently in use: disk, tape, controller,  net,  rpc,  vm,
		       kvm,  hat,  streams, kmem, kmem_cache, kstat, and misc.
		       (The kstat class	encompasses things like	kstat_types.)

       ks_data,	       ks_data is a pointer to the kstat's data	 section.  The
       ks_ndata,       type  of	data stored there depends on ks_type. ks_ndata
       ks_data_size    indicates 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	multiple 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 gen-
       erally 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
       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.

       #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 it-
       self), a	soft interrupt (induced	by the system via the use of some sys-
       tem  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 de-
       tected 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
       system'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
       statistics  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 dis-
       play 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),	   at-
       tributes(5)

SunOS 5.10			  25 Apr 2002			 kstat(3KSTAT)

NAME | DESCRIPTION | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=kstat&sektion=3&manpath=SunOS+5.10>

home | help