DTRACE(1) General Commands Manual DTRACE(1)
NAME
dtrace - generic front-end to the DTrace facility
SYNOPSIS
dtrace [-aACeFhHlqSvVwZ] [-arch arch_name]
[-b bufsz] [-c fullPathToCommand] [-D name[=def]]
[-I path] [-L path] [-o output] [-p pid]
[-s script] [-U name] [-x arg[=val]]
[-P provider [[predicate] action]]
[-m [provider:] module [[predicate] action]]
[-f [[provider:] module:] function [[predicate] action]]
[-n [[[provider:] module:] function:] name [[predicate] action]]
[-i probe-id [[predicate] action]]
OVERVIEW
The dtrace command is a generic front-end to the DTrace facility. The command implements a simple interface to invoke the D language com-
piler, the ability to retrieve buffered trace data from the DTrace kernel facility, and a set of basic routines to format and print traced
data. Due to the kernel facility it uses to operate, the dtrace command requires root privileges.
Users new to DTrace are encouraged to read: How to Use Oracle Solaris DTrace from Oracle Solaris and OpenSolaris System. Oracle, 2010.
Available on the web at http://developers.sun.com/solaris/docs/o-s-dtrace-htg.pdf
DESCRIPTION
The dtrace command provides a generic interface to all of the essential services provided by the DTrace facility, including:
o Options to list the set of probes and providers currently published by DTrace
o Options to enable probes directly using any of the probe description specifiers (provider, module, function, name)
o Options to run the D compiler and compile one or more D program files or programs written directly on the command-line
o Options to generate anonymous tracing programs
o Options to generate program stability reports
o Options to modify DTrace tracing and buffering behavior and enable additional D compiler features
OPTIONS
dtrace has the following options:
-arch arch_name
Set dtrace's target data model. See arch(1) for a list of currently supported architectures.
-a Claim anonymous tracing state and display the traced data. You can combine the -a option with the -e option to force dtrace to exit
immediately after consuming the anonymous tracing state rather than continuing to wait for new data.
-A Generate a plist(5) of directives for anonymous tracing. If the -A option is specified, dtrace compiles any D programs specified
using the -s option or on the command-line and constructs a plist(5) of dtrace directives to enable the specified probes for anony-
mous trcaing and then exits. By default, dtrace attempts to store the plist to the file /System/Library/Exten-
sions/dtrace_dof.kext/Contents/Info.plist. This behavior can be modified using the -o option to specify an alternate output file.
-b Set principal trace buffer size. The trace buffer size can include any of the size suffixes k, m, g, or t. If the buffer space
cannot be allocated, dtrace attempts to reduce the buffer size or exit depending on the setting of the bufresize property.
-c Run the specified command cmd and exit upon its completion. If more than one -c option is present on the command line, dtrace exits
when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first com-
mand is made available to any D programs specified on the command line or using the -s option through the $target macro variable.
-C Run the C preprocessor cpp over D programs before compiling them. Options can be passed to the C preprocessor using the -D, -U, -I,
and -H options. The degree of C standard conformance can be selected using the -X option. Refer to the description of the -X
option for a description of the set of tokens defined by the D compiler when invoking the C preprocessor.
-D Define the specified name when invoking cpp (enabled using the -C option). If an equals sign (=) and additional value are speci-
fied, the name is assigned the corresponding value. This options passes the -D option to each cpp invocation.
-e Exit after compiling any requests and consuming anonymous tracing state (-a option) but prior to enabling any probes. This option
can be combined with the -a option to print anonymous tracing data and exit, or it can be compiled with D compiler options to verify
that programs compile without actually executing them and enabling the corresponding instrumentation.
-f Specify function name to trace or list (-l option). The corresponding argument can include any of the probe description forms
provider:module:function, module:function, or function. Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields. If no qualifiers other than function are specified in the description, all probes with
the corresponding function are matched. The -f argument can be suffiexed with an optional D probe clause. More than one -f option
may be specified on the command-line at a time.
-F Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is pre-
fixed with ->. Function return probe reports are unindented and their output is prefixed with <-.
-h Generate a header file containing macro definitions for USDT probes. If the -o option is present, the header file is saved using the
pathname specified as the argument for this flag. If the -o option is not present and the DTrace program is contained in a file
whose name is filename.d, the header file is saved using the name filename.h.
-H Print the pathnames of included files when invoking cpp (enabled using the -C option). This option passes the -H option to each cpp
invocation, causing it to display the list of pathnames, one per line, to stderr.
-i Specify probe identifier to trace or list (-l option). Probe IDs are specified using decimal integers as shown by dtrace -l. The
-i argument can be suffixed with an optional D probe clause. More than one -i option may be specified on the command-line at a
time.
-I Add the specified directory path to the search path for #include files when invoking cpp (enabled using the -C option). This option
passes the -I option to each cpp invocation. The specified directory is inserted into the search path ahead of the default direc-
tory list.
-l List all probes matching probe specifications appearing in -f, -i, -m, -n, or -P options. No tracing is initiated for any probes.
-L Add the specified directory path to the search path for DTrace libraries. DTrace libraries are used to contain common definitions
that may be used when writing D programs. The specified path is added after the default library search path.
-m Specify module name to trace or list (-l option). The corresponding argument can include any of the probe description forms
provider:module or module. Unspecified probe description fields are left blank and match any probes regardless of the values in
those fields. If no qualifiers other than module are specified in the description, all probes with a corresponding module are
matched. The -m argument can be suffixed with an optional D probe clause. More than one -m option may be specified on the command-
line at a time.
-n Specify probe name to trace or list (-l option). The corresponding argument can include any of the probe description forms
provider:module:function:name, module:function:name, function:name, or name. Unspecified probe description fields are left blank
and match any probes regardless of the values in those fields. If no qualifiers other than name are specified in the description,
all probes with a corresponding name are matched. The -n argument can be suffixed with an optional D probe clause. More than one
-n option may be specified on the command-line at a time.
-o Specify the output file for the -A and -l options, or for the traced data. If the -A option is present, and -o is not present, the
default output file is /kernel/drv/dtrace.conf.
-p Grab the specified process-ID pid, cache its symbol tables, and exit upon its completion. If more than one -p option is present on
the command line, dtrace exits when all commands have exited, reporting the exit status for each process as it terminates. The first
process-ID is made available to any D programs spe cified on the command line or using the -s option through the $target macro vari-
able.
-P Specify provider name to trace or list (-l option). The remaining probe description fields module, function, and name are left
blank and match any probes regardless of the values in those fields. The -P argument can be suffixed with an optional D probe
clause. More than one -P option may be specified on the command-line at a time.
-q Set quiet mode. dtrace will suppress messages such as the number of probes matched by the specified options and D programs will not
print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program
statements such as trace() and printf() will be displayed to stdout.
-s Compile the specified D program source file. If the -e option is present, the program is compiled but no instrumentation is
enabled. If the -l option is specified, the program is compiled and the set of probes matched by it is listed, but no instrumenta-
tion will be enabled. If neither -e or -l are present, the instrumentation specified by the D program is enabled and tracing
begins.
-S Show D compiler intermediate code. The D compiler will produce a report of the intermediate code generated for each D program to
stderr.
-U Undefine the specified name when invoking cpp (enabled using the -C option). This option passes the -U option to each cpp invoca-
tion.
-v Set verbose mode. If the -v option is specified, dtrace produces a program stability report showing the minimum interface stability
and dependency level for the specified D programs.
-V Report the highest D programming interface version supported by dtrace. The version informaion is printed to stdout and the dtrace
command exits.
-w Allow destructive actions. D programs containing destructive actions will fail to compile unless this flag is specified.
-x Enable or modify a DTrace runtime option or D compiler option. Boolean options are enabled by specifying their name. Options with
values are set by separating the option name and value with an equals sign (=).
-Z Permit probe descriptions that match zero probes. If the -Z option is not specified, dtrace will report an error and exit if any
probe descriptions specified in D program files (-s option) or on the command-line (-P, -m, -f, -n, or -i options) contain descrip-
tions that do not match any known probes.
OPERANDS
Zero or more additional arguments may be specified on the dtrace command line to define a set of macro variables ($1, $2, and so on) to be
used in any D programs specified using the -s option or on the command-line.
C++ MANGLED NAMES
By default, dtrace uses the demangled names of C++ symbols. You can tell dtrace to use the mangled symbol names by passing -xmangled to the
command.
OBJECTIVE C PROVIDER
The Objective C provider is similar to the pid provider, and allows instrumentation of Objective C classes and methods. Objective C probe
specifiers use the following format:
objcpid:[class-name[(category-name)]]:[[+|-]method-name]:[name]
pid The id number of the process.
class-name
The name of the Objective C class.
category-name
The name of the category within the Objective C class.
method-name
The name of the Objective C method.
name The name of the probe, entry, return, or an integer instruction offset within the method.
OBJECTIVE C PROVIDER EXAMPLES
objc123:NSString:-*:entry
Every instance method of class NSString in process 123.
objc123:NSString(*)::entry
Every method on every category of class NSString in process 123.
objc123:NSString(foo):+*:entry
Every class method in NSString's foo category in process 123.
objc123::-*:entry
Every instance method in every class and category in process 123.
objc123:NSString(foo):-dealloc:entry
The dealloc method in the foo category of class NSString in process 123.
objc123::method?with?many?colons:entry
The method method:with:many:colons in every class in process 123. (A ? wildcard must be used to match colon characters inside of
Objective C method names, as they would otherwise be parsed as the provider field separators.)
BUILDING CODE CONTAINING USDT PROBES
The process of adding USDT probes to code is slightly different than documented in the Solaris Dynamic Tracing Guide. The steps for adding
probes are as follows:
1. Name the provider and specify its probes, using the following form:
provider Example {
probe increment(int);
};
This defines the Example provider with one probe, increment, that takes a single int argument. Providers can define multiple probes and
probes can take multiple arguments.
2. Process the provider description into a header file.
The provider description must be converted into a form usable by ObjC/C/C++ code. The dtrace command should be invoked with the -h flag
to do this.
dtrace -h -s exampleProvider.d
This will generate a header file named exampleProvider.h
3. Add probe invocations to the application
For each probe defined in the provider, the provider.h file will contain two macros.The naming is as follows:
PROVIDER_PROBENAME()
PROVIDER_PROBENAME_ENABLED()
In the Example provider, the increment probe becomes:
EXAMPLE_INCREMENT()
EXAMPLE_INCREMENT_ENABLED()
Place a macro invocation in the code at each site to be traced. If the arguments passed to a probe are expensive to calculate, you may
guard the probe placement like this:
if (EXAMPLE_INCREMENT_ENABLED()) {
argument = /* Expensive argument calculation code here */;
EXAMPLE_INCREMENT(argument);
};
The if test will only succeed when the increment probe is active.
4. Compile and link your program normally. No additional compiler or linker flags are required.
OS X BUILTIN VARIABLE CHANGES
A small number of DTrace builtin variables have OS X specific changes:
execname
A string giving the name that was passed to exec(2) to execute the current process. The string consists of at most MAXCOMLEN-1
characters. The constant MAXCOMLEN is defined in /usr/include/sys/param.h to be 16.
tid A uint64_t thread ID of the currently executing thread. The thread ID is guaranteed to be unique and non repeating. The tid value is
not equivalent to pthread_self.
OS X SPECIFIC ACTIONS
pidresume(pid)
The pidresume(pid) action is a destructive action meant to be used in conjunction with the stop() action. While the stop() action
will task_suspend the currently running process, the pidresume(pid) action will task_resume it. The pidresume(pid) action will only
act on a process that has been stopped using the dtrace stop() action. Passing a pid for a process that does not exist, or that was
not stopped using dtrace stop() action, will result in an error.
EXIT STATUS
The following exit values are returned by the dtrace utility:
0 The specified requests were completed successfully. For D program requests, the 0 exit status indicates that programs were success-
fully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. dtrace returns 0 even if the spec-
ified tracing requests encountered errors or drops.
1 A fatal error occurred. For D program requests, the 1 exit status indicates that program compilation failed or that the specified
request could not be satisfied.
2 Invalid command-line options or arguments were specified.
SEE ALSO
How to Use Oracle Solaris DTrace from Oracle Solaris and OpenSolaris System. Oracle, 2010. Available on the web at http://www.ora-
cle.com/technetwork/server-storage/solaris10/solaris-dtrace-wp-167895.pdf
Solaris Dynamic Tracing Guide. Sun Microsystems, 2005. Available on the web at http://docs.sun.com/app/docs/doc/817-6223
Version 1.0 July 2006 DTRACE(1)