dtrace(1m) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨페이지이름
검색(S)

dtrace

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 infras-
     tructure that permits administrators, developers,  and  ser-
     vice personnel to concisely answer arbitrary questions about
     the behavior of the operating system and user programs.


     The Oracle Solaris 11.3 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  services provided by the DTrace facility, includ-
     ing:

         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  Oracle  Solaris  11.3  Dynamic
     Tracing Guide 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 program code specified on the com-
     mand line must be appropriately quoted to avoid  interpreta-
     tion 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  pro-
         gram using the 64-bit data model. These options are typ-
         ically 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  pro-
         grams  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) pro-
         duced 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 Oracle Solaris 11.3 Dynamic  Trac-
         ing Guide for more information about anonymous tracing.


     -A
         Generate driver.conf(4) directives for  anonymous  trac-
         ing.  This  option constructs a set of dtrace(7D) confi-
         guration file directives to enable the specified  probes
         for anonymous tracing and then exits. By default, dtrace
         attempts  to  store   the   directives   to   the   file
         etc/kernel/drv/dtrace.conf   .   You   can  modify  this
         behavior if you use the -o option to specify  an  alter-
         nate 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  comple-
         tion.  If more than one -c option is present on the com-
         mand 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 Oracle Solaris 11.3 Dynamic Trac-
         ing Guide 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 preproces-
         sor using the -D, -U, -I, and -H options. You can select
         the  degree  of C standard conformance 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 addi-
         tional 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 ena-
         bling 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  actually  executing  them  and   enabling   the
         corresponding instrumentation.


     -f[[provider:]module:]function[[predicate]action]]
         Specify function name to trace or list (-l option).  The
         corresponding  argument  can  include  any  of the probe
         description       forms        provider:module:function,
         module:function, or function. Unspecified probe descrip-
         tion fields are left blank and match any probes  regard-
         less  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 prefixed 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  pre-
         fixed with <=.


     -G
         Generate an ELF file containing an embedded DTrace  pro-
         gram.  The  DTrace  probes  specified in the program are
         saved inside of a relocatable ELF object  which  can  be
         linked  into  another  program.  If  the  -o  option  is
         present, the ELF file is saved using the pathname speci-
         fied  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 filename.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 directory 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  pro-
         grams.  The  specified  path  is added after the default
         library search path.


     -l
         List probes instead of enabling them. If the  -l  option
         is  specified,  dtrace  produces  a report of the probes
         matching the descriptions 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. Unspeci-
         fied 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 etc/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.

         Note that with successive invocations of dtrace with the
         -o option, dtrace does not overwrite, but rather appends
         to the output file.


     -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 Oracle Solaris 11.3 Dynamic
         Tracing Guide 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 suf-
         fixed 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  statements  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 instru-
         mentation 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 instrumenta-
         tion specified by the D program is enabled  and  tracing
         begins.


     -S
         Show D compiler intermediate code. The D  compiler  pro-
         duces  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 invocation.


     -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  speci-
         fied  D  programs. DTrace stability levels are explained
         in further detail in the  Oracle  Solaris  11.3  Dynamic
         Tracing Guide.

     -V
         Report the highest D programming interface version  sup-
         ported  by dtrace. The version information is printed to
         stdout and the dtrace command exits. Refer to the Oracle
         Solaris  11.3 Dynamic Tracing Guide for more information
         about DTrace versioning 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 Oracle
         Solaris 11.3 Dynamic Tracing Guide. 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  semantic  changes  required by ISO C. This is
              the default mode if -X is not specified. The prede-
              fined  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  compatibility  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  exten-
              sions,  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  preprocessor,  the  -Xa  and  -Xt  options  are
         equivalent from the perspective of D and both  are  pro-
         vided  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  pro-
                  grams are compiled)

             o    __amd64 (on x86 systems only when  64-bit  pro-
                  grams 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  hexade-
                  cimal,  mmm is the minor release value in hexa-
                  decimal, and uuu is the micro release value  in
                  hexadecimal.  Refer  to the Oracle Solaris 11.3
                  Dynamic  Tracing  Guide  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
     Oracle Solaris 11.3 Dynamic Tracing Guide.

Exit Status
     The following exit values are returned:

     0
          Successful completion.

          For D program requests, an exit status of  0  indicates
          that  programs  were successfully compiled, probes were
          successfully enabled, or anonymous state  was  success-
          fully 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 satisfied.


     2
          Invalid command line options or arguments  were  speci-
          fied.

Attributes
     See attributes(5) for descriptions of the  following  attri-
     butes:



     tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i)  ATTRI-
     BUTE   TYPEATTRIBUTE  VALUE  _  Availabilitysystem/dtrace  _
     Interface StabilitySee 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)


     Oracle Solaris 11.3 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 sys-
     tem  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.
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 1.0 CSS3