1kstat(3KSTAT)         Kernel Statistics Library Functions        kstat(3KSTAT)
2
3
4

NAME

6       kstat - kernel statistics facility
7

DESCRIPTION

9       The  kstat facility is a general-purpose mechanism for providing kernel
10       statistics to users.
11
12   The kstat model
13       The kernel maintains a linked list of statistics structures, or kstats.
14       Each  kstat  has  a common header section and a type-specific data sec‐
15       tion. The header section is defined by the kstat_t structure:
16
17   kstat header
18         typedef   int kid_t;    /* unique kstat id */
19
20         typedef struct kstat {
21            /*
22             * Fields relevant to both kernel and user
23             */
24            hrtime_t      ks_crtime;               /* creation time */
25            struct kstat  *ks_next;                /* kstat chain linkage */
26            kid_t         ks_kid;                  /* unique kstat ID */
27            char          ks_module[KSTAT_STRLEN]; /* module name */
28            uchar_t       ks_resv;                 /* reserved */
29            int           ks_instance;             /* module's instance */
30            char          ks_name[KSTAT_STRLEN];   /* kstat name */
31            uchar_t       ks_type;                 /* kstat data type */
32            char          ks_class[KSTAT_STRLEN];  /* kstat class */
33            uchar_t       ks_flags;                /* kstat flags */
34            void          *ks_data;                /* kstat type-specific
35                                                      data */
36            uint_t        ks_ndata;                /* # of data records */
37            size_t        ks_data_size;            /* size of kstat data
38                                                      section */
39            hrtime_t      ks_snaptime;             /* time of last data
40                                                      snapshot */
41
42            /*
43             * Fields relevant to kernel only
44             */
45            int(*ks_update)(struct kstat *, int);
46            void  *ks_private;
47            int(*ks_snapshot)(struct kstat *, void *, int);
48            void  *ks_lock;
49         } kstat_t;
50
51
52
53       The fields that are of significance to the user are:
54
55       ks_crtime       The time the kstat was created. This allows you to com‐
56                       pute  the rates of various counters since the kstat was
57                       created; "rate since boot" is replaced by the more gen‐
58                       eral  concept of "rate since kstat creation". All times
59                       associated with kstats (such  as  creation  time,  last
60                       snapshot time, kstat_timer_t and kstat_io_t timestamps,
61                       and the like) are 64-bit nanosecond values.  The  accu‐
62                       racy  of kstat timestamps is machine dependent, but the
63                       precision (units) is the same across all platforms. See
64                       gethrtime(3C)  for general information about high-reso‐
65                       lution timestamps.
66
67
68       ks_next         kstats are stored as a linked list, or  chain.  ks_next
69                       points to the next kstat in the chain.
70
71
72       ks_kid          A unique identifier for the kstat.
73
74
75       ks_module,      contain  the  name and instance of the module that cre‐
76       ks_instance     ated the kstat. In cases where there can  only  be  one
77                       instance, ks_instance is 0.
78
79
80       ks_name         gives  a  meaningful  name  to  a kstat. The full kstat
81                       namespace is  <ks_module,ks_instance,ks_name>,  so  the
82                       name only need be unique within a module.
83
84
85       ks_type         The  type  of  data in this kstat. kstat data types are
86                       discussed below.
87
88
89       ks_class        Each kstat can be characterized as  belonging  to  some
90                       broad class of statistics, such as disk, tape, net, vm,
91                       and streams. This field can be  used  as  a  filter  to
92                       extract  related  kstats. The following values are cur‐
93                       rently in use: disk, tape, controller,  net,  rpc,  vm,
94                       kvm,  hat,  streams, kmem, kmem_cache, kstat, and misc.
95                       (The kstat class encompasses things like kstat_types.)
96
97
98       ks_data,        ks_data is a pointer to the kstat's data  section.  The
99       ks_ndata,       type  of data stored there depends on ks_type. ks_ndata
100       ks_data_size    indicates the number of data records. Only  some  kstat
101                       types   support   multiple   data  records.  Currently,
102                       KSTAT_TYPE_RAW, KSTAT_TYPE_NAMED  and  KSTAT_TYPE_TIMER
103                       kstats  support  multiple data records. KSTAT_TYPE_INTR
104                       and KSTAT_TYPE_IO kstats support only one data  record.
105                       ks_data_size  is the total size of the data section, in
106                       bytes.
107
108
109       ks_snaptime     The timestamp for the last data snapshot.  This  allows
110                       you to compute activity rates:
111
112                       rate  =  (new_count  -  old_count)  /  (new_snaptime  -
113                       old_snaptime);
114
115
116   kstat data types
117       The following types of kstats are currently available:
118
119         #define KSTAT_TYPE_RAW    0   /* can be anything */
120         #define KSTAT_TYPE_NAMED  1   /* name/value pairs */
121         #define KSTAT_TYPE_INTR   2   /* interrupt statistics */
122         #define KSTAT_TYPE_IO     3   /* I/O statistics */
123         #define KSTAT_TYPE_TIMER  4   /* event timers */
124
125
126
127       To get a list of all kstat types currently  supported  in  the  system,
128       tools  can  read  out  the standard system kstat kstat_types (full name
129       spec is <``unix'', 0, ``kstat_types''>).  This  is  a  KSTAT_TYPE_NAMED
130       kstat  in  which  the  name  field describes the type of kstat, and the
131       value field is the kstat type number  (for  example,  KSTAT_TYPE_IO  is
132       type 3 -- see above).
133
134   Raw kstat
135       KSTAT_TYPE_RAW    raw data
136
137
138
139       The "raw" kstat type is just treated as an array of bytes. This is gen‐
140       erally used to export well-known structures, like sysinfo.
141
142   Name=value kstat
143       KSTAT_TYPE_NAMED    A list of arbitrary name=value statistics.
144
145
146         typedef struct kstat_named {
147            char    name[KSTAT_STRLEN];    /* name of counter */
148            uchar_t data_type;             /* data type */
149            union {
150                     charc[16];            /* enough for 128-bit ints */
151                     struct {
152                        union {
153                            char *ptr;    /* NULL-terminated string */
154                        } addr;
155                        uint32_t len;     /* length of string */
156                     } str;
157                     int32_t   i32;
158                     uint32_t  ui32;
159                     int64_t   i64;
160                     uint64_t  ui64;
161
162           /* These structure members are obsolete */
163
164                     int32_t   l;
165                     uint32_t  ul;
166                     int64_t   ll;
167                     uint64_t  ull;
168                  } value;                /* value of counter */
169         } kstat_named_t;
170
171         /* The following types are Stable
172
173         KSTAT_DATA_CHAR
174         KSTAT_DATA_INT32
175         KSTAT_DATA_LONG
176         KSTAT_DATA_UINT32
177         KSTAT_DATA_ULONG
178         KSTAT_DATA_INT64
179         KSTAT_DATA_UINT64
180
181         /* The following type is Evolving */
182
183         KSTAT_DATA_STRING
184
185         /* The following types are Obsolete */
186
187         KSTAT_DATA_LONGLONG
188         KSTAT_DATA_ULONGLONG
189         KSTAT_DATA_FLOAT
190         KSTAT_DATA_DOUBLE
191
192
193
194       Some devices need to publish strings that exceed the maximum value  for
195       KSTAT_DATA_CHAR in length; KSTAT_DATA_STRING is a data type that allows
196       arbitrary-length strings to be  associated  with  a  named  kstat.  The
197       macros  below are the supported means to read the pointer to the string
198       and its length.
199
200         #define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr)
201         #define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len)
202
203
204
205
206       KSTAT_NAMED_STR_BUFLEN() returns the number of bytes required to  store
207       the    string   pointed   to   by   KSTAT_NAMED_STR_PTR();   that   is,
208       strlen(KSTAT_NAMED_STR_PTR()) + 1.
209
210   Interrupt kstat
211       KSTAT_TYPE_INTR    Interrupt statistics.
212
213
214
215       An interrupt is a hard interrupt  (sourced  from  the  hardware  device
216       itself),  a  soft  interrupt (induced by the system via the use of some
217       system interrupt source), a watchdog interrupt (induced by  a  periodic
218       timer  call),  spurious (an interrupt entry point was entered but there
219       was no interrupt to service), or multiple  service  (an  interrupt  was
220       detected  and  serviced  just  prior to returning from any of the other
221       types).
222
223         #define KSTAT_INTR_HARD      0
224         #define KSTAT_INTR_SOFT      1
225         #define KSTAT_INTR_WATCHDOG  2
226         #define KSTAT_INTR_SPURIOUS  3
227         #define KSTAT_INTR_MULTSVC   4
228         #define KSTAT_NUM_INTRS      5
229
230         typedef struct kstat_intr {
231            uint_t intrs[KSTAT_NUM_INTRS]; /* interrupt counters */
232         } kstat_intr_t;
233
234
235   Event timer kstat
236       KSTAT_TYPE_TIMER    Event timer statistics.
237
238
239
240       These provide basic counting and timing information  for  any  type  of
241       event.
242
243         typedef struct kstat_timer {
244            char         name[KSTAT_STRLEN]; /* event name */
245            uchar_t      resv;               /* reserved */
246            u_longlong_t num_events;         /* number of events */
247            hrtime_t     elapsed_time;       /* cumulative elapsed time */
248            hrtime_t     min_time;           /* shortest event duration */
249            hrtime_t     max_time;           /* longest event duration */
250            hrtime_t     start_time;         /* previous event start time */
251            hrtime_t     stop_time;          /* previous event stop time */
252         } kstat_timer_t;
253
254
255   I/O kstat
256       KSTAT_TYPE_IO    I/O statistics.
257
258
259         typedef struct kstat_io {
260         /*
261          * Basic counters.
262          */
263         u_longlong_t     nread;      /* number of bytes read */
264         u_longlong_t     nwritten;   /* number of bytes written */
265         uint_t           reads;      /* number of read operations */
266         uint_t           writes;     /* number of write operations */
267         /*
268         * Accumulated time and queue length statistics.
269         *
270         * Time statistics are kept as a running sum of "active" time.
271         * Queue length statistics are kept as a running sum of the
272         * product of queue length and elapsed time at that length --
273         * that is, a Riemann sum for queue length integrated against time.
274         *
275         *               ^
276         *               |                       _________
277         *               8                       | i4    |
278         *               |                       |       |
279         *       Queue   6                       |       |
280         *       Length  |       _________       |       |
281         *               4       | i2    |_______|       |
282         *               |       |       i3              |
283         *               2_______|                       |
284         *               |    i1                         |
285         *               |_______________________________|
286         *               Time->  t1      t2      t3      t4
287         *
288         * At each change of state (entry or exit from the queue),
289         * we add the elapsed time (since the previous state change)
290         * to the active time if the queue length was non-zero during
291         * that interval; and we add the product of the elapsed time
292         * times the queue length to the running length*time sum.
293         *
294         * This method is generalizable to measuring residency
295         * in any defined system: instead of queue lengths, think
296         * of "outstanding RPC calls to server X".
297         *
298         * A large number of I/O subsystems have at least two basic
299         * "lists" of transactions they manage: one for transactions
300         * that have been accepted for processing but for which processing
301         * has yet to begin, and one for transactions which are actively
302         * being processed (but not done). For this reason, two cumulative
303         * time statistics are defined here: pre-service (wait) time,
304         * and service (run) time.
305         *
306         * The units of cumulative busy time are accumulated nanoseconds.
307         * The units of cumulative length*time products are elapsed time
308         * times queue length.
309         */
310         hrtime_t   wtime;            /* cumulative wait (pre-service) time */
311         hrtime_t   wlentime;         /* cumulative wait length*time product*/
312         hrtime_t   wlastupdate;      /* last time wait queue changed */
313         hrtime_t   rtime;            /* cumulative run (service) time */
314         hrtime_t   rlentime;         /* cumulative run length*time product */
315         hrtime_t   rlastupdate;      /* last time run queue changed */
316         uint_t     wcnt;             /* count of elements in wait state */
317         uint_t     rcnt;             /* count of elements in run state */
318         } kstat_io_t;
319
320
321
322   Using libkstat
323       The  kstat  library,  libkstat, defines the user interface (API) to the
324       system's kstat facility.
325
326
327       You begin by opening libkstat with kstat_open(3KSTAT), which returns  a
328       pointer  to  a  fully initialized kstat control structure. This is your
329       ticket to subsequent libkstat operations:
330
331         typedef struct kstat_ctl {
332            kid_t     kc_chain_id;    /* current kstat chain ID */
333            kstat_t   *kc_chain;      /* pointer to kstat chain */
334            int       kc_kd;          /* /dev/kstat descriptor */
335         } kstat_ctl_t;
336
337
338
339       Only the first two fields, kc_chain_id and kc_chain, are of interest to
340       libkstat  clients.  (kc_kd is the descriptor for /dev/kstat, the kernel
341       statistics driver. libkstat functions are built on  top  of  /dev/kstat
342       ioctl(2)  primitives.  Direct  interaction  with /dev/kstat is strongly
343       discouraged, since it is not a public interface.)
344
345
346       kc_chain points to your copy of the kstat chain. You typically walk the
347       chain to find and process a certain kind of kstat. For example, to dis‐
348       play all I/O kstats:
349
350         kstat_ctl_t    *kc;
351         kstat_t        *ksp;
352         kstat_io_t     kio;
353
354         kc = kstat_open();
355         for (ksp = kc->kc_chain; ksp != NULL; ksp = ksp->ks_next) {
356                 if (ksp->ks_type == KSTAT_TYPE_IO) {
357                       kstat_read(kc, ksp, &kio);
358                         my_io_display(kio);
359                 }
360         }
361
362
363
364       kc_chain_id is the kstat chain ID, or KCID, of your copy of  the  kstat
365       chain. See kstat_chain_update(3KSTAT) for an explanation of KCIDs.
366

FILES

368       /dev/kstat                  kernel statistics driver
369
370
371       /usr/include/kstat.h        header
372
373
374       /usr/include/sys/kstat.h    header
375
376

SEE ALSO

378       ioctl(2),  gethrtime(3C),  getloadavg(3C),  kstat_chain_update(3KSTAT),
379       kstat_close(3KSTAT),  kstat_data_lookup(3KSTAT),  kstat_lookup(3KSTAT),
380       kstat_open(3KSTAT),       kstat_read(3KSTAT),      kstat_write(3KSTAT),
381       attributes(5)
382
383
384
385SunOS 5.11                        29 Jan 2007                    kstat(3KSTAT)
Impressum