File Formats tnfkernelprobes(4)
NAME
tnfkernelprobes - TNF kernel probes
DESCRIPTION
The set of probes (trace instrumentation points) available
in the standard kernel. The probes log trace data to a ker-
nel trace buffer in Trace Normal Form (TNF). Kernel probes
are controlled by prex(1). A snapshot of the kernel trace
buffer can be made using tnfxtract(1) and examined using
tnfdump(1).
Each probe has a name and is associated with a set of sym-
bolic keys, or categories. These are used to select and con-
trol probes from prex(1). A probe that is enabled for trac-
ing generates a TNF record, called an event record. An
event record contains two common members and may contain
other probe-specific data members.
Common Members
tnfprobeevent tag
tnftimedelta timedelta
tag Encodes TNF references to two other records:
tag Describes the layout of the event
record.
schedule Identifies the writing thread and
also contains a 64-bit base time
in nanoseconds.
timedelta A 32-bit time offset from the base time; the
sum of the two times is the actual time of the
event.
Threads
threadcreate
tnfkthreadid tid
tnfpid pid
tnfsymbol startpc
Thread creation event.
SunOS 5.11 Last change: 8 Nov1999 1
File Formats tnfkernelprobes(4)
tid The thread identifier for the new thread.
pid The process identifier for the new thread.
startpc The kernel address of its start routine.
threadstate
tnfkthreadid tid
tnfmicrostate state
Thread microstate transition events.
tid Optional; if it is absent, the event is for the
writing thread, otherwise the event is for the
specified thread.
state Indicates the thread state:
o Running in user mode.
o Running in system mode.
o Asleep waiting for a user-mode lock.
o Asleep on a kernel object.
o Runnable (waiting for a cpu).
o Stopped.
The values of this member are defined in
. Note that to reduce trace output,
transitions between the system and user microstates
that are induced by system calls are not traced.
This information is implicit in the system call
entry and exit events.
threadexit
Thread termination event for writing thread. This probe has
no data members other than the common members.
Scheduling
threadqueue
tnfkthreadid tid
tnfcpuid cpuid
tnflong priority
SunOS 5.11 Last change: 8 Nov1999 2
File Formats tnfkernelprobes(4)
tnfulong queuelength
Thread scheduling events. These are triggered when a runn-
able thread is placed on a dispatch queue.
cpuid Specifies the cpu to which the queue is
attached.
priority The (global) dispatch priority of the
thread.
queuelength The current length of the cpu's dispatch
queue.
Blocking
threadblock
tnfopaque reason
tnfsymbols stack
Thread blockage event. This probe captures a partial stack
backtrace when the current thread blocks.
reason The address of the object on which the thread is
blocking.
symbols References a TNF array of kernel addresses
representing the PCs on the stack at the time the
thread blocks.
System Calls
syscallstart
tnfsysnum sysnum
System call entry event.
sysnum The system call number. The writing thread impli-
citly enters the system microstate with this
event.
SunOS 5.11 Last change: 8 Nov1999 3
File Formats tnfkernelprobes(4)
syscallend
tnflong rval1
tnflong rval2
tnflong errno
System call exit event.
rval1 and rval2 The two return values of the system call
errno The error return.
The writing thread implicitly enters the user microstate
with this event.
Page Faults
addressfault
tnfopaque address
tnffaulttype faulttype
tnfsegaccess access
Address-space fault event.
address Gives the faulting virtual address.
faulttype Gives the fault type: invalid page, protection
fault, software requested locking or unlock-
ing.
access Gives the desired access protection: read,
write, execute or create. The values for these
two members are defined in .
majorfault
tnfopaque vnode
tnfoffset offset
Major page fault event. The faulting page is mapped to the
file given by the vnode member, at the given offset into the
file. (The faulting virtual address is in the most recent
addressfault event for the writing thread.)
SunOS 5.11 Last change: 8 Nov1999 4
File Formats tnfkernelprobes(4)
anonprivate
tnfopaque address
Copy-on-write page fault event.
address The virtual address at which the new page is
mapped.
anonzero
tnfopaque address
Zero-fill page fault event.
address The virtual address at which the new page is
mapped.
pageunmap
tnfopaque vnode
tnfoffset offset
Page unmapping event. This probe marks the unmapping of a
file system page from the system.
vnode and offset Identifies the file and offset of the
page being unmapped.
Pageins and Pageouts
pagein
tnfopaque vnode
tnfoffset offset
tnfsize size
Pagein start event. This event signals the initiation of
pagein I/O.
vnodeandoffset Identifyies the file and offset to be
paged in.
size Specifies the number of bytes to be paged
in.
SunOS 5.11 Last change: 8 Nov1999 5
File Formats tnfkernelprobes(4)
pageout
tnfopaque vnode
tnfulong pagespageout
tnfulong pagesfreed
tnfulong pagesreclaimed
Pageout completion event. This event signals the completion
of pageout I/O.
vnode Identifies the file of the pageout
request.
pagespageout The number of pages written out.
pagesfreed The number of pages freed after being
written out.
pagesreclaimed The number of pages reclaimed after being
written out.
Page Daemon (Page Stealer)
pageoutscanstart
tnfulong pagesfree
tnfulong pagesneeded
Page daemon scan start event. This event signals the begin-
ning of one iteration of the page daemon.
pagesfree The number of free pages in the system.
pagesneeded The number of pages desired free.
pageoutscanend
tnfulong pagesfree
tnfulong pagesscanned
Page daemon scan end event. This event signals the end of
one iteration of the page daemon.
SunOS 5.11 Last change: 8 Nov1999 6
File Formats tnfkernelprobes(4)
pagesfree The number of free pages in the system.
pagesscanned The number of pages examined by the page
daemon. (Potentially more pages will be
freed when any queued pageout requests com-
plete.)
Swapper
swapoutprocess
tnfpid pid
tnfulong pagecount
Address space swapout event. This event marks the swapping
out of a process address space.
pid Identifies the process.
pagecount Reports the number of pages either freed or
queued for pageout.
swapoutlwp
tnfpid pid
tnflwpid lwpid
tnfkthreadid tid
tnfulong pagecount
Light-weight process swapout event. This event marks the
swapping out of an LWP and its stack.
pid The LWP's process identifier
lwpid The LWP identifier
tid member The LWP's kernel thread identifier.
pagecount The number of pages swapped out.
swapinlwp
tnfpid pid
tnflwpid lwpid
SunOS 5.11 Last change: 8 Nov1999 7
File Formats tnfkernelprobes(4)
tnfkthreadid tid
tnfulong pagecount
Light-weight process swapin event. This event marks the
swapping in of an LWP and its stack.
pid The LWP's process identifier.
lwpid The LWP identifier.
tid The LWP's kernel thread identifier.
pagecount The number of pages swapped in.
Local I/O
strategy
tnfdevice device
tnfdiskaddr block
tnfsize size
tnfopaque buf
tnfbioflags flags
Block I/O strategy event. This event marks a call to the
strategy(9E) function of a block device driver.
device Contains the major and minor numbers of the dev-
ice.
block The logical block number to be accessed on the
device.
size The size of the I/O request.
buf The kernel address of the buf(9S) structure asso-
ciated with the transfer.
flags The buf(9S) flags associated with the transfer.
SunOS 5.11 Last change: 8 Nov1999 8
File Formats tnfkernelprobes(4)
biodone
tnfdevice device
tnfdiskaddr block
tnfopaque buf
Buffered I/O completion event. This event marks calls to
the biodone(9F) function.
device Contains the major and minor numbers of the dev-
ice.
block The logical block number accessed on the device.
buf The kernel address of the buf(9S) structure asso-
ciated with the transfer.
physiostart
tnfdevice device
tnfoffset offset
tnfsize size
tnfbioflags rw
Raw I/O start event. This event marks entry into the
physio(9F) fufnction which performs unbuffered I/O.
device Contains the major and minor numbers of the device
of the transfer.
offset The logical offset on the device for the transfer.
size The number of bytes to be transferred.
rw The direction of the transfer: read or write (see
buf(9S)).
physioend
tnfdevice device
SunOS 5.11 Last change: 8 Nov1999 9
File Formats tnfkernelprobes(4)
Raw I/O end event. This event marks exit from the
physio(9F) fufnction.
device The major and minor numbers of the device of the
transfer.
USAGE
Use the prex utility to control kernel probes. The standard
prex commands to list and manipulate probes are available to
you, along with commands to set up and manage kernel trac-
ing.
Kernel probes write trace records into a kernel trace
buffer. You must copy the buffer into a TNF file for post-
processing; use the tnfxtract utility for this.
You use the tnfdump utility to examine a kernel trace file.
This is exactly the same as examining a user-level trace
file.
The steps you typically follow to take a kernel trace are:
1. Become superuser (su).
2. Allocate a kernel trace buffer of the desired size
(prex).
3. Select the probes you want to trace and enable
(prex).
4. Turn kernel tracing on (prex).
5. Run your application.
6. Turn kernel tracing off (prex).
7. Extract the kernel trace buffer (tnfxtract).
8. Disable all probes (prex).
9. Deallocate the kernel trace buffer (prex).
10. Examine the trace file (tnfdump).
A convenient way to follow these steps is to use two shell
windows; run an interactive prex session in one, and run
your application and tnfxtract in the other.
SunOS 5.11 Last change: 8 Nov1999 10
File Formats tnfkernelprobes(4)
SEE ALSO
prex(1), tnfdump(1), tnfxtract(1), libtnfctl(3TNF),
TNFPROBE(3TNF), tracing(3TNF), strategy(9E), biodone(9F),
physio(9F), buf(9S)
SunOS 5.11 Last change: 8 Nov1999 11
|
