dtrace man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

dtrace(1M)		System Administration Commands		    dtrace(1M)

NAME
       dtrace - DTrace dynamic tracing compiler and tracing utility

SYNOPSIS
       dtrace [-32 | -64] [-aACeFGHhlqSvVwZ] [-b bufsz] [-c cmd]
	    [-D name [=value]] [-I path] [-L path] [-o output]
	    [-s script] [-U name] [-x arg [=val]]
	    [-X a | c | s | t] [-p pid]
	    [-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]]

DESCRIPTION
       DTrace  is  a  comprehensive  dynamic tracing framework for the Solaris
       Operating System. DTrace provides a powerful infrastructure  that  per‐
       mits  administrators,  developers,  and	service personnel to concisely
       answer arbitrary questions about the behavior of the  operating	system
       and user programs.

       The  Solaris  Dynamic  Tracing  Guide  describes	 how  to use DTrace to
       observe, debug, and tune system behavior. Refer	to  this  book	for  a
       detailed	 description  of DTrace features, including the bundled DTrace
       observability tools, instrumentation providers, and the	D  programming
       language.

       The  dtrace  command provides a generic interface to the essential ser‐
       vices provided by the DTrace facility, including:

	   o	  Options that list the set of probes and providers  currently
		  published by DTrace

	   o	  Options  that	 enable probes directly using any of the probe
		  description specifiers (provider, module, function, name)

	   o	  Options that run the D compiler and compile one  or  more  D
		  program  files  or  programs written directly on the command
		  line

	   o	  Options that generate anonymous tracing programs

	   o	  Options that generate program stability reports

	   o	  Options that modify DTrace tracing  and  buffering  behavior
		  and enable additional D compiler features

       You  can use dtrace to create D scripts by using it in a #! declaration
       to create an interpreter file. You can also use dtrace  to  attempt  to
       compile	D  programs  and  determine  their properties without actually
       enabling tracing using  the  -e	option.	 See  OPTIONS.	See  the   for
       detailed	 examples  of  how  to use the dtrace utility to perform these
       tasks.

OPTIONS
       The arguments accepted by the -P,  -m,  -f,  -n,	 and  -i  options  can
       include	an  optional  D	 language predicate enclosed in slashes // and
       optional D language action statement list enclosed in braces {}. D pro‐
       gram code specified on the command line must be appropriately quoted to
       avoid interpretation of meta-characters by the shell.

       The following options are supported:

       -32 | -64

	   The D compiler produces programs using the native data model of the
	   operating  system  kernel.  You  can	 use the isainfo -b command to
	   determine the current operating  system  data  model.  If  the  -32
	   option  is  specified,  dtrace forces the D compiler to compile a D
	   program using the 32-bit data model. If the -64  option  is	speci‐
	   fied, dtrace forces the D compiler to compile a D program using the
	   64-bit data model. These options  are  typically  not  required  as
	   dtrace selects the native data model as the default. The data model
	   affects the sizes of integer types and other language properties. D
	   programs  compiled  for  either  data model can be executed on both
	   32-bit and 64-bit kernels. The -32 and -64 options  also  determine
	   the ELF file format (ELF32 or ELF64) produced by the -G option.

       -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. See the  Solaris  Dynamic  Tracing
	   Guide for more information about anonymous tracing.

       -A

	   Generate  driver.conf(4)  directives	 for  anonymous	 tracing. This
	   option constructs a set of dtrace(7D) configuration file directives
	   to  enable  the  specified  probes  for  anonymous tracing and then
	   exits. By default, dtrace attempts to store the directives  to  the
	   file	 /kernel/drv/dtrace.conf.  You can modify this behavior if you
	   use the -o option to specify an alternate output file.

       -b bufsz

	   Set principal trace buffer size (bufsz). 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 cmd

	   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. Refer to
	   the	for more information on macro variables.

       -C

	   Run	the  C	preprocessor  cpp(1)  over D programs before compiling
	   them. You can pass options to the C preprocessor using the -D,  -U,
	   -I, and -H options. You can select the degree of C standard confor‐
	   mance if you use the -X option. For a description  of  the  set  of
	   tokens  defined by the D compiler when invoking the C preprocessor,
	   see -X.

       -D name [=value]

	   Define name when invoking cpp(1) (enabled using the -C option).  If
	   you	specify	 the equals sign (=) and additional value, the name is
	   assigned the corresponding value. This option 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. You can combine
	   this	 option with the -a option to print anonymous tracing data and
	   exit. You can also combine this option  with	 D  compiler  options.
	   This	 combination  verifies that the programs compile without actu‐
	   ally executing them and enabling the corresponding instrumentation.

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

	   Specify function name to trace or list (-l option). The correspond‐
	   ing	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 description, all probes with the
	   corresponding function are matched. The -f argument can be suffixed
	   with	 an  optional D probe clause. You can specify more than one -f
	   option 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 pre‐
	   fixed with ->. Function return probe	 reports  are  unindented  and
	   their  output  is prefixed with <-. System call entry probe reports
	   are indented and their output is  prefixed  with  =>.  System  call
	   return  probe  reports  are unindented and their output is prefixed
	   with <=.

       -G

	   Generate an ELF file containing an  embedded	 DTrace	 program.  The
	   DTrace  probes specified in the program are saved inside of a relo‐
	   catable ELF object which can be linked into another program. If the
	   -o  option  is  present,  the  ELF file is saved using the pathname
	   specified as the argument for this operand. If the -o option is not
	   present  and the DTrace program is contained with a file whose name
	   is filename.d, then the ELF file is	saved  using  the  name	 file‐
	   name.o. Otherwise the ELF file is saved using the name d.out.

       -H

	   Print the pathnames of included files when invoking cpp(1) (enabled
	   using the -C option). This option passes the -H option to each  cpp
	   invocation,	causing	 it  to display the list of pathnames, one for
	   each line, to stderr.

       -h

	   Generate a header file containing macros that correspond to	probes
	   in  the  specified provider definitions. This option should be used
	   to generate a header file that is included by  other	 source	 files
	   for	later use with the -G option. If the -o option is present, the
	   header file is saved using the pathname specified as	 the  argument
	   for	that  option.  If  the -o option is not present and the DTrace
	   program is contained with a file whose name is filename.d, then the
	   header file is saved using the name filename.h.

       -i probe-id[[predicate] action]

	   Specify  probe  identifier (probe-id) to trace or list (-l option).
	   You can specify probe IDs using decimal integers as shown by dtrace
	   -l.	The  -i	 argument  can	be  suffixed  with an optional D probe
	   clause. You can specify more than one -i option at a time.

       -I path

	   Add the specified directory path to the search  path	 for  #include
	   files  when	invoking  cpp(1)  (enabled  using the -C option). This
	   option passes the -I option to each cpp invocation.	The  specified
	   path	 is  inserted into the search path ahead of the default direc‐
	   tory list.

       -L path

	   Add the specified directory path to	the  search  path  for	DTrace
	   libraries.  DTrace libraries are used to contain common definitions
	   that can be used when writing D programs.  The  specified  path  is
	   added after the default library search path.

       -l

	   List	 probes	 instead  of enabling them. If the -l option is speci‐
	   fied, dtrace produces a report of the probes matching the  descrip‐
	   tions  given	 using the -P, -m, -f, -n, -i, and -s options. If none
	   of these options are specified, this option lists all probes.

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

	   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 can be specified on the command line at a
	   time.

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

	   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, function: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 can be specified on the command line at a time.

       -o output

	   Specify the output file for the -A , -G,  -h, and  -l  options,  or
	   for	the  traced data itself. If the -A option is present and -o is
	   not present, the default output file is /kernel/drv/dtrace.conf. If
	   the	-G  option  is	present and the -s option's argument is of the
	   form filename.d and -o is not present, the default output  file  is
	   filename.o. Otherwise the default output file is d.out.

       -p pid

	   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 specified on
	   the command line or using the -s option through the	$target	 macro
	   variable. Refer to the  for more information on macro variables.

       -P provider [[predicate] action]

	   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.  You
	   can specify more than one -P option on the command line at a time.

       -q

	   Set	quiet  mode.  dtrace suppresses messages such as the number of
	   probes matched by the specified options and D programs and does not
	   print  column headers, the CPU ID, the probe ID, or insert newlines
	   into the output. Only data traced and formatted by D program state‐
	   ments such as trace() and printf() is displayed to stdout.

       -s

	   Compile  the	 specified  D program source file. If the -e option is
	   present,  the  program  is  compiled	 but  instrumentation  is  not
	   enabled.  If	 the -l option is present, the program is compiled and
	   the set of probes matched by it is listed, but  instrumentation  is
	   not	enabled. If none of -e, -l, -G, or -A are present, the instru‐
	   mentation specified by the D program is enabled and tracing begins.

       -S

	   Show D compiler intermediate code. The D compiler produces a report
	   of the intermediate code generated for each D program to stderr.

       -U name

	   Undefine the specified name when invoking cpp(1) (enabled using the
	   -C option). This option passes the -U option to  each  cpp  invoca‐
	   tion.

       -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. DTrace stability
	   levels are explained in further detail in the .

       -V

	   Report the highest D programming  interface	version	 supported  by
	   dtrace. The version information is printed to stdout and the dtrace
	   command exits. Refer to the	for more information about DTrace ver‐
	   sioning features.

       -w

	   Permit  destructive	actions	 in D programs specified using the -s,
	   -P, -m, -f, -n, or -i options. If the -w option is  not  specified,
	   dtrace  does	 not permit the compilation or enabling of a D program
	   that contains destructive actions.

       -x arg [=val]

	   Enable or modify a DTrace runtime option or D compiler option.  The
	   list	 of  options  is found in the . Boolean options are enabled by
	   specifying their name. Options with values are  set	by  separating
	   the option name and value with an equals sign (=).

       -X a | c | s | t

	   Specify the degree of conformance to the ISO C standard that should
	   be selected when invoking cpp(1) (enabled using the -C option). The
	   -X  option  argument affects the value and presence of the __STDC__
	   macro depending upon the value of the argument letter.

	   The -X option supports the following arguments:

	   a	Default. ISO C plus K&R compatibility extensions, with	seman‐
		tic  changes required by ISO C. This is the default mode if -X
		is not specified. The predefined macro __STDC__ has a value of
		0 when cpp is invoked in conjunction with the -Xa option.

	   c	Conformance. Strictly conformant ISO C, without K&R C compati‐
		bility extensions. The predefined macro __STDC__ has  a	 value
		of 1 when cpp is invoked in conjunction with the -Xc option.

	   s	K&R  C	only.  The  macro  __STDC__ is not defined when cpp is
		invoked in conjunction with the -Xs option.

	   t	Transition. ISO C plus K&R C compatibility extensions, without
		semantic  changes  required  by	 ISO  C.  The predefined macro
		__STDC__ has a value of 0 when cpp is invoked  in  conjunction
		with the -Xt option.

	   As the -X option only affects how the D compiler invokes the C pre‐
	   processor, the -Xa and -Xt options are equivalent from the perspec‐
	   tive	 of  D	and  both are provided only to ease re-use of settings
	   from a C build environment.

	   Regardless of the -X mode, the following additional C  preprocessor
	   definitions are always specified and valid in all modes:

	       o      __sun

	       o      __unix

	       o      __SVR4

	       o      __sparc (on SPARC systems only)

	       o      __sparcv9	 (on  SPARC  systems only when 64-bit programs
		      are compiled)

	       o      __i386 (on x86 systems only  when	 32-bit	 programs  are
		      compiled)

	       o      __amd64  (on  x86	 systems only when 64-bit programs are
		      compiled)

	       o      __`uname -s`_`uname -r` (for example, __SunOS_5_10)

	       o      __SUNW_D=1

	       o      __SUNW_D_VERSION=0xMMmmmuuu

		      Where MM is the major release value in hexadecimal,  mmm
		      is  the  minor  release value in hexadecimal, and uuu is
		      the micro release value in  hexadecimal.	Refer  to  the
		      for more information about DTrace versioning.

       -Z

	   Permit  probe descriptions that match zero probes. If the -Z option
	   is not specified, dtrace reports an error and exits	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
       You can specify zero or more additional arguments on the dtrace command
       line to define a set of macro variables ($1, $2,	 and  so  forth).  The
       additional  arguments  can be used in D programs specified using the -s
       option or on the command line. The use of macro variables is  described
       further in the .

EXIT STATUS
       The following exit values are returned:

       0    Successful completion.

	    For	 D  program  requests, an exit status of 0 indicates that pro‐
	    grams  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    An error occurred.

	    For D program requests, an exit status of 1 indicates that program
	    compilation failed or that the specified request could not be sat‐
	    isfied.

       2    Invalid command line options or arguments were specified.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWdtrc			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │See below.		   │
       └─────────────────────────────┴─────────────────────────────┘

       The  command-line  syntax  is  Committed.  The human-readable output is
       Uncommitted.

SEE ALSO
       cpp(1),	 isainfo(1),	ssh(1),	   libdtrace(3LIB),    driver.conf(4),
       attributes(5), dtrace(7D)

       Solaris Dynamic Tracing Guide

USAGE
       When  using  the -p flag, dtrace stops the target processes while it is
       inspecting them and reporting results. A process can do	nothing	 while
       it  is  stopped.	 This  means  that,  if , for example, the X server is
       inspected by dtrace running in a window under the X  server's  control,
       the  whole  window  system can become deadlocked, because the proc tool
       would be attempting to display its results to a window that  cannot  be
       refreshed.  In such a case, logging in from another system using ssh(1)
       and killing the offending proc tool clears the deadlock.

SunOS 5.10			  3 Feb 2009			    dtrace(1M)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net