1kstat(3KSTAT) Kernel Statistics Library Functions kstat(3KSTAT)
2
3
4
6 kstat - kernel statistics facility
7
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
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
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)