Section 10.6. Probe Reference

10.6. Probe Reference

10.6.1. The I/O Provider

The io probes are listed in Table 10.2, and the arguments are described in Sections 10.6.1.1 through 10.6.1.3.

Table 10.2. io Probes

Probe	Description
start	Probe that fires when an I/O request is about to be made either to a peripheral device or to an NFS server. The bufinfo_t corresponding to the I/O request is pointed to by args[0]. The devinfo_t of the device to which the I/O is being issued is pointed to by args[1]. The fileinfo_t of the file that corresponds to the I/O request is pointed to by args[2]. Note that file information availability depends on the filesystem making the I/O request. See fileinfo_t for more information.
done	Probe that fires after an I/O request has been fulfilled. The bufinfo_t corresponding to the I/O request is pointed to by args[0]. The done probe fires after the I/O completes, but before completion processing has been performed on the buffer. As a result B_DONE is not set in b_flags at the time the done probe fires. The devinfo_t of the device to which the I/O was issued is pointed to by args[1]. The fileinfo_t of the file that corresponds to the I/O request is pointed to by args[2].
wait-start	Probe that fires immediately before a thread begins to wait pending completion of a given I/O request. The buf(9S) structure corresponding to the I/O request for which the thread will wait is pointed to by args[0]. The devinfo_t of the device to which the I/O was issued is pointed to by args[1]. The fileinfo_t of the file that corresponds to the I/O request is pointed to by args[2]. Some time after the wait-start probe fires, the wait-done probe will fire in the same thread.
wait-done	Probe that fires when a thread is done waiting for the completion of a given I/O request. The bufinfo_t corresponding to the I/O request for which the thread will wait is pointed to by args[0]. The devinfo_t of the device to which the I/O was issued is pointed to by args[1]. The fileinfo_t of the file that corresponds to the I/O request is pointed to by args[2]. The wait-done probe fires only after the wait-start probe has fired in the same thread.

10.6.1.1. bufinfo_t structure

The bufinfo_t structure is the abstraction that describes an I/O request. The buffer corresponding to an I/O request is pointed to by args[0] in the start, done, wait-start, and wait-done probes. The bufinfo_t structure definition is as follows:

typedef struct bufinfo {               int b_flags;                    /* flags */               size_t b_bcount;                /* number of bytes */               caddr_t b_addr;                 /* buffer address */               uint64_t b_blkno;               /* expanded block # on device */               uint64_t b_lblkno;              /* block # on device */               size_t b_resid;                 /* # of bytes not transferred */               size_t b_bufsize;               /* size of allocated buffer */               caddr_t b_iodone;               /* I/O completion routine */               dev_t b_edev;                   /* extended device */ } bufinfo_t;                                                                See /usr/lib/dtrace/io.d 

The b_flags member indicates the state of the I/O buffer, and consists of a bitwise-or of different state values. The valid state values are in Table 10.3.

Table 10.3. b_flags Values

Flag	Description
B_DONE	Indicates that the data transfer has completed.
B_ERROR	Indicates an I/O transfer error. It is set in conjunction with the b_error field.
B_PAGEIO	Indicates that the buffer is being used in a paged I/O request. See the description of the b_addr field for more information.
B_PHYS	Indicates that the buffer is being used for physical (direct) I/O to a user data area.
B_READ	Indicates that data is to be read from the peripheral device into main memory.
B_WRITE	Indicates that the data is to be transferred from main memory to the peripheral device.
B_ASYNC	The I/O request is asynchronous, and will not be waited upon. The wait-start and wait-done probes don't fire for asynchronous I/O requests. Note that some I/Os directed to be asynchronous might not have B_ASYNC set: the asynchronous I/O subsystem might implement the asynchronous request by having a separate worker thread perform a synchronous I/O operation.

The structure members are as follows:

• b_bcount is the number of bytes to be transferred as part of the I/O request.

• b_addr is the virtual address of the I/O request, unless B_PAGEIO is set. The address is a kernel virtual address unless B_PHYS is set, in which case it is a user virtual address. If B_PAGEIO is set, the b_addr field contains kernel private data. Exactly one of B_PHYS and B_PAGEIO can be set, or neither flag will be set.

• b_lblkno identifies which logical block on the device is to be accessed. The mapping from a logical block to a physical block (such as the cylinder, track, and so on) is defined by the device.

• b_resid is set to the number of bytes not transferred because of an error.

• b_bufsize contains the size of the allocated buffer.

• b_iodoneidentifies a specific routine in the kernel that is called when the I/O is complete.

• b_error may hold an error code returned from the driver in the event of an I/O error. b_error is set in conjunction with the B_ERROR bit set in the b_flags member.

• b_edev contains the major and minor device numbers of the device accessed. Consumers may use the D subroutines getmajor() and getminor() to extract the major and minor device numbers from the b_edev field.

10.6.1.2. devinfo_t

The devinfo_t structure provides information about a device. The devinfo_t structure corresponding to the destination device of an I/O is pointed to by args[1] in the start, done, wait-start, and wait-done probes. The members of devinfo_t are as follows:

typedef struct devinfo {               int dev_major;                  /* major number */               int dev_minor;                  /* minor number */               int dev_instance;               /* instance number */               string dev_name;                /* name of device */               string dev_statname;            /* name of device + instance/minor */               string dev_pathname;            /* pathname of device */ } devinfo_t;                                                                See /usr/lib/dtrace/io.d 

• dev_major. The major number of the device. See getmajor(9F) for more information.

• dev_minor. The minor number of the device. See getminor(9F) for more information.

• dev_instance. The instance number of the device. The instance of a device is different from the minor number. The minor number is an abstraction managed by the device driver. The instance number is a property of the device node. You can display device node instance numbers with prtconf(1M).

• dev_name. The name of the device driver that manages the device. You can display device driver names with the -D option to prtconf(1M).

• dev_statname. The name of the device as reported by iostat(1M). This name also corresponds to the name of a kernel statistic as reported by kstat(1M). This field is provided so that aberrant iostat or kstat output can be quickly correlated to actual I/O activity.

• dev_pathname. The full path of the device. This path may be specified as an argument to prtconf(1M) to obtain detailed device information. The path specified by dev_pathname includes components expressing the device node, the instance number, and the minor node. However, all three of these elements aren't necessarily expressed in the statistics name. For some devices, the statistics name consists of the device name and the instance number. For other devices, the name consists of the device name and the number of the minor node. As a result, two devices that have the same dev_statname may differ in dev_pathname.

10.6.1.3. fileinfo_t

The fileinfo_t structure provides information about a file. The file to which an I/O corresponds is pointed to by args[2] in the start, done, wait-start, and wait-done probes. The presence of file information is contingent upon the filesystem providing this information when dispatching I/O requests. Some filesystems, especially third-party filesystems, might not provide this information. Also, I/O requests might emanate from a filesystem for which no file information exists. For example, any I/O to filesystem metadata will not be associated with any one file. Finally, some highly optimized filesystems might aggregate I/O from disjoint files into a single I/O request. In this case, the filesystem might provide the file information either for the file that represents the majority of the I/O or for the file that represents some of the I/O. Alternately, the filesystem might provide no file information at all in this case.

The definition of the fileinfo_t structure is as follows:

typedef struct fileinfo {               string fi_name;                 /* name (basename of fi_pathname) */               string fi_dirname;              /* directory (dirname of fi_pathname) */               string fi_pathname;             /* full pathname */               offset_t fi_offset;             /* offset within file */               string fi_fs;                   /* filesystem */               string fi_mount;                /* mount point of file system */ } fileinfo_t;                                                                See /usr/lib/dtrace/io.d 

• fi_name. Contains the name of the file but does not include any directory components. If no file information is associated with an I/O, the fi_name field will be set to the string <none>. In some rare cases, the pathname associated with a file might be unknown. In this case, the fi_name field will be set to the string <unknown>.

• fi_dirname. Contains only the directory component of the file name. As with fi_name, this string may be set to <none> if no file information is present, or <unknown> if the pathname associated with the file is not known.

• fi_pathname. Contains the full pathname to the file. As with fi_name, this string may be set to <none> if no file information is present, or <unknown> if the pathname associated with the file is not known.

• fi_offset. Contains the offset within the file, or -1 if either file information is not present or if the offset is otherwise unspecified by the filesystem.

10.6.2. Virtual Memory Provider Probes

The vminfo provider probes correspond to the fields in the "vm" named kstat: A probe provided by vminfo fires immediately before the corresponding vm value is incremented. Table 10.4 lists the probes available from the VM provider. A probe takes the following arguments:

• arg0. The value by which the statistic is to be incremented. For most probes, this argument is always 1, but for some it may take other values; these probes are noted in Table 10.4.

• arg1. A pointer to the current value of the statistic to be incremented. This value is a 64bit quantity that is incremented by the value in arg0. Dereferencing this pointer allows consumers to determine the current count of the statistic corresponding to the probe.

For example, if you should see the following paging activity with vmstat, indicating page-in from the swap device, you could drill down to investigate.

# vmstat -p 3      memory           page          executable      anonymous      filesystem    swap  free  re  mf  fr  de  sr  epi  epo  epf  api  apo  apf  fpi  fpo  fpf  1512488 837792 160 20 12   0   0    0    0    0 8102    0    0   12   12   12  1715812 985116 7  82   0   0   0    0    0    0 7501    0    0   45    0    0  1715784 983984 0   2   0   0   0    0    0    0 1231    0    0   53    0    0  1715780 987644 0   0   0   0   0    0    0    0 2451    0    0   33    0    0 $ dtrace -n anonpgin'{@[execname] = count()}' dtrace: description 'anonpgin' matched 1 probe   svc.startd                                                       1   sshd                                                             2   ssh                                                              3   dtrace                                                           6   vmstat                                                          28   filebench                                                      913 

The VM probes are described in Table 10.4.

Table 10.4. DTrace VM Provider Probes and Descriptions

Probe Name	Description
anonfree	Fires whenever an unmodified anonymous page is freed as part of paging activity. Anonymous pages are those that are not associated with a file; memory containing such pages include heap memory, stack memory, or memory obtained by explicitly mapping zero(7D).
anonpgin	Fires whenever an anonymous page is paged in from a swap device.
anonpgout	Fires whenever a modified anonymous page is paged out to a swap device.
as_fault	Fires whenever a fault is taken on a page and the fault is neither a protection fault nor a copy-on-write fault.
cow_fault	Fires whenever a copy-on-write fault is taken on a page. arg0 contains the number of pages that are created as a result of the copy-on-write.
dfree	Fires whenever a page is freed as a result of paging activity. Whenever dfree fires, exactly one of anonfree, execfree, or fsfree will also subsequently fire.
execfree	Fires whenever an unmodified executable page is freed as a result of paging activity.
execpgin	Fires whenever an executable page is paged in from the backing store.
execpgout	Fires whenever a modified executable page is paged out to the backing store. If it occurs at all, most paging of executable pages will occur in terms of execfree; execpgout can only fire if an executable page is modified in memoryan uncommon occurrence in most systems.
fsfree	Fires whenever an unmodified file system data page is freed as part of paging activity.
fspgin	Fires whenever a file system page is paged in from the backing store.
fspgout	Fires whenever a modified file system page is paged out to the backing store.
kernel_asflt	Fires whenever a page fault is taken by the kernel on a page in its own address space. Whenever kernel_asflt fires, it will be immediately preceded by a firing of the as_fault probe.
maj_fault	Fires whenever a page fault is taken that results in I/O from a backing store or swap device. Whenever maj_fault fires, it will be immediately preceded by a firing of the pgin probe.
pgfrec	Fires whenever a page is reclaimed off of the free page list.

10.6.3. The Sched Provider

The sched probes are described in Table 10.5.

Table 10.5. sched Probes

Probe	Description
change-pri	Probe that fires whenever a thread's priority is about to be changed. The lwpsinfo_t of the thread is pointed to by args[0]. The thread's current priority is in the pr_pri field of this structure. The psinfo_t of the process containing the thread is pointed to by args[1]. The thread's new priority is contained in args[2].
dequeue	Probe that fires immediately before a runnable thread is dequeued from a run queue. The lwpsinfo_t of the thread being dequeued is pointed to by args[0]. The psinfo_t of the process containing the thread is pointed to by args[1]. The cpuinfo_t of the CPU from which the thread is being dequeued is pointed to by args[2]. If the thread is being dequeued from a run queue that is not associated with a particular CPU, the cpu_id member of this structure will be -1.
enqueue	Probe that fires immediately before a runnable thread is enqueued to a run queue. The lwpsinfo_t of the thread being enqueued is pointed to by args[0]. The psinfo_t of the process containing the thread is pointed to by args[1]. The cpuinfo_t of the CPU to which the thread is being enqueued is pointed to by args[2]. If the thread is being enqueued from a run queue that is not associated with a particular CPU, the cpu_id member of this structure will be -1. The value in args[3] is a boolean indicating whether the thread will be enqueued to the front of the run queue. The value is non-zero if the thread will be enqueued at the front of the run queue, and zero if the thread will be enqueued at the back of the run queue.
off-cpu	Probe that fires when the current CPU is about to end execution of a thread. The curcpu variable indicates the current CPU. The curlwpsinfo variable indicates the thread that is ending execution. The curpsinfo variable describes the process containing the current thread. The lwpsinfo_t structure of the thread that the current CPU will next execute is pointed to by args[0]. The psinfo_t of the process containing the next thread is pointed to by args[1].
on-cpu	Probe that fires when a CPU has just begun execution of a thread. The curcpu variable indicates the current CPU. The curlwpsinfo variable indicates the thread that is beginning execution. The curpsinfo variable describes the process containing the current thread.
preempt	Probe that fires immediately before the current thread is preempted. After this probe fires, the current thread will select a thread to run and the off-cpu probe will fire for the current thread. In some cases, a thread on one CPU will be preempted, but the preempting thread will run on another CPU in the meantime. In this situation, the preempt probe will fire, but the dispatcher will be unable to find a higher priority thread to run and the remain-cpu probe will fire instead of the off-cpu probe.
remain-cpu	Probe that fires when a scheduling decision has been made, but the dispatcher has elected to continue to run the current thread. The curcpu variable indicates the current CPU. The curlwpsinfo variable indicates the thread that is beginning execution. The curpsinfo variable describes the process containing the current thread.
schedctl-nopreempt	Probe that fires when a thread is preempted and then re-enqueued at the front of the run queue due to a preemption control request. See schedctl_init(3C) for details on preemption control. As with preempt, either off-cpu or remain-cpu will fire after schedctl-nopreempt. Because schedctl-nopreempt denotes a re-enqueuing of the current thread at the front of the run queue, remain-cpu is more likely to fire after schedctl-nopreempt than off-cpu. The lwpsinfo_t of the thread being preempted is pointed to by args[0]. The psinfo_t of the process containing the thread is pointed to by args[1].
schedctl-preempt	Probe that fires when a thread that is using preemption control is nonetheless preempted and re-enqueued at the back of the run queue. See schedctl_init(3C) for details on preemption control. As with preempt, either off-cpu or remain-cpu will fire after schedctl-preempt. Like preempt (and unlike schedctl-nopreempt), schedctl-preempt denotes a reenqueuing of the current thread at the back of the run queue. As a result, off-cpu is more likely to fire after schedctl-preempt than remain-cpu. The lwpsinfo_t of the thread being preempted is pointed to by args[0]. The psinfo_t of the process containing the thread is pointed to by args[1].
schedctl-yield	Probe that fires when a thread that had preemption control enabled and its time slice artificially extended executed code to yield the CPU to other threads.
sleep	Probe that fires immediately before the current thread sleeps on a synchronization object. The type of the synchronization object is contained in the pr_stype member of the lwpsinfo_t pointed to by curlwpsinfo. The address of the synchronization object is contained in the pr_wchan member of the lwpsinfo_t pointed to by curlwpsinfo. The meaning of this address is a private implementation detail, but the address value may be treated as a token unique to the synchronization object.
surrender	Probe that fires when a CPU has been instructed by another CPU to make a scheduling decisionoften because a higher-priority thread has become runnable.
tick	Probe that fires as a part of clock tick-based accounting. In clock tick-based accounting, CPU accounting is performed by examining which threads and processes are running when a fixed-interval interrupt fires. The lwpsinfo_t that corresponds to the thread that is being assigned CPU time is pointed to by args[0]. The psinfo_t that corresponds to the process that contains the thread is pointed to by args[1].
wakeup	Probe that fires immediately before the current thread wakes a thread sleeping on a synchronization object. The lwpsinfo_t of the sleeping thread is pointed to by args[0]. The psinfo_t of the process containing the sleeping thread is pointed to by args[1]. The type of the synchronization object is contained in the pr_stype member of the lwpsinfo_t of the sleeping thread. The address of the synchronization object is contained in the pr_wchan member of the lwpsinfo_t of the sleeping thread. The meaning of this address is a private implementation detail, but the address value may be treated as a token unique to the synchronization object.

10.6.3.1. Arguments

The argument types for the sched probes are listed in Table 10.5; the arguments are described in Table 10.6.

Table 10.6. sched Probe Arguments

Probe	args[0]	args[1]	args[2]	args[3]
change-pri	lwpsinfo_t *	psinfo_t *	pri_t
dequeue	lwpsinfo_t *	psinfo_t *	cpuinfo_t *
enqueue	lwpsinfo_t *	psinfo_t *	cpuinfo_t *	int
off-cpu	lwpsinfo_t *	psinfo_t *
on-cpu
preempt
remain-cpu
schedctl-nopreempt	lwpsinfo_t *	psinfo_t *
schedctl-preempt	lwpsinfo_t *	psinfo_t *
schedctl-yield	lwpsinfo_t *	psinfo_t *
sleep
surrender	lwpsinfo_t *	psinfo_t *
tick	lwpsinfo_t *	psinfo_t *
wakeup	lwpsinfo_t *	psinfo_t *

As Table 10.6 indicates, many sched probes have arguments consisting of a pointer to an lwpsinfo_t and a pointer to a psinfo_t, indicating a thread and the process containing the thread, respectively. These structures are described in detail in lwpsinfo_t and psinfo_t, respectively.

The cpuinfo_t structure defines a CPU. As Table 10.6 indicates, arguments to both the enqueue and dequeue probes include a pointer to a cpuinfo_t. Additionally, the cpuinfo_t corresponding to the current CPU is pointed to by the curcpu variable.

typedef struct cpuinfo {               processorid_t cpu_id;           /* CPU identifier */               psetid_t cpu_pset;              /* processor set identifier */               chipid_t cpu_chip;              /* chip identifier */               lgrp_id_t cpu_lgrp;             /* locality group identifer */               processor_info_t cpu_info;      /* CPU information */ } cpuinfo_t; 

The definition of the cpuinfo_t structure is as follows:

• cpu_id. The processor identifier, as returned by psrinfo(1M) and p_online(2).

• cpu_pset. The processor set that contains the CPU, if any. See psrset(1M) for more details on processor sets.

• cpu_chip. The identifier of the physical chip. Physical chips may contain several CPUs. See psrinfo(1M) for more information.

• The cpu_lgrp. The identifier of the latency group associated with the CPU. See liblgrp(3LIB) for details on latency groups.

• The cpu_info. The processor_info_t structure associated with the CPU, as returned by processor_info(2).

10.6.4. DTrace Lockstat Provider

The lockstat provider makes available probes that can be used to discern lock contention statistics or to understand virtually any aspect of locking behavior. The lockstat(1M) command is actually a DTrace consumer that uses the lockstat provider to gather its raw data.

The lockstat provider makes available two kinds of probes: content-event probes and hold-event probes.

• Contention-event probes. Correspond to contention on a synchronization primitive; they fire when a thread is forced to wait for a resource to become available. Solaris is generally optimized for the noncontention case, so prolonged contention is not expected. These probes should be used to understand those cases where contention does arise. Because contention is relatively rare, enabling contention-event probes generally doesn't substantially affect performance.

• Hold-event probes. Correspond to acquiring, releasing, or otherwise manipulating a synchronization primitive. These probes can be used to answer arbitrary questions about the way synchronization primitives are manipulated. Because Solaris acquires and releases synchronization primitives very often (on the order of millions of times per second per CPU on a busy system), enabling hold-event probes has a much higher probe effect than does enabling contention-event probes. While the probe effect induced by enabling them can be substantial, it is not pathological; they may still be enabled with confidence on production systems.

The lockstat provider makes available probes that correspond to the different synchronization primitives in Solaris; these primitives and the probes that correspond to them are discussed in the remainder of this chapter.

10.6.4.1. Adaptive Lock Probes

The four lockstat probes pertaining to adaptive locks are in Table 10.7. For each probe, arg0 contains a pointer to the kmutex_t structure that represents the adaptive lock.

Table 10.7. Adaptive Lock Probes

Probe Name	Description
adaptive-acquire	Hold-event probe that fires immediately after an adaptive lock is acquired.
adaptive-block	Contention-event probe that fires after a thread that has blocked on a held adaptive mutex has reawakened and has acquired the mutex. If both probes are enabled, adaptive-block fires before adaptive-acquire. At most one of adaptive-block and adaptive-spin fires for a single lock acquisition. arg1 for adaptive-block contains the sleep time in nanoseconds.
adaptive-spin	Contention-event probe that fires after a thread that has spun on a held adaptive mutex has successfully acquired the mutex. If both are enabled, adaptive-spin fires before adaptive-acquire. At most one of adaptive-spin and adaptive-block fires for a single lock acquisition. arg1 for adaptive-spin contains the spin count: the number of iterations that were taken through the spin loop before the lock was acquired. The spin count has little meaning on its own but can be used to compare spin times.
adaptive-release	Hold-event probe that fires immediately after an adaptive lock is released.

10.6.4.2. Spin Lock Probes

The three probes pertaining to spin locks are in Table 10.8.

Table 10.8. Spin Lock Probes

Probe Name	Description
spin-acquire	Hold-event probe that fires immediately after a spin lock is acquired.
spin-spin	Contention-event probe that fires after a thread that has spun on a held spin lock has successfully acquired the spin lock. If both are enabled, spin-spin fires before spin-acquire.arg1 for spin-spin contains the spin count: the number of iterations that were taken through the spin loop before the lock was acquired. The spin count has little meaning on its own but can be used to compare spin times.
spin-release	Hold-event probe that fires immediately after a spin lock is released.

10.6.4.3. Thread Locks

Thread lock hold events are available as spin lock hold-event probes (that is, spin-acquire and spin-release), but contention events have their own probe specific to thread locks. The thread lock hold-event probe is described in Table 10.9.

Table 10.9. Thread Lock Probes

Probe Name

Description

tHRead-spin

Contention-event probe that fires after a thread has spun on a thread lock. Like other contention-event probes, if both the contention-event probe and the hold-event probe are enabled, thread-spin fires before spin-acquire. Unlike other contention-event probes, however, thread-spin fires before the lock is actually acquired. As a result, multiple thread-spin probe firings may correspond to a single spin-acquire probe firing.

10.6.4.4. Readers/Writer Lock Probes

The probes pertaining to readers/writer locks are in Table 10.10. For each probe, arg0 contains a pointer to the krwlock_t structure that represents the adaptive lock.

Table 10.10. Readers/Writer Lock Probes

Probe Name	Description
rw-acquire	Hold-event probe that fires immediately after a readers/writer lock is acquired. arg1 contains the constant RW_READER if the lock was acquired as a reader, and RW_WRITER if the lock was acquired as a writer.
rw-block	Contention-event probe that fires after a thread that has blocked on a held readers/writer lock has reawakened and has acquired the lock. arg1 contains the length of time (in nanoseconds) that the current thread had to sleep to acquire the lock. arg2 contains the constant RW_READER if the lock was acquired as a reader, and RW_WRITER if the lock was acquired as a writer. arg3 and arg4 contain more information on the reason for blocking. arg3 is nonzero if and only if the lock was held as a writer when the current thread blocked. arg4 contains the readers count when the current thread blocked. If both the rw-block and rw-acquire probes are enabled, rw-block fires before rw-acquire.
rw-upgrade	Hold-event probe that fires after a thread has successfully upgraded a readers/writer lock from a reader to a writer. Upgrades do not have an associated contention event because they are only possible through a nonblocking interface, rw_tryupgrade(TRYUPGRADE.9F).
rw-downgrade	Hold-event probe that fires after a thread had downgraded its ownership of a readers/writer lock from writer to reader. Downgrades do not have an associated contention event because they always succeed without contention.
rw-release	Hold-event probe that fires immediately after a readers/writer lock is released. arg1 contains the constant RW_READER if the released lock was held as a reader, and RW_WRITER if the released lock was held as a writer. Due to upgrades and downgrades, the lock may not have been released as it was acquired.

10.6.5. The Java Virtual Machine Provider

This following section lists all probes published by the hotspot provider.

10.6.5.1. VM Life Cycle Probes

Three probes are available related to the VM life cycle, as shown in Table 10.11.

Table 10.11. VM Life Cycle Probes

Probe	Description
vm-init-begin	This probe fires just as the VM initialization begins. It occurs just after JNI_CreateVM() is called, as the VM is initializing.
vm-init-end	This probe fires when the VM initialization finishes, and the VM is ready to start running application code.
vm-shutdown	Probe that fires as the VM is shutting down due to program termination or error

10.6.5.2. Thread Life Cycle Probes

Two probes are available for tracking thread start and stop events, as shown in Table 10.12.

Table 10.12. Thread Life Cycle Probes

Probe	Description
tHRead-start	Probe that fires as a thread is started
tHRead-stop	Probe that fires when the thread has completed

Each of these probes has the arguments shown in Table 10.13.

Table 10.13. Thread Life Cycle Probe Arguments

Argument	Description
args[0]	A pointer to mUTF-8 string data which contains the thread name
args[1]	The length of the thread name (in bytes)
args[2]	The Java thread ID. This is the value that will match other hotspot probes that contain a thread argument.
args[3]	The native/OS thread ID. This is the ID assigned by the host operating system.
args[4]	A boolean value that indicates if this thread is a daemon or not. A value of 0 indicates a non-daemon thread.

10.6.5.3. Class-Loading Probes

Two probes are available for tracking class loading and unloading activity, as shown in Table 10.14.

Table 10.14. Class-Loading Probes

Probe	Description
class-loaded	Probe that fires after the class has been loaded
class-unloaded	Probe that fires after the class has been unloaded from the system

Each of these probes has the arguments shown in Table 10.15.

Table 10.15. Class-Loading Probe Arguments

Argument	Description
args[0]	A pointer to mUTF-8 string data which contains the name of the class begin loaded
args[1]	The length of the class name (in bytes)
args[2]	The class loader ID, which is a unique identifier for a class loader in the VM. This is the class loader that has loaded or is loading the class
args[3]	A boolean value which indicates if the class is a shared class (if the class was loaded from the shared archive)

10.6.5.4. Garbage Collection Probes

The following probes measure the duration of a system-wide garbage collection cycle (for those garbage collectors that have a defined begin and end), and each memory pool can be tracked independently. The probes for individual pools pass the memory manager's name, the pool name, and pool usage information at both the begin and end of pool collection.

The provider's GC-related probes are shown in Table 10.16.

Table 10.16. Garbage Collection Probes

Probe	Description
gc-begin	Probe that fires when system-wide collection is about to start. Its one argument (arg[0]) is a boolean value that indicates if this is to be a Full GC.
gc-end	Probe that fires when system-wide collection has completed. No arguments.
mem-pool-gc-begin	Probe that fires when an individual memory pool is about to be collected. Provides the arguments listed in Table 10.17.
mem-pool-gc-end	Probe that fires after an individual memory pool has been collected.

The memory pool probe arguments are as follows:

Table 10.17. Garbage Collection Probe Arguments

Argument	Description
args[0]	A pointer to mUTF-8 string data that contains the name of the manager which manages this memory pool
args[1]	The length of the manager name (in bytes)
args[2]	A pointer to mUTF-8 string data that contains the name of the memory pool
args[3]	The length of the memory pool name (in bytes)
args[4]	The initial size of the memory pool (in bytes)
args[5]	The amount of memory in use in the memory pool (in bytes)
args[6]	The number of committed pages in the memory pool
args[7]	The maximum size of the memory pool

10.6.5.5. Method Compilation Probes

The following probes indicate which methods are being compiled and by which compiler. Then, when the method compilation has completed, it can be loaded and possibly unloaded later. Probes are available to track these events as they occur.

Probes that mark the begin and end of method compilation are shown in Table 10.18.

Table 10.18. Method Compilation Probes

Probe	Description
method-compile-begin	Probe that fires as method compilation begins. Provides the arguments listed below
method-compile-end	Probe that fires when method compilation completes. In addition to the arguments listed below, argv[8] is a boolean value which indicates if the compilation was successful

Method compilation probe arguments are shown in Table 10.19.

Table 10.19. Method Compilation Probe Arguments

Argument	Description
args[0]	A pointer to mUTF-8 string data which contains the name of the compiler which is compiling this method
args[1]	The length of the compiler name (in bytes)
args[2]	A pointer to mUTF-8 string data which contains the name of the class of the method being compiled
args[3]	The length of the class name (in bytes)
args[4]	A pointer to mUTF-8 string data which contains the name of the method being compiled
args[5]	The length of the method name (in bytes)
args[6]	A pointer to mUTF-8 string data which contains the signature of the method being compiled
args[7]	The length of the signature(in bytes)

When compiled methods are installed for execution, the probes shown in Table 10.20 are fired.

Table 10.20. Compiled Method Install Probes

Probe	Description
compiled-method-load	Probe that fires when a compiled method is installed. In addition to the arguments listed below, argv[6] contains a pointer to the compiled code, and argv[7] is the size of the compiled code.
compiled-method-unload	Probe that fires when a compiled method is unin-stalled. Provides the arguments listed in Table 10.21.

Compiled method loading probe arguments are as follows:

Table 10.21. Compiled Method Install Probe Arguments

Argument	Description
args[0]	A pointer to mUTF-8 string data which contains the name of the class of the method being installed
args[1]	The length of the class name (in bytes)
args[2]	A pointer to mUTF-8 string data which contains the name of the method being installed
args[3]	The length of the method name (in bytes)
args[4]	A pointer to mUTF-8 string data which contains the signature of the method being installed
args[5]	The length of the signature(in bytes)

10.6.5.6. Monitor Probes

As an application runs, threads will enter and exit monitors, wait on objects, and perform notifications. Probes are available for all wait and notification events, as well as for contended monitor entry and exit events. A contended monitor entry is the situation where a thread attempts to enter a monitor when another thread is already in the monitor. A contended monitor exit event occurs when a thread leaves a monitor and other threads are waiting to enter to the monitor. Thus, contended enter and contended exit events may not match up to each other in relation to the thread that encounters these events, though it is expected that a contended exit from one thread should match up to a contended enter on another thread (the thread waiting for the monitor).

All monitor events provide the thread ID, a monitor ID, and the type of the class of the object as arguments. It is expected that the thread and the class will help map back to the program, while the monitor ID can provide matching information between probe firings.

Since the existance of these probes in the VM causes performance degradation, they will only fire if the VM has been started with the command-line option -XX:+ExtendedDtraceProbes. By default they are present in any listing of the probes in the VM, but are dormant without the flag. It is intended that this restriction be removed in future releases of the VM, where these probes will be enabled all the time with no impact to performance.

The available probes are shown in Table 10.22.

Table 10.22. Monitor Probes

Probe	Description
monitor-contended-enter	Probe that fires as a thread attempts to enter a contended monitor.
monitor-contended-entered	Probe that fires when the thread successfully enters the contended monitor.
monitor-contended-exit	Probe that fires when the thread leaves a monitor and other threads are waiting to enter.
monitor-wait	Probe that fires as a thread begins a wait on an object via Object.wait(). The probe has an additional argument, args[4] which is a "long" value which indicates the timeout being used.
monitor-waited	Probe that fires when the thread completes an Object.wait() and has been either been notified, or timed out.
monitor-notify	Probe that fires when a thread calls Object.notify() to notify waiters on a monitor monitor-notifyAll Probe that fires when a thread calls Object. notifyAll() to notify waiters on a monitor.

Monitor probe arguments are shown in Table 10.23.

Table 10.23. Monitor Probe Arguments

Argument	Description
args[0]	The Java thread identifier for the thread peforming the monitor operation
args[1]	A unique, but opaque identifier for the specific monitor that the action is performed upon
args[2]	A pointer to mUTF-8 string data which contains the name of the class of the object being acted upon
args[3]	The length of the class name (in bytes)

10.6.5.7. Application Tracking Probes

A few probes are provided to allow fine-grained examination of the Java thread execution. These consist of probes that fire anytime a method in entered or returned from, as well as a probe that fires whenever a Jav object has been allocated.

Since the existance of these probes in the VM causes performance degradation, they will only fire if the VM has been started with the command-line option -XX:+ExtendedDtraceProbes. By default they are present in any listing of the probes in the VM, but are dormant without the flag. It is intended that this restriction be removed in future releases of the VM, where these probes will be enabled all the time with no impact to performance.

The method entry and return probes are shown in Table 10.24.

Table 10.24. Application Tracking Probes

Probe	Description
method-entry	Probe which fires when a method is begin entered. Only fires if the VM was created with the ExtendedDtraceProbes command-line argument.
method-return	Probe which fires when a method returns normally or due to an exception. Only fires if the VM was created with the Extended-DtraceProbes command-line argument.

Method probe arguments are shown in Table 10.25.

Table 10.25. Application Tracking Probe Arguments

Argument	Description
args[0]	The Java thread ID of the thread that is entering or leaving the method
args[1]	A pointer to mUTF-8 string data which contains the name of the class of the method
args[2]	The length of the class name (in bytes)
args[3]	A pointer to mUTF-8 string data which contains the name of the method
args[4]	The length of the method name (in bytes)
args[5]	A pointer to mUTF-8 string data which contains the signature of the method
args[6]	The length of the signature(in bytes)

The available allocation probe is shown in Table 10.26.

Table 10.26. Allocation Probe

Probe	Description
object-alloc	Probe that fires when any object is allocated, provided that the VM was created with the ExtendedDtraceProbes command-line argument.

The object allocation probe has the arguments shown in Table 10.27.

Table 10.27. Allocation Probe Arguments

Argument	Description
args[0]	The Java thread ID of the thread that is allocating the object
args[1]	A pointer to mUTF-8 string data which contains the name of the class of the object being allocated
args[2]	The length of the class name (in bytes)
args[3]	The size of the object being allocated

10.6.5.8. The hotspot_jni Provider

The JNI provides a number of methods for invoking code written in the Java Programming Language, and for examining the state of the VM. DTrace probes are provided at the entry point and return point for each of these methods. The probes are provided by the hotspot_jni provider. The name of the probe is the name of the JNI method, appended with "_entry" for enter probes, and "_return" for return probes. The arguments available at each entry probe are the arguments that were provided to the function (with the exception of the Invoke* methods, which omit the arguments that are passed to Java method). The return probes have the return value of the method as an argument (if available).