manpagez: man pages & more
man dtrace(1)
Home | html | info | man
dtrace(1)                                                            dtrace(1)




NAME

       dtrace - generic front-end to the DTrace facility


SYNOPSIS

       dtrace [-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:

       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


OPTIONS

       dtrace 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 ACTIONS

       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.


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)

Mac OS X 10.9 - Generated Sat Oct 12 10:49:53 CDT 2013
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.