1 TNF_KERNEL_PROBES(4) File Formats and Configurations TNF_KERNEL_PROBES(4) 2 3 4 5 NAME 6 tnf_kernel_probes - TNF kernel probes 7 8 DESCRIPTION 9 The set of probes (trace instrumentation points) available in the 10 standard kernel. The probes log trace data to a kernel trace buffer in 11 Trace Normal Form (TNF). Kernel probes are controlled by prex(1). A 12 snapshot of the kernel trace buffer can be made using tnfxtract(1) and 13 examined using tnfdump(1). 14 15 16 Each probe has a name and is associated with a set of symbolic keys, or 17 categories. These are used to select and control probes from prex(1). A 18 probe that is enabled for tracing generates a TNF record, called an 19 event record. An event record contains two common members and may 20 contain other probe-specific data members. 21 22 Common Members 23 tnf_probe_event tag 24 tnf_time_delta time_delta 25 26 27 tag 28 Encodes TNF references to two other records: 29 30 tag 31 Describes the layout of the event record. 32 33 34 schedule 35 Identifies the writing thread and also 36 contains a 64-bit base time in nanoseconds. 37 38 39 40 time_delta 41 A 32-bit time offset from the base time; the sum of the 42 two times is the actual time of the event. 43 44 45 Threads 46 thread_create 47 tnf_kthread_id tid 48 tnf_pid pid 49 tnf_symbol start_pc 50 51 52 53 Thread creation event. 54 55 tid 56 The thread identifier for the new thread. 57 58 59 pid 60 The process identifier for the new thread. 61 62 63 start_pc 64 The kernel address of its start routine. 65 66 67 thread_state 68 tnf_kthread_id tid 69 tnf_microstate state 70 71 72 73 Thread microstate transition events. 74 75 tid 76 Optional; if it is absent, the event is for the writing 77 thread, otherwise the event is for the specified thread. 78 79 80 state 81 Indicates the thread state: 82 83 o Running in user mode. 84 85 o Running in system mode. 86 87 o Asleep waiting for a user-mode lock. 88 89 o Asleep on a kernel object. 90 91 o Runnable (waiting for a cpu). 92 93 o Stopped. 94 The values of this member are defined in <sys/msacct.h>. Note 95 that to reduce trace output, transitions between the system 96 and user microstates that are induced by system calls are not 97 traced. This information is implicit in the system call 98 entry and exit events. 99 100 101 thread_exit 102 Thread termination event for writing thread. This probe has no data 103 members other than the common members. 104 105 Scheduling 106 107 thread_queue 108 tnf_kthread_id tid 109 tnf_cpuid cpuid 110 tnf_long priority 111 tnf_ulong queue_length 112 113 114 115 Thread scheduling events. These are triggered when a runnable thread 116 is placed on a dispatch queue. 117 118 cpuid 119 Specifies the cpu to which the queue is attached. 120 121 122 priority 123 The (global) dispatch priority of the thread. 124 125 126 queue_length 127 The current length of the cpu's dispatch queue. 128 129 130 Blocking 131 thread_block 132 tnf_opaque reason 133 tnf_symbols stack 134 135 136 137 Thread blockage event. This probe captures a partial stack backtrace 138 when the current thread blocks. 139 140 reason 141 The address of the object on which the thread is blocking. 142 143 144 symbols 145 References a TNF array of kernel addresses representing the 146 PCs on the stack at the time the thread blocks. 147 148 149 System Calls 150 syscall_start 151 tnf_sysnum sysnum 152 153 154 155 System call entry event. 156 157 sysnum 158 The system call number. The writing thread implicitly enters 159 the system microstate with this event. 160 161 162 syscall_end 163 tnf_long rval1 164 tnf_long rval2 165 tnf_long errno 166 167 168 169 System call exit event. 170 171 rval1 and rval2 172 The two return values of the system call 173 174 175 errno 176 The error return. 177 178 179 180 The writing thread implicitly enters the user microstate with this 181 event. 182 183 Page Faults 184 address_fault 185 tnf_opaque address 186 tnf_fault_type fault_type 187 tnf_seg_access access 188 189 190 191 Address-space fault event. 192 193 address 194 Gives the faulting virtual address. 195 196 197 fault_type 198 Gives the fault type: invalid page, protection fault, 199 software requested locking or unlocking. 200 201 202 access 203 Gives the desired access protection: read, write, execute 204 or create. The values for these two members are defined 205 in <vm/seg_enum.h>. 206 207 208 major_fault 209 tnf_opaque vnode 210 tnf_offset offset 211 212 213 214 Major page fault event. The faulting page is mapped to the file given 215 by the vnode member, at the given offset into the file. (The faulting 216 virtual address is in the most recent address_fault event for the 217 writing thread.) 218 219 anon_private 220 tnf_opaque address 221 222 223 224 Copy-on-write page fault event. 225 226 address 227 The virtual address at which the new page is mapped. 228 229 230 anon_zero 231 tnf_opaque address 232 233 234 235 Zero-fill page fault event. 236 237 address 238 The virtual address at which the new page is mapped. 239 240 241 page_unmap 242 tnf_opaque vnode 243 tnf_offset offset 244 245 246 247 Page unmapping event. This probe marks the unmapping of a file system 248 page from the system. 249 250 vnode and offset 251 Identifies the file and offset of the page being 252 unmapped. 253 254 255 Pageins and Pageouts 256 pagein 257 tnf_opaque vnode 258 tnf_offset offset 259 tnf_size size 260 261 262 263 Pagein start event. This event signals the initiation of pagein I/O. 264 265 vnodeandoffset 266 Identifies the file and offset to be paged in. 267 268 269 size 270 Specifies the number of bytes to be paged in. 271 272 273 pageout 274 tnf_opaque vnode 275 tnf_ulong pages_pageout 276 tnf_ulong pages_freed 277 tnf_ulong pages_reclaimed 278 279 280 281 Pageout completion event. This event signals the completion of pageout 282 I/O. 283 284 vnode 285 Identifies the file of the pageout request. 286 287 288 pages_pageout 289 The number of pages written out. 290 291 292 pages_freed 293 The number of pages freed after being written out. 294 295 296 pages_reclaimed 297 The number of pages reclaimed after being written 298 out. 299 300 301 Page Daemon (Page Stealer) 302 pageout_scan_start 303 tnf_ulong pages_free 304 tnf_ulong pages_needed 305 306 307 308 Page daemon scan start event. This event signals the beginning of one 309 iteration of the page daemon. 310 311 pages_free 312 The number of free pages in the system. 313 314 315 pages_needed 316 The number of pages desired free. 317 318 319 pageout_scan_end 320 tnf_ulong pages_free 321 tnf_ulong pages_scanned 322 323 324 325 Page daemon scan end event. This event signals the end of one 326 iteration of the page daemon. 327 328 pages_free 329 The number of free pages in the system. 330 331 332 pages_scanned 333 The number of pages examined by the page daemon. 334 (Potentially more pages will be freed when any queued 335 pageout requests complete.) 336 337 338 Swapper 339 swapout_process 340 tnf_pid pid 341 tnf_ulong page_count 342 343 344 345 Address space swapout event. This event marks the swapping out of a 346 process address space. 347 348 pid 349 Identifies the process. 350 351 352 page_count 353 Reports the number of pages either freed or queued for 354 pageout. 355 356 357 swapout_lwp 358 tnf_pid pid 359 tnf_lwpid lwpid 360 tnf_kthread_id tid 361 tnf_ulong page_count 362 363 364 365 Light-weight process swapout event. This event marks the swapping out 366 of an LWP and its stack. 367 368 pid 369 The LWP's process identifier 370 371 372 lwpid 373 The LWP identifier 374 375 376 tid member 377 The LWP's kernel thread identifier. 378 379 380 page_count 381 The number of pages swapped out. 382 383 384 swapin_lwp 385 tnf_pid pid 386 tnf_lwpid lwpid 387 tnf_kthread_id tid 388 tnf_ulong page_count 389 390 391 392 Light-weight process swapin event. This event marks the swapping in of 393 an LWP and its stack. 394 395 pid 396 The LWP's process identifier. 397 398 399 lwpid 400 The LWP identifier. 401 402 403 tid 404 The LWP's kernel thread identifier. 405 406 407 page_count 408 The number of pages swapped in. 409 410 411 Local I/O 412 strategy 413 tnf_device device 414 tnf_diskaddr block 415 tnf_size size 416 tnf_opaque buf 417 tnf_bioflags flags 418 419 420 421 Block I/O strategy event. This event marks a call to the strategy(9E) 422 function of a block device driver. 423 424 device 425 Contains the major and minor numbers of the device. 426 427 428 block 429 The logical block number to be accessed on the device. 430 431 432 size 433 The size of the I/O request. 434 435 436 buf 437 The kernel address of the buf(9S) structure associated with 438 the transfer. 439 440 441 flags 442 The buf(9S) flags associated with the transfer. 443 444 445 biodone 446 tnf_device device 447 tnf_diskaddr block 448 tnf_opaque buf 449 450 451 452 Buffered I/O completion event. This event marks calls to the 453 biodone(9F) function. 454 455 device 456 Contains the major and minor numbers of the device. 457 458 459 block 460 The logical block number accessed on the device. 461 462 463 buf 464 The kernel address of the buf(9S) structure associated with 465 the transfer. 466 467 468 physio_start 469 tnf_device device 470 tnf_offset offset 471 tnf_size size 472 tnf_bioflags rw 473 474 475 476 Raw I/O start event. This event marks entry into the physio(9F) 477 function which performs unbuffered I/O. 478 479 device 480 Contains the major and minor numbers of the device of the 481 transfer. 482 483 484 offset 485 The logical offset on the device for the transfer. 486 487 488 size 489 The number of bytes to be transferred. 490 491 492 rw 493 The direction of the transfer: read or write (see buf(9S)). 494 495 496 physio_end 497 tnf_device device 498 499 500 501 Raw I/O end event. This event marks exit from the physio(9F) function. 502 503 device 504 The major and minor numbers of the device of the transfer. 505 506 507 USAGE 508 Use the prex utility to control kernel probes. The standard prex 509 commands to list and manipulate probes are available to you, along with 510 commands to set up and manage kernel tracing. 511 512 513 Kernel probes write trace records into a kernel trace buffer. You must 514 copy the buffer into a TNF file for post-processing; use the tnfxtract 515 utility for this. 516 517 518 You use the tnfdump utility to examine a kernel trace file. This is 519 exactly the same as examining a user-level trace file. 520 521 522 The steps you typically follow to take a kernel trace are: 523 524 1. Become superuser (su). 525 526 2. Allocate a kernel trace buffer of the desired size (prex). 527 528 3. Select the probes you want to trace and enable (prex). 529 530 4. Turn kernel tracing on (prex). 531 532 5. Run your application. 533 534 6. Turn kernel tracing off (prex). 535 536 7. Extract the kernel trace buffer (tnfxtract). 537 538 8. Disable all probes (prex). 539 540 9. Deallocate the kernel trace buffer (prex). 541 542 10. Examine the trace file (tnfdump). 543 544 545 A convenient way to follow these steps is to use two shell windows; run 546 an interactive prex session in one, and run your application and 547 tnfxtract in the other. 548 549 SEE ALSO 550 prex(1), tnfdump(1), tnfxtract(1), libtnfctl(3TNF), TNF_PROBE(3TNF), 551 tracing(3TNF), strategy(9E), biodone(9F), physio(9F), buf(9S) 552 553 554 555 May 16, 2020 TNF_KERNEL_PROBES(4)