dtrace.1

.TH DTRACE 1 "July 2006" "Version 1.0"
.SH NAME
dtrace \- generic front-end to the DTrace facility
.SH SYNOPSIS
.HP
.B dtrace
[\fB\-aACeFhHlqSvVwWZ\fR]
[\fB\-arch\fR \fIarch_name\fR]
.br
[\fB\-b\fR \fIbufsz\fR]
[\fB\-c\fR \fIfullPathToCommand\fR]
[\fB\-D\fR \fIname\fR[=\fIdef\fR]]
.br
[\fB\-I\fR \fIpath\fR]
[\fB\-L\fR \fIpath\fR]
[\fB\-o\fR \fIoutput\fR]
[\fB\-p\fR \fIpid\fR]
[\fB\-W\fR \fIpname\fR]
.br
[\fB\-s\fR \fIscript\fR]
[\fB\-U\fR \fIname\fR]
[\fB\-x\fR \fIarg\fR[=\fIval\fR]]
.br
[\fB\-P\fR \fIprovider\fR [[\fIpredicate\fR] \fIaction\fR]]
.br
[\fB\-m\fR [\fIprovider\fR:] \fImodule\fR [[\fIpredicate\fR] \fIaction\fR]]
.br
[\fB\-f\fR [[\fIprovider\fR:] \fImodule\fR:] \fIfunction\fR [[\fIpredicate\fR] \fIaction\fR]]
.br
[\fB\-n\fR [[[\fIprovider\fR:] \fImodule\fR:] \fIfunction\fR:] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]]
.br
[\fB\-i\fR \fIprobe\-id\fR [[\fIpredicate\fR] \fIaction\fR]]
.SH OVERVIEW
The \fIdtrace\fP 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.
Due to the kernel facility it uses to operate, the \fIdtrace\fP command requires root privileges.
.br
.P
Users new to DTrace are encouraged to read:
\fIHow to Use Oracle Solaris DTrace from Oracle Solaris and OpenSolaris
System\fP. Oracle, 2010. Available on the web at http://www.oracle.com/technetwork/server-storage/solaris/solaris-dtrace-wp-167895.pdf
.SH DESCRIPTION
The \fIdtrace\fP command provides a generic interface to all of the essential services provided by the DTrace facility, including:
." If I wanted numbered lists, I'd use .IP n[step] 3 for the first and .IP n+[step] for each other entry
.IP \(bu 2
Options to list the set of probes and providers currently published by DTrace
.IP \(bu
Options to enable probes directly using any of the probe description specifiers (provider, module, function, name)
.IP \(bu
Options to run the D compiler and compile one or more D program files or programs written directly on the command-line
.IP \(bu
Options to generate anonymous tracing programs
.IP \(bu
Options to generate program stability reports
.IP \(bu
Options to modify DTrace tracing and buffering behavior and enable additional D compiler features
.SH OPTIONS
\fIdtrace\fP has the following options:
.TP 7
.B \-arch\fR \fIarch_name\fR
Set dtrace's target data model. See \fIarch\fR(1) for a list of currently supported architectures.
.TP
.B \-a
Claim anonymous tracing state and display the traced data.  You can combine the \fB\-a\fP option with the \fB\-e\fP option to force \fIdtrace\fP to exit immediately after consuming the anonymous tracing state rather than continuing to wait for new data.
.TP
.B \-A
Generate a plist(5) of directives for anonymous tracing.  If the \fB\-A\fP
option is specified, \fIdtrace\fP compiles any D programs specified using the
\fB\-s\fP option or on the command-line and constructs a plist(5) of dtrace directives to enable the specified probes for anonymous tracing and then exits.  By default, \fIdtrace\fP attempts to store the plist to the file /System/Library/Extensions/dtrace_dof.kext/Contents/Info.plist.  This behavior can be modified using the \fB\-o\fP option to specify an alternate output file.
.TP
.B \-b
Set principal trace buffer size.  The trace buffer size can include any of the size suffixes \fBk\fP, \fBm\fP, \fBg\fP, or \fBt\fP.  If the buffer space cannot be allocated, \fIdtrace\fP attempts to reduce the buffer size or exit depending on the setting of the bufresize property.
.TP
.B \-c
Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB-c\fR option is present on the command line, \fBdtrace\fR 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 \fB-s\fR option through the \fB$target\fR macro variable.
.TP
.B \-C
Run the C preprocessor of \fIclang\fP over D programs before compiling them.  Options can be passed to the C preprocessor using the \fB\-D\fP, \fB\-U\fP, \fB\-I\fP, and \fB\-H\fP options.  The degree of C standard conformance can be selected using the \fB\-X\fP option.  Refer to the description of the \fB\-X\fP option for a description of the set of tokens defined by the D compiler when invoking the C preprocessor.
.TP
.B \-D
Define the specified \fIname\fP when invoking \fIclang\fP (enabled using the \fB\-C\fP option).  If an equals sign (=) and additional \fIvalue\fP are specified, the name is assigned the corresponding value.  This options passes the \fB\-D\fP option to each \fIclang\fP invocation.
.TP
.B \-e
Exit after compiling any requests and consuming anonymous tracing state (\fB\-a\fP option) but prior to enabling any probes.  This option can be combined with the \fB\-a\fP 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.
.TP
.B \-f
Specify function name to trace or list (\fB\-l\fP option).  The corresponding argument can include any of the probe description forms \fIprovider\fP:\fImodule\fP:\fIfunction\fP, \fImodule\fP:\fIfunction\fP, or \fIfunction\fP.  Unspecified probe description fields are left blank and match any probes regardless of the values in those fields.  If no qualifiers other than \fIfunction\fP are specified in the description, all probes with the corresponding \fIfunction\fP are matched.  The \fB\-f\fP argument can be suffiexed with an optional D probe clause.  More than one \fB\-f\fP option may be specified on the command-line at a time.
.TP
.B \-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 <-.
.TP
.B \-h
Generate a header file containing macro definitions for USDT probes. If the \fB\-o\fP option is present, the header file is saved using the pathname specified as the argument for this flag. If the \fB\-o\fP 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.
.TP
.B \-H
Print the pathnames of included files when invoking \fIclang\fP (enabled using the \fB\-C\fP option).  This option passes the \fB\-H\fP option to each \fIclang\fP invocation, causing it to display the list of pathnames, one per line, to stderr.
.TP
.B \-i
Specify probe identifier to trace or list (\fB\-l\fP option).  Probe IDs are specified using decimal integers as shown by \fIdtrace\fP \fB\-l\fP.  The \fB\-i\fP argument can be suffixed with an optional D probe clause.  More than one \fB\-i\fP option may be specified on the command-line at a time.
.TP
.B \-I
Add the specified directory \fIpath\fP to the search path for #include files when invoking \fIclang\fP (enabled using the \fB\-C\fP option).  This option passes the \fB\-I\fP option to each \fIclang\fP invocation.  The specified directory is inserted into the search path ahead of the default directory list.
.TP
.B \-l
List all probes matching probe specifications appearing in \fB\-f\fP, \fB\-i\fP, \fB\-m\fP, \fB\-n\fP, or \fB\-P\fP options. No tracing is initiated for any probes.
.TP
.B \-L
Add the specified directory \fIpath\fP 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 \fIpath\fP is added after the default library search path.
.TP
.B \-m
Specify module name to trace or list (\fB\-l\fP option).  The corresponding argument can include any of the probe description forms \fIprovider\fP:\fImodule\fP or \fImodule\fP.  Unspecified probe description fields are left blank and match any probes regardless of the values in those fields.  If no qualifiers other than \fImodule\fP are specified in the description, all probes with a corresponding \fImodule\fP are matched.  The \fB\-m\fP argument can be suffixed with an optional D probe clause.  More than one \fB\-m\fP option may be specified on the command-line at a time.
.TP
.B \-n
Specify probe name to trace or list (\fB\-l\fP option).  The corresponding argument can include any of the probe description forms \fIprovider\fP:\fImodule\fP:\fIfunction\fP:\fIname\fP, \fImodule\fP:\fIfunction\fP:\fIname\fP, \fIfunction\fP:\fIname\fP, or \fIname\fP.  Unspecified probe description fields are left blank and match any probes regardless of the values in those fields.  If no qualifiers other than \fIname\fP are specified in the description, all probes with a corresponding name are matched.  The \fB\-n\fP argument can be suffixed with an optional D probe clause.  More than one \fB\-n\fP option may be specified on the command-line at a time.
.TP
.B \-o
Specify the \fIoutput\fP file for the \fB\-A\fP and \fB\-l\fP options, or for the traced data.  If the \fB\-A\fP option is present, and \fB\-o\fP is not present, the default output file is /kernel/drv/dtrace.conf.
.br
Note that with successive invocations of dtrace with the -o option, dtrace does not overwrite, but rather appends to the output file.
.TP
.B \-p
Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB-p\fR option is present on the command line, \fBdtrace\fR
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 \fB-s\fR option through the \fB$target\fR macro variable. 
.TP
.B \-P
Specify provider name to trace or list (\fB\-l\fP 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 \fB\-P\fP argument can be suffixed with an optional D probe clause.  More than one \fB\-P\fP option may be specified on the command-line at a time.
.TP
.B \-q
Set quiet mode.  \fIdtrace\fP 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 \fBtrace()\fP and \fBprintf()\fP will be displayed to stdout.
.TP
.B \-s
Compile the specified D program source file.  If the \fB\-e\fP option is present, the program is compiled but no instrumentation is enabled.  If the \fB\-l\fP option is specified, the program is compiled and the set of probes matched by it is listed, but no instrumentation will be enabled.  If neither \fB\-e\fP or \fB\-l\fP are present, the instrumentation specified by the D program is enabled and tracing begins.
.TP
.B \-S
Show D compiler intermediate code.  The D compiler will produce a report of the intermediate code generated for each D program to stderr.
.TP
.B \-U
Undefine the specified \fIname\fP when invoking \fIclang\fP (enabled using the \fB\-C\fP option).  This option passes the \fB\-U\fP option to each \fIclang\fP invocation.
.TP
.B \-v
Set verbose mode.  If the \fB\-v\fP option is specified, \fIdtrace\fP produces a program stability report showing the minimum interface stability and dependency level for the specified D programs.
.TP
.B \-V
Report the highest D programming interface version supported by \fIdtrace\fP.  The version informaion is printed to stdout and the dtrace command exits.
.TP
.B \-w
Allow destructive actions. D programs containing destructive actions will fail to compile unless this flag is specified.
.TP
.B \-W
Wait for the specified process \fIpname\fR, cache its symbol tables, and exit upon its completion.  If more than one \fB-W\fR option is present on the command line, \fBdtrace\fR will
start tracing when all processes have been executed, in the order they have been specified.  Furthermore, \fBdtrace\fR exits when all processes have exited, reporting the exit status for each process
as it terminates.  The first process-ID  is made available to any D programs specified on the command line or using the \fB-s\fR option through the \fB$target\fR macro variable.
Using this option automatically activates the \fB-Z\fR option.
.TP
.B \-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 (=).
.TP
.B -Z
Permit probe descriptions that match zero probes.  If the \fB\-Z\fP option is not specified, \fIdtrace\fP will report an error and exit if any probe descriptions specified in D program files (\fB\-s\fP option) or on the command-line (\fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, or \fB\-i\fP options) contain descriptions that do not match any known probes.
.SH OPERANDS
Zero or more additional arguments may be specified on the \fIdtrace\fP command line to define a set of macro variables ($1, $2, and so on) to be used in any D programs specified using the \fB\-s\fP option or on the command-line.
.SH C++ MANGLED NAMES
By default, \fIdtrace\fP uses the demangled names of C++ symbols. You can tell \fIdtrace\fP to use the mangled symbol names by passing \fI-xmangled\fP to the command.
.SH 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:
.TP 7
.B objc\fIpid\fR:[\fIclass-name\fR[(\fIcategory-name\fR)]]:[[+|-]\fImethod-name\fR]:[\fIname\fR]
.TP
.B pid
The id number of the process.
.TP
.B class-name
The name of the Objective C class.
.TP
.B category-name
The name of the category within the Objective C class.
.TP
.B method-name
The name of the Objective C method.
.TP
.B name
The name of the probe, \fBentry\fR, \fBreturn\fR, or an integer instruction offset within the method.
.SH OBJECTIVE C PROVIDER EXAMPLES
.TP
.B objc123:NSString:-*:entry
Every instance method of class NSString in process 123.
.TP
.B objc123:NSString(*)::entry
Every method on every category of class NSString in process 123.
.TP
.B objc123:NSString(foo):+*:entry
Every class method in NSString's foo category in process 123.
.TP
.B objc123::-*:entry
Every instance method in every class and category in process 123.
.TP
.B objc123:NSString(foo):-dealloc:entry
The dealloc method in the foo category of class NSString in process 123.
.TP
.B objc123::method?with?many?colons:entry
The method method:with:many:colons in every class in process 123. (A \fB?\fR 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.)
.SH BUILDING CODE CONTAINING USDT PROBES
The process of adding USDT probes to code is slightly different than documented in the \fISolaris Dynamic Tracing Guide\fP. The steps for adding probes are as follows:
.IP 1. 3
Name the provider and specify its probes, using the following form:
.P
.RS 8
provider\ Example\ {
.br
\	probe\ increment(int);
.br
};
.RE
.IP "" 3
This defines the \fBExample\fP provider with one probe, \fBincrement\fP, that takes a single int argument. Providers can define multiple probes and probes can take multiple arguments.
.IP 2. 3
Process the provider description into a header file.
.IP
The provider description must be converted into a form usable by ObjC/C/C++ code. The dtrace command should be invoked with the \fB\-h\fP flag to do this.
.IP
.RS 8
\fBdtrace \-h \-s exampleProvider.d\fP
.RE
.IP "" 3
This will generate a header file named \fBexampleProvider.h\fP
.IP 3. 3
Add probe invocations to the application
.IP
For each probe defined in the provider, the provider.h file will contain two macros.The naming is as follows:
.IP
.RS 8
\fBPROVIDER_PROBENAME()
.br
PROVIDER_PROBENAME_ENABLED()\fP
.RE
.IP "" 3
In the Example provider, the increment probe becomes:
.RS 8
.P
\fBEXAMPLE_INCREMENT()
.br
EXAMPLE_INCREMENT_ENABLED()\fP
.RE
.IP "" 3
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:
.P
.RS 8
if (EXAMPLE_INCREMENT_ENABLED()) {
.br
\	argument = /* Expensive argument calculation code here */;
.br
\	EXAMPLE_INCREMENT(argument);
.br
};
.RE
.IP "" 3
The if test will only succeed when the increment probe is active.
.IP 4. 3
Compile and link your program normally. No additional compiler or linker flags are required.
.IP
.SH OS X BUILTIN VARIABLE CHANGES
A small number of DTrace builtin variables have OS X specific changes:
.TP
.B 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.
.TP
.B machtimestamp
A uint64_t timestamp returning mach_absolute_time().
.TP
.B 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.
.SH OS X SPECIFIC ACTIONS
.TP
.B 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.
.SH OS X SPECIFIC OPTIONS
.TP
.B nojtanalysis (boolean)
The default behavior of the pid provider is to bail out when it detects a jump
table. This results in missing return probes. The nojtanalysis option disables
the jump table analysis. Please note that use of this option is discouraged,
inappropriately placed probes may cause data corruption or even crashes in the
target process.
.SH EXIT STATUS
The following exit values are returned by the \fIdtrace\fP utility:
.TP
.B 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.  \fIdtrace\fP returns 0 even if the specified tracing requests encountered errors or drops.
.TP
.B 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.
.TP
.B 2
Invalid command-line options or arguments were specified.
.SH SEE ALSO
\fIHow to Use Oracle Solaris DTrace from Oracle Solaris and OpenSolaris System\fP. Oracle, 2010. Available on the web at http://www.oracle.com/technetwork/server-storage/solaris10/solaris-dtrace-wp-167895.pdf
.br
\fISolaris Dynamic Tracing Guide\fP.  Sun Microsystems, 2005.  Available on the web at http://docs.oracle.com/cd/E19253-01/817-6223/