DTRACE(1)DTRACE(1)NAMEdtrace - generic front-end to the DTrace facility
SYNOPSISdtrace [-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 ker‐
nel facility, and a set of basic routines to format and print traced
data. Due to the kernel facility it uses to operate, the dtrace com‐
mand 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. Avail‐
able 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:
· 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
OPTIONSdtrace has the following options:
-arch arch_name
Set dtrace's target data model. See arch(1) for a list of cur‐
rently 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
anonymous 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 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 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
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 trac‐
ing 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 execut‐
ing them and enabling the corresponding instrumentation.
-f Specify function name to trace or list (-l option). The corre‐
sponding argument can include any of the probe description forms
provider:module:function, module:function, or function. Unspec‐
ified probe description fields are left blank and match any
probes regardless of the values in those fields. If no quali‐
fiers 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
prefixed 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 speci‐
fied 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 defini‐
tions 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 corre‐
sponding 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 corre‐
sponding 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 remain‐
ing 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 num‐
ber 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 instrumen‐
tation will be enabled. If neither -e or -l are present, the
instrumentation specified by the D program is enabled and trac‐
ing 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 invo‐
cation.
-v Set verbose mode. If the -v option is specified, dtrace pro‐
duces 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
descriptions that do not match any known probes.
OPERANDS
Zero or more additional arguments may be specified on the dtrace com‐
mand 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 ACTIONSpidresume(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 dtracestop() action. Passing a pid for a process that does
not exist, or that was not stopped using dtracestop() 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 pro‐
gram 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 sta‐
tus indicates that program compilation failed or that the speci‐
fied 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)
