Chapter 2. DTrace Basics

Table of Contents

Listing Probes
Specifying Probes in DTrace
Enabling Probes
DTrace Action Basics
Data Recording Actions
Destructive Actions
DTrace Aggregations
DTrace Aggregation Syntax

Listing Probes

You can list all DTrace probes by passing the l option to the dtrace command:

# dtrace -l
ID   PROVIDER    MODULE        FUNCTION NAME
 1     dtrace                           BEGIN
 2     dtrace                           END
 3     dtrace                           ERROR
 4    syscall                     nosys entry
 5    syscall                     nosys return
 6    syscall                     rexit entry
 7    syscall                     rexit return
 8    syscall                   forkall entry
 9    syscall                   forkall return
10    syscall                      read entry
11    syscall                      read return
...

To count all the probes that are available on your system, you can type the following command:

# dtrace -l | wc -l

The number of probes reported will vary depending on your operating platform and the software you have installed. Some probes do not list an entry under the MODULE or FUNCTION columns, such as the BEGIN and END probes in the previous example. Probes with blank entries in these fields do not correspond to a specifically instrumented program function or location. These probes refer to more abstract concepts, such as the end of a tracing request. A probe that has a module and function as part of its name is called an anchored probe. A probe that is not associated with a module and function is called an unanchored probe.

You can use additional options to list specific probes, as seen in the following examples.

Example 2.1. Listing Probes by Specific Function

You can list probes that are associated with a specific function by passing that function name to DTrace with the f option.

# dtrace -l -f cv_wait
ID      PROVIDER        MODULE        FUNCTION NAME
12921        fbt       genunix         cv_wait entry
12922        fbt       genunix         cv_wait return

Example 2.2. Listing Probes by Specific Module

You can list probes that are associated with a specific module by passing that module name to DTrace with the m option.

# dtrace -l -m sd
ID      PROVIDER        MODULE        FUNCTION NAME
17147        fbt            sd          sdopen entry
17148        fbt            sd          sdopen return
17149        fbt            sd         sdclose entry
17150        fbt            sd         sdclose return
17151        fbt            sd      sdstrategy entry
17152        fbt            sd      sdstrategy return
...

Example 2.3. Listing Probes by Specific Name

You can list probes that have a specific name by passing that name to DTrace with the n option.

# dtrace -l -n BEGIN
ID      PROVIDER        MODULE        FUNCTION NAME
1         dtrace                               BEGIN

Example 2.4. Listing Probes by Provider of Origin

You can list probes that are originate from a specific provider by passing the provider name to DTrace with the P option.

# dtrace -l -P lockstat
ID        PROVIDER        MODULE             FUNCTION NAME
469       lockstat       genunix          mutex_enter adaptive-acquire
470       lockstat       genunix          mutex_enter adaptive-block
471       lockstat       genunix          mutex_enter adaptive-spin
472       lockstat       genunix           mutex_exit adaptive-release
473       lockstat       genunix        mutex_destroy adaptive-release
474       lockstat       genunix       mutex_tryenter adaptive-acquire
...

Example 2.5. Multiple Providers Supporting a Specific Function or Module

A specific function or specific module can be supported by multiple providers, as the following example shows.

# dtrace -l -f read
ID        PROVIDER        MODULE             FUNCTION NAME
  10       syscall                               read entry
  11       syscall                               read return
4036       sysinfo       genunix                 read readch
4040       sysinfo       genunix                 read sysread
7885           fbt       genunix                 read entry
7886           fbt       genunix                 read return

As the previous examples show, the output for a listing of probes displays the following information:

  • The probe's uniquely assigned integer probe ID

    Note

    The probe ID is only unique within a given release or patch level of the Solaris operating system.

  • The provider name

  • The module name, if applicable

  • The function name, if applicable

  • The probe name