kstat(3kstat) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨페이지이름
검색(S)

kstat(3kstat)

Name
     kstat - kernel statistics facility

Description
     The kstat facility is a general-purpose mechanism  for  pro-
     viding 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 section. The header section is defined by
     the kstat_t structure:

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



     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 con-
                     cept of "rate  since  kstat  creation".  All
                     times  associated with kstats (such as crea-
                     tion 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
                     information  about  high-resolution   times-
                     tamps.


     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,
     ks_instance
                     contain the name and instance of the  module
                     that created 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  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_ndata,
     ks_data_size
                     ks_data is a pointer  to  the  kstat's  data
                     section.  The  type  of  data  stored  there
                     depends on ks_type. ks_ndata  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 generally used to export well-known structures, like
     sysinfo.

  Name=value kstat
     KSTAT_TYPE_NAMED
                         A list of arbitrary  name=value  statis-
                         tics.

       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 Committed

       KSTAT_DATA_CHAR
       KSTAT_DATA_INT32
       KSTAT_DATA_LONG
       KSTAT_DATA_STRING
       KSTAT_DATA_UINT32
       KSTAT_DATA_ULONG
       KSTAT_DATA_INT64
       KSTAT_DATA_UINT64

       /* 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 associ-
     ated  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.str.addr.ptr)
       #define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.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  inter-
     rupt (induced by a periodic timer call), spurious (an inter-
     rupt 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 opera-
     tions:

       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  typi-
     cally  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
                                 header


     /usr/include/sys/kstat.h
                                 header

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)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3