Dynamic Tracing Guide
PreviousNext
Chapter 17

dtrace Provider

The dtrace provider provides several probes related to DTrace itself. 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 will fire until all BEGIN clauses have completed. This probe can be used to initialize any state that is needed in other probes. The following example shows how to use the BEGIN probe to initialize an associative array to map between mmap(2) protection bits and a textual representation:

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.

The 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. The printa action is therefore often used in the END probe. The BEGIN and END probes can be used together to measure the total time spent tracing:

BEGIN
{
	start = timestamp;
}

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

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

See Data Normalization and printa() for other common uses of the END probe.

As with the BEGIN probe, no arguments are defined for the END probe. The context in which the END probe fires is arbitrary and should not be depended upon.

When tracing with the bufpolicy option set to fill, adequate space is reserved to accommodate any records traced in the END probe. See fill Policy and END Probes for details.


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. During this delay, no probes will fire. 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 statusrate option. For more information, see Chapter 16, 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.

error.d: Record Errors

BEGIN
{
	*(char *)NULL;
}

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

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

# 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(1M) reporting the error. dtrace has its own enabling of the ERROR probe to allow it to report errors. Using the ERROR probe, you can create your own custom error handling.

The arguments to the ERROR probe are as follows:

arg1

The enabled probe identifier (EPID) of the probe that caused the error

arg2

The index of the action that caused the fault

arg3

The DIF offset into that action or -1 if not applicable

arg4

The fault type

arg5

Value particular to the fault type

The table below describes the various fault types and the value that arg5 will have for each:

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

If the actions taken in the ERROR probe itself cause an error, that error is silently dropped — the ERROR probe will not be recursively invoked.

Stability

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

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

PreviousNext