1dtrace(1M) System Administration Commands dtrace(1M)
2
6 dtrace - DTrace dynamic tracing compiler and tracing utility
7
9 dtrace [-32 | -64] [-aACeFGHhlqSvVwZ] [-b bufsz] [-c cmd]
10 [-D name [=value]] [-I path] [-L path] [-o output]
11 [-s script] [-U name] [-x arg [=val]]
12 [-X a | c | s | t] [-p pid]
13 [-P provider [[predicate] action]]
14 [-m [provider:] module [[predicate] action]]
15 [-f [[provider:] module:] function [[predicate] action]]
16 [-n [[[provider:] module:] function:] name [[predicate] action]]
17 [-i probe-id [[predicate] action]]
18
21 DTrace is a comprehensive dynamic tracing framework for the Solaris
22 Operating System. DTrace provides a powerful infrastructure that per‐
23 mits administrators, developers, and service personnel to concisely
24 answer arbitrary questions about the behavior of the operating system
25 and user programs.
26 The Solaris Dynamic Tracing Guide describes how to use DTrace to
29 observe, debug, and tune system behavior. Refer to this book for a
30 detailed description of DTrace features, including the bundled DTrace
31 observability tools, instrumentation providers, and the D programming
32 language.
33 The dtrace command provides a generic interface to the essential ser‐
36 vices provided by the DTrace facility, including:
37 o Options that list the set of probes and providers currently
39 published by DTrace
40 o Options that enable probes directly using any of the probe
42 description specifiers (provider, module, function, name)
43 o Options that run the D compiler and compile one or more D
45 program files or programs written directly on the command
46 line
47 o Options that generate anonymous tracing programs
49 o Options that generate program stability reports
51 o Options that modify DTrace tracing and buffering behavior
53 and enable additional D compiler features
54 You can use dtrace to create D scripts by using it in a #! declaration
57 to create an interpreter file. You can also use dtrace to attempt to
58 compile D programs and determine their properties without actually
59 enabling tracing using the -e option. See OPTIONS. See the Solaris
60 Dynamic Tracing Guide for detailed examples of how to use the dtrace
61 utility to perform these tasks.
62
64 The arguments accepted by the -P, -m, -f, -n, and -i options can
65 include an optional D language predicate enclosed in slashes // and
66 optional D language action statement list enclosed in braces {}. D pro‐
67 gram code specified on the command line must be appropriately quoted to
68 avoid interpretation of meta-characters by the shell.
69 The following options are supported:
72 -32 | -64
74 The D compiler produces programs using the native data model of the
76 operating system kernel. You can use the isainfo -b command to
77 determine the current operating system data model. If the -32
78 option is specified, dtrace forces the D compiler to compile a D
79 program using the 32-bit data model. If the -64 option is speci‐
80 fied, dtrace forces the D compiler to compile a D program using the
81 64-bit data model. These options are typically not required as
82 dtrace selects the native data model as the default. The data model
83 affects the sizes of integer types and other language properties. D
84 programs compiled for either data model can be executed on both
85 32-bit and 64-bit kernels. The -32 and -64 options also determine
86 the ELF file format (ELF32 or ELF64) produced by the -G option.
87 -a
90 Claim anonymous tracing state and display the traced data. You can
92 combine the -a option with the -e option to force dtrace to exit
93 immediately after consuming the anonymous tracing state rather than
94 continuing to wait for new data. See the Solaris Dynamic Tracing
95 Guide for more information about anonymous tracing.
96 -A
99 Generate driver.conf(4) directives for anonymous tracing. This
101 option constructs a set of dtrace(7D) configuration file directives
102 to enable the specified probes for anonymous tracing and then
103 exits. By default, dtrace attempts to store the directives to the
104 file /kernel/drv/dtrace.conf. You can modify this behavior if you
105 use the -o option to specify an alternate output file.
106 -b bufsz
109 Set principal trace buffer size (bufsz). The trace buffer size can
111 include any of the size suffixes k, m, g, or t. If the buffer space
112 cannot be allocated, dtrace attempts to reduce the buffer size or
113 exit depending on the setting of the bufresize property.
114 -c cmd
117 Run the specified command cmd and exit upon its completion. If more
119 than one -c option is present on the command line, dtrace exits
120 when all commands have exited, reporting the exit status for each
121 child process as it terminates. The process-ID of the first command
122 is made available to any D programs specified on the command line
123 or using the -s option through the $target macro variable. Refer to
124 the Solaris Dynamic Tracing Guide for more information on macro
125 variables.
126 -C
129 Run the C preprocessor cpp(1) over D programs before compiling
131 them. You can pass options to the C preprocessor using the -D, -U,
132 -I, and -H options. You can select the degree of C standard confor‐
133 mance if you use the -X option. For a description of the set of
134 tokens defined by the D compiler when invoking the C preprocessor,
135 see -X.
136 -D name [=value]
139 Define name when invoking cpp(1) (enabled using the -C option). If
141 you specify the equals sign (=) and additional value, the name is
142 assigned the corresponding value. This option passes the -D option
143 to each cpp invocation.
144 -e
147 Exit after compiling any requests and consuming anonymous tracing
149 state (-a option) but prior to enabling any probes. You can combine
150 this option with the -a option to print anonymous tracing data and
151 exit. You can also combine this option with D compiler options.
152 This combination verifies that the programs compile without actu‐
153 ally executing them and enabling the corresponding instrumentation.
154 -f[[provider:]module:]function[[predicate]action]]
157 Specify function name to trace or list (-l option). The correspond‐
159 ing argument can include any of the probe description forms
160 provider:module:function, module:function, or function. Unspecified
161 probe description fields are left blank and match any probes
162 regardless of the values in those fields. If no qualifiers other
163 than function are specified in the description, all probes with the
164 corresponding function are matched. The -f argument can be suffixed
165 with an optional D probe clause. You can specify more than one -f
166 option on the command line at a time.
167 -F
170 Coalesce trace output by identifying function entry and return.
172 Function entry probe reports are indented and their output is pre‐
173 fixed with ->. Function return probe reports are unindented and
174 their output is prefixed with <-. System call entry probe reports
175 are indented and their output is prefixed with =>. System call
176 return probe reports are unindented and their output is prefixed
177 with <=.
178 -G
181 Generate an ELF file containing an embedded DTrace program. The
183 DTrace probes specified in the program are saved inside of a relo‐
184 catable ELF object which can be linked into another program. If the
185 -o option is present, the ELF file is saved using the pathname
186 specified as the argument for this operand. If the -o option is not
187 present and the DTrace program is contained with a file whose name
188 is filename.d, then the ELF file is saved using the name file‐
189 name.o. Otherwise the ELF file is saved using the name d.out.
190 -H
193 Print the pathnames of included files when invoking cpp(1) (enabled
195 using the -C option). This option passes the -H option to each cpp
196 invocation, causing it to display the list of pathnames, one for
197 each line, to stderr.
198 -h
201 Generate a header file containing macros that correspond to probes
203 in the specified provider definitions. This option should be used
204 to generate a header file that is included by other source files
205 for later use with the -G option. If the -o option is present, the
206 header file is saved using the pathname specified as the argument
207 for that option. If the -o option is not present and the DTrace
208 program is contained with a file whose name is filename.d, then the
209 header file is saved using the name filename.h.
210 -i probe-id[[predicate] action]
213 Specify probe identifier (probe-id) to trace or list (-l option).
215 You can specify probe IDs using decimal integers as shown by dtrace
216 -l. The -i argument can be suffixed with an optional D probe
217 clause. You can specify more than one -i option at a time.
218 -I path
221 Add the specified directory path to the search path for #include
223 files when invoking cpp(1) (enabled using the -C option). This
224 option passes the -I option to each cpp invocation. The specified
225 path is inserted into the search path ahead of the default direc‐
226 tory list.
227 -L path
230 Add the specified directory path to the search path for DTrace
232 libraries. DTrace libraries are used to contain common definitions
233 that can be used when writing D programs. The specified path is
234 added after the default library search path.
235 -l
238 List probes instead of enabling them. If the -l option is speci‐
240 fied, dtrace produces a report of the probes matching the descrip‐
241 tions given using the -P, -m, -f, -n, -i, and -s options. If none
242 of these options are specified, this option lists all probes.
243 -m [[provider:] module: [[predicate] action]]
246 Specify module name to trace or list (-l option). The corresponding
248 argument can include any of the probe description forms
249 provider:module or module. Unspecified probe description fields are
250 left blank and match any probes regardless of the values in those
251 fields. If no qualifiers other than module are specified in the
252 description, all probes with a corresponding module are matched.
253 The -m argument can be suffixed with an optional D probe clause.
254 More than one -m option can be specified on the command line at a
255 time.
256 -n [[[provider:] module:] function:] name [[predicate] action]
259 Specify probe name to trace or list (-l option). The corresponding
261 argument can include any of the probe description forms
262 provider:module:function:name, module:function:name, function:name,
263 or name. Unspecified probe description fields are left blank and
264 match any probes regardless of the values in those fields. If no
265 qualifiers other than name are specified in the description, all
266 probes with a corresponding name are matched. The -n argument can
267 be suffixed with an optional D probe clause. More than one -n
268 option can be specified on the command line at a time.
269 -o output
272 Specify the output file for the -A , -G, -h, and -l options, or
274 for the traced data itself. If the -A option is present and -o is
275 not present, the default output file is /kernel/drv/dtrace.conf. If
276 the -G option is present and the -s option's argument is of the
277 form filename.d and -o is not present, the default output file is
278 filename.o. Otherwise the default output file is d.out.
279 -p pid
282 Grab the specified process-ID pid, cache its symbol tables, and
284 exit upon its completion. If more than one -p option is present on
285 the command line, dtrace exits when all commands have exited,
286 reporting the exit status for each process as it terminates. The
287 first process-ID is made available to any D programs specified on
288 the command line or using the -s option through the $target macro
289 variable. Refer to the Solaris Dynamic Tracing Guide for more
290 information on macro variables.
291 -P provider [[predicate] action]
294 Specify provider name to trace or list (-l option). The remaining
296 probe description fields module, function, and name are left blank
297 and match any probes regardless of the values in those fields. The
298 -P argument can be suffixed with an optional D probe clause. You
299 can specify more than one -P option on the command line at a time.
300 -q
303 Set quiet mode. dtrace suppresses messages such as the number of
305 probes matched by the specified options and D programs and does not
306 print column headers, the CPU ID, the probe ID, or insert newlines
307 into the output. Only data traced and formatted by D program state‐
308 ments such as trace() and printf() is displayed to stdout.
309 -s
312 Compile the specified D program source file. If the -e option is
314 present, the program is compiled but instrumentation is not
315 enabled. If the -l option is present, the program is compiled and
316 the set of probes matched by it is listed, but instrumentation is
317 not enabled. If none of -e, -l, -G, or -A are present, the instru‐
318 mentation specified by the D program is enabled and tracing begins.
319 -S
322 Show D compiler intermediate code. The D compiler produces a report
324 of the intermediate code generated for each D program to stderr.
325 -U name
328 Undefine the specified name when invoking cpp(1) (enabled using the
330 -C option). This option passes the -U option to each cpp invoca‐
331 tion.
332 -v
335 Set verbose mode. If the -v option is specified, dtrace produces a
337 program stability report showing the minimum interface stability
338 and dependency level for the specified D programs. DTrace stability
339 levels are explained in further detail in the Solaris Dynamic Trac‐
340 ing Guide.
341 -V
344 Report the highest D programming interface version supported by
346 dtrace. The version information is printed to stdout and the dtrace
347 command exits. Refer to the Solaris Dynamic Tracing Guide for more
348 information about DTrace versioning features.
349 -w
352 Permit destructive actions in D programs specified using the -s,
354 -P, -m, -f, -n, or -i options. If the -w option is not specified,
355 dtrace does not permit the compilation or enabling of a D program
356 that contains destructive actions.
357 -x arg [=val]
360 Enable or modify a DTrace runtime option or D compiler option. The
362 list of options is found in the Solaris Dynamic Tracing Guide.
363 Boolean options are enabled by specifying their name. Options with
364 values are set by separating the option name and value with an
365 equals sign (=).
366 -X a | c | s | t
369 Specify the degree of conformance to the ISO C standard that should
371 be selected when invoking cpp(1) (enabled using the -C option). The
372 -X option argument affects the value and presence of the __STDC__
373 macro depending upon the value of the argument letter.
374 The -X option supports the following arguments:
376 a Default. ISO C plus K&R compatibility extensions, with seman‐
378 tic changes required by ISO C. This is the default mode if -X
379 is not specified. The predefined macro __STDC__ has a value of
380 0 when cpp is invoked in conjunction with the -Xa option.
381 c Conformance. Strictly conformant ISO C, without K&R C compati‐
384 bility extensions. The predefined macro __STDC__ has a value
385 of 1 when cpp is invoked in conjunction with the -Xc option.
386 s K&R C only. The macro __STDC__ is not defined when cpp is
389 invoked in conjunction with the -Xs option.
390 t Transition. ISO C plus K&R C compatibility extensions, without
393 semantic changes required by ISO C. The predefined macro
394 __STDC__ has a value of 0 when cpp is invoked in conjunction
395 with the -Xt option.
396 As the -X option only affects how the D compiler invokes the C pre‐
398 processor, the -Xa and -Xt options are equivalent from the perspec‐
399 tive of D and both are provided only to ease re-use of settings
400 from a C build environment.
401 Regardless of the -X mode, the following additional C preprocessor
403 definitions are always specified and valid in all modes:
404 o __sun
406 o __unix
408 o __SVR4
410 o __sparc (on SPARC systems only)
412 o __sparcv9 (on SPARC systems only when 64-bit programs
414 are compiled)
415 o __i386 (on x86 systems only when 32-bit programs are
417 compiled)
418 o __amd64 (on x86 systems only when 64-bit programs are
420 compiled)
421 o __`uname -s`_`uname -r` (for example, __SunOS_5_10)
423 o __SUNW_D=1
425 o __SUNW_D_VERSION=0xMMmmmuuu
427 Where MM is the major release value in hexadecimal, mmm
429 is the minor release value in hexadecimal, and uuu is
430 the micro release value in hexadecimal. Refer to the
431 Solaris Dynamic Tracing Guide for more information about
432 DTrace versioning.
433 -Z
436 Permit probe descriptions that match zero probes. If the -Z option
438 is not specified, dtrace reports an error and exits if any probe
439 descriptions specified in D program files (-s option) or on the
440 command line (-P, -m, -f, -n, or -i options) contain descriptions
441 that do not match any known probes.
442
445 You can specify zero or more additional arguments on the dtrace command
446 line to define a set of macro variables ($1, $2, and so forth). The
447 additional arguments can be used in D programs specified using the -s
448 option or on the command line. The use of macro variables is described
449 further in the Solaris Dynamic Tracing Guide.
450
452 The following exit values are returned:
453 0 Successful completion.
455 For D program requests, an exit status of 0 indicates that pro‐
457 grams were successfully compiled, probes were successfully
458 enabled, or anonymous state was successfully retrieved. dtrace
459 returns 0 even if the specified tracing requests encountered
460 errors or drops.
461 1 An error occurred.
464 For D program requests, an exit status of 1 indicates that program
466 compilation failed or that the specified request could not be sat‐
467 isfied.
468 2 Invalid command line options or arguments were specified.
471
474 See attributes(5) for descriptions of the following attributes:
475 ┌─────────────────────────────┬─────────────────────────────┐
480 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
481 ├─────────────────────────────┼─────────────────────────────┤
482 │Availability │SUNWdtrc │
483 ├─────────────────────────────┼─────────────────────────────┤
484 │Interface Stability │See below. │
485 └─────────────────────────────┴─────────────────────────────┘
486 The command-line syntax is Committed. The human-readable output is
489 Uncommitted.
490
492 cpp(1), isainfo(1), ssh(1), libdtrace(3LIB), driver.conf(4),
493 attributes(5), dtrace(7D)
494 Solaris Dynamic Tracing Guide
497
499 When using the -p flag, dtrace stops the target processes while it is
500 inspecting them and reporting results. A process can do nothing while
501 it is stopped. This means that, if , for example, the X server is
502 inspected by dtrace running in a window under the X server's control,
503 the whole window system can become deadlocked, because the proc tool
504 would be attempting to display its results to a window that cannot be
505 refreshed. In such a case, logging in from another system using ssh(1)
506 and killing the offending proc tool clears the deadlock.
507SunOS 5.11 4 Aug 2009 dtrace(1M)