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.

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.

Example 17–1 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:

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

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.