Manual Pages for UNIX Darwin command on man dtrace

DTRACE(1) DTRACE(1)

NAME

dtrace - generic front-end to the DTrace facility

SYNOPSIS

ddttrraaccee [-aaAACCeeFFhhHHllqqSSvvVVwwZZ] [-aarrcchh archname]

[-bb bufsz] [-cc fullPathToCommand] [-DD name[=def]]

[-II path] [-LL path] [-oo output] [-pp pid]

[-ss script] [-UU name] [-xx arg[=val]]

[-PP provider [[predicate] action]]

[-mm [provider:] module [[predicate] action]]

[-ff [[provider:] module:] function [[predicate] action]]

[-nn [[[provider:] module:] function:] name [[predicate] action]]

[-ii probe-id [[predicate] action]]

OOVVEERRVVIIEEWW

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. Users new to DTrace are encouraged to read: How To Use DTrace. Sun

Microsystems, 2005. Available on the web at http://www.sun.com/soft-

ware/solaris/howtoguides/dtracehowto.jsp

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 OOPPTTIIOONNSS

dtrace has the following options:

-aarrcchh archname

Set dtrace's target data model. See arch(1) for a list of cur-

rently supported architectures.

-aa Claim anonymous tracing state and display the traced data. You

can combine the -aa option with the -ee option to force dtrace to

exit immediately after consuming the anonymous tracing state rather than continuing to wait for new data.

-AA Generate a plist(5) of directives for anonymous tracing. If the

-AA option is specified, dtrace compiles any D programs specified

using the -ss 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/dtracedof.kext/Contents/Info.plist. This behavior can be

modified using the -oo option to specify an alternate output

file.

-bb Set principal trace buffer size. The trace buffer size can

include any of the size suffixes kk, mm, gg, or tt. If the buffer

space cannot be allocated, dtrace attempts to reduce the buffer

size or exit depending on the setting of the bufresize property.

-cc Run the specified command cmd and exit upon its completion. If

more than one -cc option is present on the command line, ddttrraaccee

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 -ss option through the $$ttaarrggeett

macro variable.

-CC Run the C preprocessor cpp over D programs before compiling

them. Options can be passed to the C preprocessor using the -DD,

-UU, -II, and -HH options. The degree of C standard conformance

can be selected using the -XX option. Refer to the description

of the -XX option for a description of the set of tokens defined

by the D compiler when invoking the C preprocessor.

-DD Define the specified name when invoking cpp (enabled using the

-CC option). If an equals sign (=) and additional value are

specified, the name is assigned the corresponding value. This

options passes the -DD option to each cpp invocation.

-ee Exit after compiling any requests and consuming anonymous trac-

ing state (-aa option) but prior to enabling any probes. This

option can be combined with the -aa 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.

-ff Specify function name to trace or list (-ll 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 -ff

argument can be suffiexed with an optional D probe clause. More

than one -ff option may be specified on the command-line at a

time.

-FF 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 <-.

-hh Generate a header file containing macro definitions for USDT

probes. If the -oo option is present, the header file is saved

using the pathname specified as the argument for this flag. If

the -oo 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.

-HH Print the pathnames of included files when invoking cpp (enabled

using the -CC option). This option passes the -HH option to each

cpp invocation, causing it to display the list of pathnames, one per line, to stderr.

-ii Specify probe identifier to trace or list (-ll option). Probe

IDs are specified using decimal integers as shown by dtrace -ll.

The -ii argument can be suffixed with an optional D probe clause.

More than one -ii option may be specified on the command-line at

a time.

-II Add the specified directory path to the search path for #include

files when invoking cpp (enabled using the -CC option). This

option passes the -II option to each cpp invocation. The speci-

fied directory is inserted into the search path ahead of the default directory list.

-ll List all probes matching probe specifications appearing in -ff,

-ii, -mm, -nn, or -PP options. No tracing is initiated for any

probes.

-LL 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.

-mm Specify module name to trace or list (-ll 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 -mm argument can be suffixed with an optional D

probe clause. More than one -mm option may be specified on the

command-line at a time.

-nn Specify probe name to trace or list (-ll 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 -nn argument can be suffixed with an optional D

probe clause. More than one -nn option may be specified on the

command-line at a time.

-oo Specify the output file for the -AA and -ll options, or for the

traced data. If the -AA option is present, and -oo is not

present, the default output file is /kernel/drv/dtrace.conf.

-pp Grab the specified process-ID pid, cache its symbol tables, and

exit upon its completion. If more than one -pp option is present

on the command line, ddttrraaccee 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 -ss option through the $$ttaarrggeett

macro variable.

-PP Specify provider name to trace or list (-ll 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 -PP argument can be suffixed with an optional D

probe clause. More than one -PP option may be specified on the

command-line at a time.

-qq 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 ttrraaccee(()) and pprriinnttff(()) will be displayed to stdout.

-ss Compile the specified D program source file. If the -ee option

is present, the program is compiled but no instrumentation is

enabled. If the -ll 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 -ee or -ll are present, the

instrumentation specified by the D program is enabled and trac-

ing begins.

-SS Show D compiler intermediate code. The D compiler will produce

a report of the intermediate code generated for each D program to stderr.

-UU Undefine the specified name when invoking cpp (enabled using the

-CC option). This option passes the -UU option to each cpp invo-

cation.

-vv Set verbose mode. If the -vv option is specified, dtrace pro-

duces a program stability report showing the minimum interface stability and dependency level for the specified D programs.

-VV Report the highest D programming interface version supported by

dtrace. The version informaion is printed to stdout and the

dtrace command exits.

-ww Allow destructive actions. D programs containing destructive

actions will fail to compile unless this flag is specified.

-xx 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 (=).

-ZZ Permit probe descriptions that match zero probes. If the -ZZ

option is not specified, dtrace will report an error and exit if

any probe descriptions specified in D program files (-ss option)

or on the command-line (-PP, -mm, -ff, -nn, or -ii options) contain

descriptions that do not match any known probes. OOPPEERRAANNDDSS

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 -ss 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. OOBBJJEECCTTIIVVEE CC PPRROOVVIIDDEERR 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:

oobbjjccpid:[class-name[(category-name)]]:[[+|-]method-name]:[name]

ppiidd The id number of the process.

ccllaassss-nnaammee

The name of the Objective C class.

ccaatteeggoorryy-nnaammee

The name of the category within the Objective C class.

mmeetthhoodd-nnaammee

The name of the Objective C method. nnaammee The name of the probe, eennttrryy, rreettuurrnn, or an integer instruction offset within the method. OOBBJJEECCTTIIVVEE CC PPRROOVVIIDDEERR EEXXAAMMPPLLEESS

oobbjjcc112233::NNSSSSttrriinngg::-**::eennttrryy

Every instance method of class NSString in process 123. oobbjjcc112233::NNSSSSttrriinngg((**))::::eennttrryy Every method on every category of class NSString in process 123. oobbjjcc112233::NNSSSSttrriinngg((ffoooo))::++**::eennttrryy Every class method in NSString's foo category in process 123.

oobbjjcc112233::::-**::eennttrryy

Every instance method in every class and category in process 123.

oobbjjcc112233::NNSSSSttrriinngg((ffoooo))::-ddeeaalllloocc::eennttrryy

The dealloc method in the foo category of class NSString in process 123. oobbjjcc112233::::mmeetthhoodd??wwiitthh??mmaannyy??ccoolloonnss::eennttrryy 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.) BBUUIILLDDIINNGG CCOODDEE CCOONNTTAAIINNIINNGG UUSSDDTT PPRROOBBEESS 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 EExxaammppllee provider with one probe, iinnccrreemmeenntt, 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 -hh

flag to do this.

ddttrraaccee -hh -ss eexxaammpplleePPrroovviiddeerr..dd

This will generate a header file named eexxaammpplleePPrroovviiddeerr..hh 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:

PROVIDERPROBENAME()

PROVIDERPROBENAMEENABLED()

In the Example provider, the increment probe becomes: EEXXAAMMPPLLEEIINNCCRREEMMEENNTT(()) EEXXAAMMPPLLEEIINNCCRREEMMEENNTTEENNAABBLLEEDD(()) 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 (EXAMPLEINCREMENTENABLED()) {

argument = /* Expensive argument calculation code here */;

EXAMPLEINCREMENT(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. EEXXIITT SSTTAATTUUSS

The following exit values are returned by the dtrace utility:

00 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.

11 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.

22 Invalid command-line options or arguments were specified.

http://www.sun.com/software/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)