Go to main content

Oracle® Solaris 11.4 DTrace (Dynamic Tracing) Guide

Exit Print View

Updated: September 2020
 
 

dtrace Provider

The dtrace provider provides several probes related to DTrace. You can use these probes to initialize state before tracing begins, process state after tracing has completed, and handle unexpected execution errors in other probes.

BEGIN Probe

The BEGIN probe fires before any other probe. No other probe fires until all BEGIN clauses are completed. You can use this probe to initialize any state that is required in other probes. The following example shows how to use the BEGIN probe to initialize an associative array to map between mmap protection bits and a textual representation. For information about the mmap system call, see the mmap(2) man page.

BEGIN
{
        prot[0] = "---";
        prot[1] = "r--";
        prot[2] = "-w-";
        prot[3] = "rw-";
        prot[4] = "--x";
        prot[5] = "r-x";
        prot[6] = "-wx";
        prot[7] = "rwx";
}

syscall::mmap:entry
{
        printf("mmap with prot = %s", prot[arg2 & 0x7]);
}

The BEGIN probe fires in an unspecified context. This means that the output of stack or ustack, and the value of context-specific variables (for example, execname), are all arbitrary. These values should not be relied upon or interpreted to infer any meaningful information. No arguments are defined for the BEGIN probe.

END Probe

The END probe fires after all other probes. This probe will not fire until all other probe clauses have completed. This probe can be used to process state that has been gathered or to format the output. Therefore, the END probe often uses the printa action. You can use the BEGIN and END probes together to measure the total time spent in tracing.

BEGIN
{
        start = timestamp;
}

/*
 * ... other tracing actions...
 */

END
{
        printf("total time: %d secs", (timestamp - start) / 1000000000);
}

For information about other uses of the END probe, see Data Normalization and printa Action.

No arguments are defined for the END probe. The context in which the END probe fires is arbitrary.

When tracing with the bufpolicy option set to fill, adequate space is reserved to accommodate any records traced in the END probe. For more information, see fill Policy and END Probes.


Note -  The exit action causes tracing to stop and the END probe to fire. However, there is some delay between the invocation of the exit action and the END probe firing. No probes fire during this delay. After a probe invokes the exit action, the END probe is not fired until the DTrace consumer determines that exit has been called and stops tracing. The rate at which the exit status is checked can be set using the statusrate option. For more information, see DTrace Options and Tunables.

ERROR Probe

The ERROR probe fires when a run-time error occurs in executing a clause for a DTrace probe. For example, if a clause attempts to dereference a NULL pointer, the ERROR probe will fire, as shown in the following example.

Example 25  Showing How to Record Errors
BEGIN
{
*(char *)NULL;
}

ERROR
{
printf("Hit an error!");
}

When you run this program, you will see the following output:

# .dtrace -s ./error.d
dtrace: script './error.d' matched 2 probes
CPU ID FUNCTION:NAME
2 3 :ERROR Hit an error!
dtrace: error on enabled probe ID 1 (ID 1: dtrace:::BEGIN): invalid address
(0x0) in action #1 at DIF offset 12
dtrace: 1 error on CPU 2

The output shows that the ERROR probe fired, and also illustrates dtrace reporting the error. dtrace has its own enabling of the ERROR probe to allow it to report errors. Use the ERROR probe to customize error handling.

The arguments to the ERROR probe are as follows:

  • arg1 – Enabled probe identifier (EPID) of the probe that caused the error

  • arg2 – Index of the action that caused the fault

  • arg3 – DIF offset into that action or -1 if not applicable

  • arg4 – Fault type

  • arg5 – Value particular to the fault type

The following table describes the arg4 fault types and the value and its meaning for the arg5.

Table 21  ERROR Probe Fault Types and Values
arg4 Value
Description
arg5 Meaning
DTRACEFLT_UNKNOWN
Unknown fault type
None
DTRACEFLT_BADADDR
Access to unmapped or invalid address
Address accessed
DTRACEFLT_BADALIGN
Unaligned memory access
Address accessed
DTRACEFLT_ILLOP
Illegal or invalid operation
None
DTRACEFLT_DIVZERO
Integer divide by zero
None
DTRACEFLT_NOSCRATCH
Insufficient scratch space to satisfy scratch allocation
None
DTRACEFLT_KPRIV
Attempt to access a kernel address or property without sufficient privileges
Address accessed or 0 if not applicable
DTRACEFLT_UPRIV
Attempt to access a user address or property without sufficient privileges
Address accessed or 0 if not applicable
DTRACEFLT_TUPOFLOW
DTrace internal parameter stack overflow
None
DTRACEFLT_BADSTACK
Invalid user process stack
Address of invalid stack pointer

If the error actions taken in the ERROR probe cause an error, the error is dropped and the ERROR probe is not recursively invoked.

dtrace Provider Stability

The dtrace provider uses the stability mechanism of DTrace to describe its stabilities as shown in the following table. For more information about the stability mechanism, see DTrace Stability Mechanisms.

Table 22  Stability Mechanism for dtrace
Element
Name Stability
Data Stability
Dependency Class
Provider
Stable
Stable
Common
Module
Private
Private
Unknown
Function
Private
Private
Unknown
Name
Stable
Stable
Common
Arguments
Stable
Stable
Common