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
		       extract	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
       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).

       #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),
       attributes(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