Getting Started

DTrace enables you to understand a software system by dynamically modifying the operating system kernel and user processes to record additional data that you specify at locations of interest, called probes. A probe is a location or activity to which DTrace can bind a request to perform a set of actions, like recording a stack trace, a timestamp, or the argument to a function. Probes are like programmable sensors scattered all over your Oracle Solaris system in interesting places. You can use DTrace to program the appropriate sensors to record the information that is of interest to you. Then, as each probe fires, DTrace gathers the data from your probes and reports it back to you. If you do not specify any actions for a probe, DTrace will just take note of each time the probe fires.

Every probe in DTrace has an unique integer ID and a probe description. For more information about the fields of a probe description, see Providers and Probes.

You can learn DTrace by building some simple requests using the probe named BEGIN, which fires once each time you start a new tracing request. You can use the -n option of the dtrace utility to enable a probe using its string name. Type the following command:

# dtrace -n BEGIN

The output shows that a probe was enabled and the BEGIN probe was fired. Once you see this output, dtrace remains paused waiting for other probes to fire. Since no other probes are enabled and BEGIN only fires once, press Control-C in the shell to exit dtrace and return to the shell prompt:

# dtrace -n BEGIN
dtrace: description 'BEGIN' matched 1 probe
CPU     ID                    FUNCTION:NAME
  0      1                            :BEGIN
^C
#

The output displays that the probe named BEGIN fired once and both its name and integer ID, 1, are printed. By default, the integer name of the CPU on which this probe fired is displayed. In this example, the CPU column indicates that the dtrace command was executing on CPU 0 when the probe fired.

DTrace requests can be constructed using arbitrary numbers of probes and actions. Create a simple request using two probes by adding the END probe to the previous example command. The END probe fires once when tracing is completed. Type the following command, and then again press Control-C in your shell after you see the line of output for the BEGIN probe:

# dtrace -n BEGIN -n END
dtrace: description 'BEGIN' matched 1 probe
dtrace: description 'END' matched 1 probe
CPU     ID                    FUNCTION:NAME
  0      1                    :BEGIN
^C
  0      2                    :END
#

Pressing Control-C to exit dtrace triggers the END probe. dtrace reports this probe firing before exiting. In addition to constructing DTrace experiments on the command line, you can also write them in text files using the D programming language. In a text editor, create a file called hello.d and type in your first D program:

Example 1-1 Hello, World in DTrace Using hello.d

In a text editor, create a file called hello.d and type in your first D program.

BEGIN
{
        trace("hello, world");
        exit(0);
}

Save the hello.d program and run it using the dtrace -s command. Type the following command:

# dtrace -s hello.d
dtrace: script 'hello.d' matched 1 probe
CPU     ID                    FUNCTION:NAME
  0         1                  :BEGIN   hello, world
#

dtrace printed the same output as before followed by the text "hello, world". Unlike the previous example, you did not have to wait and press Control-C, either. These changes were the result of the actions specified for BEGIN probe in hello.d.

Each D program consists of a series of clauses, each clause describing one or more probes to enable, and an optional set of actions to perform when the probe fires. The actions are listed as a series of statements enclosed in braces { } following the probe name. Each statement ends with a semicolon (;). Your first statement uses the function trace to indicate that DTrace should record the specified argument, the string "hello, world", when the BEGIN probe fires, and then print it out. The second statement uses the function exit to indicate that DTrace should cease tracing and exit the dtrace command. DTrace provides a set of useful functions like trace() and exit() to call in D programs. To call a function, you specify its name followed by a parenthesized list of arguments. The complete set of D functions is described in DTrace Actions and Subroutines.

The D programming language is similar to the C programming language. Indeed, the D programming language is derived from a large subset of C combined with a special set of functions and variables to help make tracing easy. You will learn more about the D programming features in subsequent chapters. You will understand all of the syntax by the end of this chapter.