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.