Provided by: systemtap-doc_0.0.20090214-1ubuntu1_all bug

NAME

       stapprobes - systemtap probe points

DESCRIPTION

       The  following sections enumerate the variety of probe points supported
       by the systemtap translator, and additional aliases defined by standard
       tapset scripts.

       The  general  probe  point  syntax  is  a dotted-symbol sequence.  This
       allows a breakdown of the event namespace into parts, somewhat like the
       Domain Name System does on the Internet.  Each component identifier may
       be parametrized by a string or number literal, with  a  syntax  like  a
       function call.  A component may include a "*" character, to expand to a
       set of matching probe points.  Probe aliases likewise expand  to  other
       probe  points.   Each  and  every  resulting  probe  point  is normally
       resolved to some low-level system  instrumentation  facility  (e.g.,  a
       kprobe  address,  marker,  or  a  timer  configuration),  otherwise the
       elaboration phase will fail.

       However, a probe point may be followed by a "?" character, to  indicate
       that  it  is  optional,  and that no error should result if it fails to
       resolve.  Optionalness passes down through all levels of alias/wildcard
       expansion.   Alternately,  a  probe  point  may  be  followed  by a "!"
       character, to indicate that it is both optional and sufficient.  (Think
       vaguely  of  the  prolog  cut  operator.)  If  it does resolve, then no
       further probe points in the same comma-separated list will be resolved.
       Therefore,  the  "!"   sufficiency  mark  only makes sense in a list of
       probe point alternatives.

       Additionally, a probe point may be followed by a "if (expr)" statement,
       in  order  to  enable/disable the probe point on-the-fly. With the "if"
       statement, if the "expr" is false when the  probe  point  is  hit,  the
       whole  probe  body  including alias’s body is skipped. The condition is
       stacked up through all levels of alias/wildcard expansion. So the final
       condition  becomes  the  logical-and  of  conditions  of  all  expanded
       alias/wildcard.

       These are all syntactically valid probe points:

              kernel.function("foo").return
              syscall(22)
              user.inode("/bin/vi").statement(0x2222)
              end
              syscall.*
              kernel.function("no_such_function") ?
              module("awol").function("no_such_function") !
              signal.*? if (switch)

       Probes may be broadly classified into "synchronous" and "asynchronous".
       A "synchronous" event is deemed to occur when any processor executes an
       instruction matched by the specification.  This gives  these  probes  a
       reference  point  (instruction address) from which more contextual data
       may  be  available.   Other  families  of   probe   points   refer   to
       "asynchronous" events such as timers/counters rolling over, where there
       is no  fixed  reference  point  that  is  related.   Each  probe  point
       specification   may   match  multiple  locations  (for  example,  using
       wildcards  or  aliases),  and  all  them  are  then  probed.   A  probe
       declaration  may  also  contain several comma-separated specifications,
       all of which are probed.

   BEGIN/END/ERROR
       The probe points begin and end are defined by the translator  to  refer
       to  the  time  of  session  startup  and  shutdown.   All "begin" probe
       handlers are run, in some sequence, during the startup of the  session.
       All  global  variables  will have been initialized prior to this point.
       All "end" probes are run, in some sequence, during the normal  shutdown
       of  a session, such as in the aftermath of an exit () function call, or
       an interruption from the user.   In  the  case  of  an  error-triggered
       shutdown,  "end"  probes  are  not  run.  There are no target variables
       available in either context.

       If the order of execution among "begin" or "end" probes is significant,
       then an optional sequence number may be provided:

              begin(N)
              end(N)

       The  number  N may be positive or negative.  The probe handlers are run
       in increasing order, and the  order  between  handlers  with  the  same
       sequence  number  is  unspecified.   When  "begin"  or  "end" are given
       without a sequence, they are effectively sequence zero.

       The error probe point is similar to the end  probe,  except  that  each
       such  probe  handler  run  when  the  session  ends  after  errors have
       occurred.  In such cases, "end" probes are skipped,  but  each  "error"
       prober  is still attempted.  This kind of probe can be used to clean up
       or emit a "final gasp".  It may also be numerically parametrized to set
       a sequence.

   NEVER
       The  probe  point  never is specially defined by the translator to mean
       "never".  Its probe handler is never run,  though  its  statements  are
       analyzed  for symbol / type correctness as usual.  This probe point may
       be useful in conjunction with optional probes.

   SYSCALL
       The syscall.*  aliases define  several  hundred  probes,  too  many  to
       summarize here.  They are:

              syscall.NAME
              syscall.NAME.return

       Generally, two probes are defined for each normal system call as listed
       in the syscalls(2) manual page, one  for  entry  and  one  for  return.
       Those  system  calls  that  never  return  do  not have a corresponding
       .return probe.

       Each probe alias defines a variety of variables. Looking at the  tapset
       source  code is the most reliable way.  Generally, each variable listed
       in the standard  manual  page  is  made  available  as  a  script-level
       variable,  so  syscall.open  exposes  filename,  flags,  and  mode.  In
       addition, a standard suite of variables is available at most aliases:

       argstr A pretty-printed form  of  the  entire  argument  list,  without
              parentheses.

       name   The name of the system call.

       retstr For  return  probes,  a  pretty-printed  form of the system-call
              result.

       Not all probe aliases obey all of  these  general  guidelines.   Please
       report any bothersome ones you encounter as a bug.

   TIMERS
       Intervals defined by the standard kernel "jiffies" timer may be used to
       trigger probe handlers asynchronously.  Two probe  point  variants  are
       supported by the translator:

              timer.jiffies(N)
              timer.jiffies(N).randomize(M)

       The  probe  handler  is  run  every N jiffies (a kernel-defined unit of
       time, typically between 1 and 60 ms).  If the "randomize" component  is
       given,  a  linearly  distributed  random value in the range [-M..+M] is
       added to N every time the  handler  is  run.   N  is  restricted  to  a
       reasonable  range  (1  to  around a million), and M is restricted to be
       smaller than N.  There are  no  target  variables  provided  in  either
       context.   It  is  possible for such probes to be run concurrently on a
       multi-processor computer.

       Alternatively, intervals may be specified in units of time.  There  are
       two probe point variants similar to the jiffies timer:

              timer.ms(N)
              timer.ms(N).randomize(M)

       Here,  N  and M are specified in milliseconds, but the full options for
       units  are  seconds  (s/sec),  milliseconds   (ms/msec),   microseconds
       (us/usec), nanoseconds (ns/nsec), and hertz (hz).  Randomization is not
       supported for hertz timers.

       The actual resolution of the timers depends on the target kernel.   For
       kernels  prior  to 2.6.17, timers are limited to jiffies resolution, so
       intervals are rounded  up  to  the  nearest  jiffies  interval.   After
       2.6.17,  the implementation uses hrtimers for tighter precision, though
       the actual resolution will be arch-dependent.  In either case,  if  the
       "randomize"  component is given, then the random value will be added to
       the interval before any rounding occurs.

       Profiling timers are also available to provide probes that  execute  on
       all  CPUs at the rate of the system tick (CONFIG_HZ).  This probe takes
       no parameters.

              timer.profile

       Full context information  of  the  interrupted  process  is  available,
       making this probe suitable for a time-based sampling profiler.

   DWARF
       This family of probe points uses symbolic debugging information for the
       target  kernel/module/program,  as   may   be   found   in   unstripped
       executables,  or the separate debuginfo packages.  They allow placement
       of probes logically into the execution path of the target  program,  by
       specifying  a  set  of  points  in  the  source or object code.  When a
       matching statement executes on any processor, the probe handler is  run
       in that context.

       Points  in  a kernel, which are identified by module, source file, line
       number, function name, or some combination of these.

       Here is a list  of  probe  point  families  currently  supported.   The
       .function  variant  places  a  probe  near  the  beginning of the named
       function, so that parameters are available as context  variables.   The
       .return  variant places a probe at the moment after the return from the
       named function, so the return  value  is  available  as  the  "$return"
       context  variable.   The  .inline  modifier  for  .function filters the
       results to include only instances  of  inlined  functions.   The  .call
       modifier  selects the opposite subset.  Inline functions do not have an
       identifiable return point, so  .return  is  not  supported  on  .inline
       probes.  The  .statement  variant  places  a  probe  at the exact spot,
       exposing those local variables that are visible there.

              kernel.function(PATTERN)
              kernel.function(PATTERN).call
              kernel.function(PATTERN).return
              kernel.function(PATTERN).inline
              kernel.function(PATTERN).label(LPATTERN)
              module(MPATTERN).function(PATTERN)
              module(MPATTERN).function(PATTERN).call
              module(MPATTERN).function(PATTERN).return
              module(MPATTERN).function(PATTERN).inline
              kernel.statement(PATTERN)
              kernel.statement(ADDRESS).absolute
              module(MPATTERN).statement(PATTERN)

       In the above list, MPATTERN stands for a string literal  that  aims  to
       identify the loaded kernel module of interest and LPATTERN stands for a
       source program label.  Both MPATTERN and LPATTERN may include  the  "*"
       "[]", and "?" wildcards.  PATTERN stands for a string literal that aims
       to identify a point in the program.  It is made up of three parts:

       ·   The first part is the name of a function, as would appear in the nm
           program’s  output.   This  part may use the "*" and "?" wildcarding
           operators to match multiple names.

       ·   The second part is optional and begins with the "@" character.   It
           is followed by the path to the source file containing the function,
           which may include a wildcard pattern, such as mm/slab*.  If it does
           not  match  as  is, an implicit "*/" is optionally added before the
           pattern, so that a script need only name the last few components of
           a possibly long source directory path.

       ·   Finally,  the  third  part  is  optional  if the file name part was
           given, and identifies the line number in the source  file  preceded
           by  a  ":"  or a "+".  The line number is assumed to be an absolute
           line number if preceded by a ":", or relative to the entry  of  the
           function  if  preceded by a "+".  All the lines in the function can
           be matched with ":*".  A range of lines x through y can be  matched
           with ":x-y".

       As  an  alternative,  PATTERN  may be a numeric constant, indicating an
       address.  Such an address may  be  found  from  symbol  tables  of  the
       appropriate  kernel / module object file.  It is verified against known
       statement code boundaries, and will be relocated for use at run time.

       In guru mode only, absolute kernel-space  addresses  may  be  specified
       with  the  ".absolute"  suffix.   Such an address is considered already
       relocated, as if it came from /proc/kallsyms, so it cannot  be  checked
       against statement/instruction boundaries.

       Some   of   the   source-level  context  variables,  such  as  function
       parameters, locals, globals visible in the  compilation  unit,  may  be
       visible  to  probe  handlers.   They  may  refer  to these variables by
       prefixing their name with "$"  within  the  scripts.   In  addition,  a
       special  syntax  allows  limited traversal of structures, pointers, and
       arrays.

       $var   refers to an in-scope variable "var".  If it’s  an  integer-like
              type,  it will be cast to a 64-bit int for systemtap script use.
              String-like pointers (char *) may be copied to systemtap  string
              values using the kernel_string or user_string functions.

       $var->field
              traversal  to a structure’s field.  The indirection operator may
              be repeated to follow more levels of pointers.

       $return
              is available in  return  probes  only  for  functions  that  are
              declared with a return value.

       $var[N]
              indexes into an array.  The index is given with a literal
              number.

       $$vars expands to a  character  string  that  is  equivalent  to
              sprintf("parm1=%x  ...  parmN=%x  var1=%x  ...  varN=%x",
              parm1, ..., parmN, var1, ..., varN)

       $$locals
              expands to a subset of $$vars for only local variables.

       $$parms
              expands  to  a  subset  of  $$vars  for   only   function
              parameters.

       $$return
              is  available  in  return  probes  only.  It expands to a
              string  that  is   equivalent   to   sprintf("return=%x",
              $return)  if  the  probed function has a return value, or
              else an empty string.

       For ".return" probes, context variables other than the "$return"
       value   itself   are   only  available  for  the  function  call
       parameters.  The expressions evaluate to the  entry-time  values
       of  those  variables,  since  that  is when a snapshot is taken.
       Other local variables are not generally accessible, since by the
       time  a  ".return"  probe  hits,  the  probed function will have
       already returned.

   USER-SPACE
       Early prototype support for user-space probing is  available  in
       the form of a non-symbolic probe point:
              process(PID).statement(ADDRESS).absolute
       is  analogous to kernel.statement(ADDRESS).absolute in that both
       use  raw  (unverified)  virtual   addresses   and   provide   no
       $variables.   The  target  PID parameter must identify a running
       process,  and  ADDRESS  should  identify  a  valid   instruction
       address.  All threads of that process will be probed.

       Additional  user-space  probing  is  available  in the following
       forms:
              process(PID).begin
              process("PATH").begin
              process.begin
              process(PID).thread.begin
              process("PATH").thread.begin
              process.thread.begin
              process(PID).end
              process("PATH").end
              process.end
              process(PID).thread.end
              process("PATH").thread.end
              process.thread.end
              process(PID).syscall
              process("PATH").syscall
              process.syscall
              process(PID).syscall.return
              process("PATH").syscall.return
              process.syscall.return
              process(PID).itrace
              process("PATH").itrace
              process("PATH").mark("LABEL")

       A .begin probe gets called when new process described by PID  or
       PATH gets created.  A .thread.begin probe gets called when a new
       thread described by PID or PATH gets created.  A .end probe gets
       called   when   process  described  by  PID  or  PATH  dies.   A
       .thread.end probe gets called when a thread described by PID  or
       PATH dies.  A .syscall probe gets called when a thread described
       by PID or PATH makes a system call.  The system call  number  is
       available  in  the  $syscall  context  variable, and the first 6
       arguments of the system call are available  in  the  $argN  (ex.
       $arg1,  $arg2,  ...)  context variable.  A .syscall.return probe
       gets called when a thread described by PID or PATH returns  from
       a  system  call.   The  system  call  number is available in the
       $syscall context variable, and the return value  of  the  system
       call  is  available  in the $return context variable.  A .itrace
       probe gets called for every single step of the process described
       by  PID  or  PATH.  A .mark probe gets called via a static probe
       which     is     defined     in     the      application      by
       STAP_PROBE1(handle,LABEL,arg1),  which is defined in sdt.h.  The
       handle is an application handle, LABEL corresponds to the  .mark
       argument,  and  arg1  is  the argument.  STAP_PROBE1 is used for
       probes with 1 argument, STAP_PROBE2 is used for  probes  with  2
       arguments,  and so on.  The arguments of the probe are available
       in the context variables $arg1, $arg2, ...   An  alternative  to
       using  the  STAP_PROBE  macros  is  to  use the dtrace script to
       create custom macros.

       Note that PATH names refer to executables that are searched  the
       same  way  shells  do: relative to the working directory if they
       contain a "/" character, otherwise in $PATH.  If a process probe
       is specified without a PID or PATH, all user threads are probed.

   PROCFS
       These    probe    points     allow     procfs     "files"     in
       /proc/systemtap/MODNAME to be created, read and written (MODNAME
       is the name of the systemtap module). The proc filesystem  is  a
       pseudo-filesystem  which  is used an an interface to kernel data
       structures.  There are four probe point  variants  supported  by
       the translator:

              procfs("PATH").read
              procfs("PATH").write
              procfs.read
              procfs.write

       PATH  is  the file name (relative to /proc/systemtap/MODNAME) to
       be created.  If no  PATH  is  specified  (as  in  the  last  two
       variants above), PATH defaults to "command".

       When    a    user    reads   /proc/systemtap/MODNAME/PATH,   the
       corresponding procfs read probe is triggered.  The  string  data
       to  be  read should be assigned to a variable named $value, like
       this:

              procfs("PATH").read { $value = "100\n" }

       When  a  user  writes  into  /proc/systemtap/MODNAME/PATH,   the
       corresponding  procfs  write  probe  is triggered.  The data the
       user wrote is available in the  string  variable  named  $value,
       like this:

              procfs("PATH").write { printf("user wrote: %s", $value) }

   MARKERS
       This  family  of probe points hooks up to static probing markers
       inserted into the kernel or modules.  These markers are  special
       macro calls inserted by kernel developers to make probing faster
       and more reliable than with DWARF-based probes.  Further,  DWARF
       debugging information is not required to probe markers.

       Marker  probe points begin with kernel.  The next part names the
       marker itself: mark("name").  The marker name string, which  may
       contain  the  usual  wildcard characters, is matched against the
       names given to the marker macros when the kernel  and/or  module
       was  compiled.     Optionally, you can specify format("format").
       Specifying  the  marker  format  string  allows   differentation
       between  two  markers  with  the  same name but different marker
       format strings.

       The handler associated with a marker-based probe  may  read  the
       optional parameters specified at the macro call site.  These are
       named $arg1 through $argNN, where NN is the number of parameters
       supplied  by the macro.  Number and string parameters are passed
       in a type-safe manner.

       The marker format string associated with a marker  is  available
       in  $format.   And  also  the  marker name string is avalable in
       $name.

   PERFORMANCE MONITORING HARDWARE
       The perfmon family  of  probe  points  is  used  to  access  the
       performance  monitoring hardware available in modern processors.
       This family of probes points needs the perfmon2 support  in  the
       kernel to access the performance monitoring hardware.

       Performance  monitor  hardware points begin with a perfmon.  The
       next part of the names the event being counted counter("event").
       The  event  names are processor implementation specific with the
       execption of the generic cycles and instructions  events,  which
       are  available  on all processors. This sets up a counter on the
       processor  to  count  the  number  of  events  occuring  on  the
       processor. For more details on the performance monitoring events
       available on a  specific  processor  use  the  command  perfmon2
       command:

              pfmon -l

       $counter
              is  a handle used in the body of the probe for operations
              involving the counter associated with the probe.

       read_counter
              is a function that is passed the handle for  the  perfmon
              probe and returns the current count for the event.

EXAMPLES

       Here  are  some  example  probe  points, defining the associated
       events.

       begin, end, end
              refers to the startup and normal shutdown of the session.
              In  this  case, the handler would run once during startup
              and twice during shutdown.

       timer.jiffies(1000).randomize(200)
              refers to  a  periodic  interrupt,  every  1000  +/-  200
              jiffies.

       kernel.function("*init*"), kernel.function("*exit*")
              refers  to  all kernel functions with "init" or "exit" in
              the name.

       kernel.function("*@kernel/sched.c:240")
              refers to any functions within the "kernel/sched.c"  file
              that span line 240.

       kernel.mark("getuid")
              refers  to  an  STAP_MARK(getuid,  ...) macro call in the
              kernel.

       module("usb*").function("*sync*").return
              refers to the moment of return from  all  functions  with
              "sync" in the name in any of the USB drivers.

       kernel.statement(0xc0044852)
              refers  to the first byte of the statement whose compiled
              instructions include the given address in the kernel.

       kernel.statement("*@kernel/sched.c:2917")
              refers   to   the   statement   of   line   2917   within
              "kernel/sched.c".

       kernel.statement("bio_init@fs/bio.c+3")
              refers   to  the  statement  at  line  bio_init+3  within
              "fs/bio.c".

       syscall.*.return
              refers to the group of probe aliases with any name in the
              third position

SEE ALSO

       stap(1),       stapprobes.iosched(5),      stapprobes.netdev(5),
       stapprobes.nfs(5), stapprobes.nfsd(5),  stapprobes.pagefault(5),
       stapprobes.process(5),   stapprobes.rpc(5),  stapprobes.scsi(5),
       stapprobes.signal(5),  stapprobes.socket(5),  stapprobes.tcp(5),
       stapprobes.udp(5), proc(5)