DTRACE(1) 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 compiler, the ability to retrieve buffered trace data from the
DTrace kernel facility, and a set of basic routines to format and print traced data.
Users new to DTrace are encouraged to read: How To Use DTrace. Sun Microsystems, 2005. Available on
the web at http://www.sun.com/software/solaris/howtoguides/dtracehowto.jsp
DESCRIPTION
The dtrace command provides a generic interface to all of the essential services provided by the
DTrace facility, including:
Options to list the set of probes and providers currently published by DTrace
Options to enable probes directly using any of the probe description specifiers (provider, module,
function, name)
Options to run the D compiler and compile one or more D program files or programs written directly
on the command-line
Options to generate anonymous tracing programs
Options to generate program stability reports
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 con-
structs a plist(5) of dtrace directives to enable the specified probes for anonymous trcaing
and then exits. By default, dtrace attempts to store the plist to the file /Sys-
tem/Library/Extensions/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 command 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 descrip-
tion 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 specified, 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 descrip-
tion, 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 prefixed with ->. Function return probe reports are unin-
dented 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 path-
names, 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 directory 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 speci-
fied 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, func-
tion: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 variable.
-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 com-
piled but no instrumentation is enabled. If the -l option is specified, the program is com-
piled and the set of probes matched by it is listed, but no instrumentation 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 invocation.
-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 infor-
maion 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 descriptions 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 com-
mand 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.
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 successfully compiled, probes were successfully enabled, or
anonymous state was successfully retrieved. dtrace returns 0 even if the specified tracing
requests encountered errors or drops.
1 A fatal error occurred. For D program requests, the 1 exit status indicates that program com-
pilation failed or that the specified request could not be satisfied.
2 Invalid command-line options or arguments were specified.
SEE ALSO
How To Use DTrace. Sun Microsystems, 2005. Available on the web at http://www.sun.com/soft-
ware/solaris/howtoguides/dtracehowto.jsp
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)
|