| blob | d0b45d94e6d1cf2375ae18982078264ce8369103 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH KSTAT 3KSTAT "Jan 29, 2007"
7 .SH NAME
8 kstat \- kernel statistics facility
9 .SH DESCRIPTION
10 .sp
11 .LP
12 The \fBkstat\fR facility is a general-purpose mechanism for providing kernel
13 statistics to users.
14 .SS "The kstat model"
15 .sp
16 .LP
17 The kernel maintains a linked list of statistics structures, or kstats. Each
18 kstat has a common header section and a type-specific data section. The header
19 section is defined by the \fBkstat_t\fR structure:
20 .SS "kstat header"
21 .sp
22 .in +2
23 .nf
24 typedef int kid_t; /* unique kstat id */
26 typedef struct kstat {
27 /*
28 * Fields relevant to both kernel and user
29 */
30 hrtime_t ks_crtime; /* creation time */
31 struct kstat *ks_next; /* kstat chain linkage */
32 kid_t ks_kid; /* unique kstat ID */
33 char ks_module[KSTAT_STRLEN]; /* module name */
34 uchar_t ks_resv; /* reserved */
35 int ks_instance; /* module's instance */
36 char ks_name[KSTAT_STRLEN]; /* kstat name */
37 uchar_t ks_type; /* kstat data type */
38 char ks_class[KSTAT_STRLEN]; /* kstat class */
39 uchar_t ks_flags; /* kstat flags */
40 void *ks_data; /* kstat type-specific
41 data */
42 uint_t ks_ndata; /* # of data records */
43 size_t ks_data_size; /* size of kstat data
44 section */
45 hrtime_t ks_snaptime; /* time of last data
46 snapshot */
48 /*
49 * Fields relevant to kernel only
50 */
51 int(*ks_update)(struct kstat *, int);
52 void *ks_private;
53 int(*ks_snapshot)(struct kstat *, void *, int);
54 void *ks_lock;
55 } kstat_t;
56 .fi
57 .in -2
59 .sp
60 .LP
61 The fields that are of significance to the user are:
62 .sp
63 .ne 2
64 .na
65 \fB\fBks_crtime\fR\fR
66 .ad
67 .RS 16n
68 The time the kstat was created. This allows you to compute the rates of various
69 counters since the kstat was created; "rate since boot" is replaced by the more
70 general concept of "rate since kstat creation". All times associated with
71 kstats (such as creation time, last snapshot time, \fBkstat_timer_t\fR and
72 \fBkstat_io_t\fR timestamps, and the like) are 64-bit nanosecond values. The
73 accuracy of kstat timestamps is machine dependent, but the precision (units) is
74 the same across all platforms. See \fBgethrtime\fR(3C) for general information
75 about high-resolution timestamps.
76 .RE
78 .sp
79 .ne 2
80 .na
81 \fB\fBks_next\fR\fR
82 .ad
83 .RS 16n
84 kstats are stored as a linked list, or chain. \fBks_next\fR points to the next
85 kstat in the chain.
86 .RE
88 .sp
89 .ne 2
90 .na
91 \fB\fBks_kid\fR\fR
92 .ad
93 .RS 16n
94 A unique identifier for the kstat.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fBks_module\fR,\fR
101 .ad
102 .br
103 .na
104 \fB\fBks_instance\fR\fR
105 .ad
106 .RS 16n
107 contain the name and instance of the module that created the kstat. In cases
108 where there can only be one instance, \fBks_instance\fR is 0.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fBks_name\fR\fR
115 .ad
116 .RS 16n
117 gives a meaningful name to a kstat. The full kstat namespace is
118 <\fBks_module\fR,\fBks_instance\fR,\fBks_name\fR>, so the name only need be
119 unique within a module.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fBks_type\fR\fR
126 .ad
127 .RS 16n
128 The type of data in this kstat. kstat data types are discussed below.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fBks_class\fR\fR
135 .ad
136 .RS 16n
137 Each kstat can be characterized as belonging to some broad class of statistics,
138 such as disk, tape, net, vm, and streams. This field can be used as a filter to
139 extract related kstats. The following values are currently in use: \fBdisk\fR,
140 \fBtape\fR, \fBcontroller\fR, \fBnet\fR, \fBrpc\fR, \fBvm\fR, \fBkvm\fR,
141 \fBhat\fR, \fBstreams\fR, \fBkmem\fR, \fBkmem_cache\fR, \fBkstat\fR, and
142 \fBmisc\fR. (The kstat class encompasses things like \fIkstat_types\fR.)
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBks_data\fR,\fR
149 .ad
150 .br
151 .na
152 \fB\fBks_ndata\fR,\fR
153 .ad
154 .br
155 .na
156 \fB\fBks_data_size\fR\fR
157 .ad
158 .RS 16n
159 \fBks_data\fR is a pointer to the kstat's data section. The type of data stored
160 there depends on \fBks_type\fR. \fBks_ndata\fR indicates the number of data
161 records. Only some kstat types support multiple data records. Currently,
162 \fBKSTAT_TYPE_RAW\fR, \fBKSTAT_TYPE_NAMED\fR and \fBKSTAT_TYPE_TIMER\fR kstats
163 support multiple data records. \fBKSTAT_TYPE_INTR\fR and \fBKSTAT_TYPE_IO\fR
164 kstats support only one data record. \fBks_data_size\fR is the total size of
165 the data section, in bytes.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fBks_snaptime\fR\fR
172 .ad
173 .RS 16n
174 The timestamp for the last data snapshot. This allows you to compute activity
175 rates:
176 .sp
177 \fBrate = (new_count - old_count) / (new_snaptime - old_snaptime);\fR
178 .RE
180 .SS "kstat data types"
181 .sp
182 .LP
183 The following types of kstats are currently available:
184 .sp
185 .in +2
186 .nf
187 #define KSTAT_TYPE_RAW 0 /* can be anything */
188 #define KSTAT_TYPE_NAMED 1 /* name/value pairs */
189 #define KSTAT_TYPE_INTR 2 /* interrupt statistics */
190 #define KSTAT_TYPE_IO 3 /* I/O statistics */
191 #define KSTAT_TYPE_TIMER 4 /* event timers */
192 .fi
193 .in -2
195 .sp
196 .LP
197 To get a list of all kstat types currently supported in the system, tools can
198 read out the standard system kstat \fIkstat_types\fR (full name spec is
199 \fI<``unix'', 0, ``kstat_types''>\fR). This is a \fBKSTAT_TYPE_NAMED\fR kstat
200 in which the \fIname\fR field describes the type of kstat, and the \fIvalue\fR
201 field is the kstat type number (for example, \fBKSTAT_TYPE_IO\fR is type 3 --
202 see above).
203 .SS "Raw kstat"
204 .sp
205 .ne 2
206 .na
207 \fB\fBKSTAT_TYPE_RAW\fR\fR
208 .ad
209 .RS 18n
210 raw data
211 .RE
213 .sp
214 .LP
215 The "raw" kstat type is just treated as an array of bytes. This is generally
216 used to export well-known structures, like \fIsysinfo\fR.
217 .SS "Name=value kstat"
218 .sp
219 .ne 2
220 .na
221 \fB\fBKSTAT_TYPE_NAMED\fR\fR
222 .ad
223 .RS 20n
224 A list of arbitrary \fIname=value\fR statistics.
225 .RE
227 .sp
228 .in +2
229 .nf
230 typedef struct kstat_named {
231 char name[KSTAT_STRLEN]; /* name of counter */
232 uchar_t data_type; /* data type */
233 union {
234 charc[16]; /* enough for 128-bit ints */
235 struct {
236 union {
237 char *ptr; /* NULL-terminated string */
238 } addr;
239 uint32_t len; /* length of string */
240 } str;
241 int32_t i32;
242 uint32_t ui32;
243 int64_t i64;
244 uint64_t ui64;
246 /* These structure members are obsolete */
248 int32_t l;
249 uint32_t ul;
250 int64_t ll;
251 uint64_t ull;
252 } value; /* value of counter */
253 } kstat_named_t;
255 /* The following types are Stable
257 KSTAT_DATA_CHAR
258 KSTAT_DATA_INT32
259 KSTAT_DATA_LONG
260 KSTAT_DATA_UINT32
261 KSTAT_DATA_ULONG
262 KSTAT_DATA_INT64
263 KSTAT_DATA_UINT64
265 /* The following type is Evolving */
267 KSTAT_DATA_STRING
269 /* The following types are Obsolete */
271 KSTAT_DATA_LONGLONG
272 KSTAT_DATA_ULONGLONG
273 KSTAT_DATA_FLOAT
274 KSTAT_DATA_DOUBLE
275 .fi
276 .in -2
278 .sp
279 .LP
280 Some devices need to publish strings that exceed the maximum value for
281 \fBKSTAT_DATA_CHAR\fR in length; \fBKSTAT_DATA_STRING\fR is a data type that
282 allows arbitrary-length strings to be associated with a named kstat. The macros
283 below are the supported means to read the pointer to the string and its length.
284 .sp
285 .in +2
286 .nf
287 #define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr)
288 #define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len)
289 .fi
290 .in -2
291 .sp
293 .sp
294 .LP
295 \fBKSTAT_NAMED_STR_BUFLEN()\fR returns the number of bytes required to store
296 the string pointed to by \fBKSTAT_NAMED_STR_PTR()\fR; that is,
297 \fBstrlen(KSTAT_NAMED_STR_PTR()) + 1\fR.
298 .SS "Interrupt kstat"
299 .sp
300 .ne 2
301 .na
302 \fB\fBKSTAT_TYPE_INTR\fR\fR
303 .ad
304 .RS 19n
305 Interrupt statistics.
306 .RE
308 .sp
309 .LP
310 An interrupt is a hard interrupt (sourced from the hardware device itself), a
311 soft interrupt (induced by the system via the use of some system interrupt
312 source), a watchdog interrupt (induced by a periodic timer call), spurious (an
313 interrupt entry point was entered but there was no interrupt to service), or
314 multiple service (an interrupt was detected and serviced just prior to
315 returning from any of the other types).
316 .sp
317 .in +2
318 .nf
319 #define KSTAT_INTR_HARD 0
320 #define KSTAT_INTR_SOFT 1
321 #define KSTAT_INTR_WATCHDOG 2
322 #define KSTAT_INTR_SPURIOUS 3
323 #define KSTAT_INTR_MULTSVC 4
324 #define KSTAT_NUM_INTRS 5
326 typedef struct kstat_intr {
327 uint_t intrs[KSTAT_NUM_INTRS]; /* interrupt counters */
328 } kstat_intr_t;
329 .fi
330 .in -2
332 .SS "Event timer kstat"
333 .sp
334 .ne 2
335 .na
336 \fB\fBKSTAT_TYPE_TIMER\fR\fR
337 .ad
338 .RS 20n
339 Event timer statistics.
340 .RE
342 .sp
343 .LP
344 These provide basic counting and timing information for any type of event.
345 .sp
346 .in +2
347 .nf
348 typedef struct kstat_timer {
349 char name[KSTAT_STRLEN]; /* event name */
350 uchar_t resv; /* reserved */
351 u_longlong_t num_events; /* number of events */
352 hrtime_t elapsed_time; /* cumulative elapsed time */
353 hrtime_t min_time; /* shortest event duration */
354 hrtime_t max_time; /* longest event duration */
355 hrtime_t start_time; /* previous event start time */
356 hrtime_t stop_time; /* previous event stop time */
357 } kstat_timer_t;
358 .fi
359 .in -2
361 .SS "I/O kstat"
362 .sp
363 .ne 2
364 .na
365 \fB\fBKSTAT_TYPE_IO\fR\fR
366 .ad
367 .RS 17n
368 I/O statistics.
369 .RE
371 .sp
372 .in +2
373 .nf
374 typedef struct kstat_io {
375 /*
376 * Basic counters.
377 */
378 u_longlong_t nread; /* number of bytes read */
379 u_longlong_t nwritten; /* number of bytes written */
380 uint_t reads; /* number of read operations */
381 uint_t writes; /* number of write operations */
382 /*
383 * Accumulated time and queue length statistics.
384 *
385 * Time statistics are kept as a running sum of "active" time.
386 * Queue length statistics are kept as a running sum of the
387 * product of queue length and elapsed time at that length --
388 * that is, a Riemann sum for queue length integrated against time.
389 *
390 * ^
391 * | _________
392 * 8 | i4 |
393 * | | |
394 * Queue 6 | |
395 * Length | _________ | |
396 * 4 | i2 |_______| |
397 * | | i3 |
398 * 2_______| |
399 * | i1 |
400 * |_______________________________|
401 * Time-> t1 t2 t3 t4
402 *
403 * At each change of state (entry or exit from the queue),
404 * we add the elapsed time (since the previous state change)
405 * to the active time if the queue length was non-zero during
406 * that interval; and we add the product of the elapsed time
407 * times the queue length to the running length*time sum.
408 *
409 * This method is generalizable to measuring residency
410 * in any defined system: instead of queue lengths, think
411 * of "outstanding RPC calls to server X".
412 *
413 * A large number of I/O subsystems have at least two basic
414 * "lists" of transactions they manage: one for transactions
415 * that have been accepted for processing but for which processing
416 * has yet to begin, and one for transactions which are actively
417 * being processed (but not done). For this reason, two cumulative
418 * time statistics are defined here: pre-service (wait) time,
419 * and service (run) time.
420 *
421 * The units of cumulative busy time are accumulated nanoseconds.
422 * The units of cumulative length*time products are elapsed time
423 * times queue length.
424 */
425 hrtime_t wtime; /* cumulative wait (pre-service) time */
426 hrtime_t wlentime; /* cumulative wait length*time product*/
427 hrtime_t wlastupdate; /* last time wait queue changed */
428 hrtime_t rtime; /* cumulative run (service) time */
429 hrtime_t rlentime; /* cumulative run length*time product */
430 hrtime_t rlastupdate; /* last time run queue changed */
431 uint_t wcnt; /* count of elements in wait state */
432 uint_t rcnt; /* count of elements in run state */
433 } kstat_io_t;
434 .fi
435 .in -2
436 .sp
438 .SS "Using libkstat"
439 .sp
440 .LP
441 The kstat library, \fBlibkstat\fR, defines the user interface (API) to the
442 system's kstat facility.
443 .sp
444 .LP
445 You begin by opening libkstat with \fBkstat_open\fR(3KSTAT), which returns a
446 pointer to a fully initialized kstat control structure. This is your ticket to
447 subsequent libkstat operations:
448 .sp
449 .in +2
450 .nf
451 typedef struct kstat_ctl {
452 kid_t kc_chain_id; /* current kstat chain ID */
453 kstat_t *kc_chain; /* pointer to kstat chain */
454 int kc_kd; /* /dev/kstat descriptor */
455 } kstat_ctl_t;
456 .fi
457 .in -2
459 .sp
460 .LP
461 Only the first two fields, \fBkc_chain_id\fR and \fBkc_chain\fR, are of
462 interest to \fBlibkstat\fR clients. (\fIkc_kd\fR is the descriptor for
463 \fB/dev/kstat\fR, the kernel statistics driver. libkstat functions are built on
464 top of \fB/dev/kstat\fR \fBioctl\fR(2) primitives. Direct interaction with
465 \fB/dev/kstat\fR is strongly discouraged, since it is \fInot\fR a public
466 interface.)
467 .sp
468 .LP
469 \fBkc_chain\fR points to your copy of the kstat chain. You typically walk the
470 chain to find and process a certain kind of kstat. For example, to display all
471 \fBI/O\fR kstats:
472 .sp
473 .in +2
474 .nf
475 kstat_ctl_t *kc;
476 kstat_t *ksp;
477 kstat_io_t kio;
479 kc = kstat_open();
480 for (ksp = kc->kc_chain; ksp != NULL; ksp = ksp->ks_next) {
481 if (ksp->ks_type == KSTAT_TYPE_IO) {
482 kstat_read(kc, ksp, &kio);
483 my_io_display(kio);
484 }
485 }
486 .fi
487 .in -2
489 .sp
490 .LP
491 \fBkc_chain_id\fR is the kstat chain \fBID\fR, or \fBKCID\fR, of your copy of
492 the kstat chain. See \fBkstat_chain_update\fR(3KSTAT) for an explanation of
493 \fBKCID\fRs.
494 .SH FILES
495 .sp
496 .ne 2
497 .na
498 \fB\fB/dev/kstat\fR\fR
499 .ad
500 .RS 28n
501 kernel statistics driver
502 .RE
504 .sp
505 .ne 2
506 .na
507 \fB\fB/usr/include/kstat.h\fR\fR
508 .ad
509 .RS 28n
510 header
511 .RE
513 .sp
514 .ne 2
515 .na
516 \fB\fB/usr/include/sys/kstat.h\fR\fR
517 .ad
518 .RS 28n
519 header
520 .RE
522 .SH SEE ALSO
523 .sp
524 .LP
525 \fBioctl\fR(2), \fBgethrtime\fR(3C), \fBgetloadavg\fR(3C),
526 \fBkstat_chain_update\fR(3KSTAT), \fBkstat_close\fR(3KSTAT),
527 \fBkstat_data_lookup\fR(3KSTAT), \fBkstat_lookup\fR(3KSTAT),
528 \fBkstat_open\fR(3KSTAT), \fBkstat_read\fR(3KSTAT), \fBkstat_write\fR(3KSTAT),
529 \fBattributes\fR(5)