DTRACY(1)                                               DTRACY(1)

     NAME
          dtracy - dynamic tracing language

     SYNOPSIS
          dtracy [ -d ] prog

     DESCRIPTION
          Dtracy is a language for dynamic tracing of the kernel.
          Essentially, it allows the user to define small programs in
          kernel space that are triggered by certain events (known as
          probes) upon which they are executed.

          Dtracy uses an awk(1) inspired syntax.  A dtracy program is
          a series of statements of one of the following forms

               probes { actions }
               probes if predicate { actions }

          Probes is a comma-separated list of probes, such as
          sys:pwrite:entry.  Each probe name consists of any number of
          parts separated by :.  If a part is omitted (e.g.
          qsys::entry), it matches all probes that match the remaining
          parts.  If the probe name is enclosed in quotation marks,
          the wildcards * and ? are available, e.g. "sys:*stat:entry".

          Predicate, if specified, is an expression that must evaluate
          to a non-zero value for the actions to be executed.

          Actions is a semicolon-separated list of statements of one
          of the following forms:

               expr
               print a, b, ...
               printf "fmt", a, b, ...
               @name[index] = aggregation-expr

          Expressions follow C syntax and semantics and all C opera-
          tors (including casts) are supported.  Available integer
          types are u8, u16, u32, u64, s8, s16, s32 and s64; they cor-
          respond to the C types u8int, etc.  Additionally, a string
          type string is available.

          Expressions can use the following variables

          probe              name of the probe that was triggered
          pid                PID of the process triggering the probe
          arg0, arg1, ...    for a syscall probe, the syscall argu-
                             ments (cast to s64)
          time               timestamp when the probe was triggered
          machno             CPU number on which the probe was

     DTRACY(1)                                               DTRACY(1)

                             triggered

          Print prints all its arguments, separated by spaces and fol-
          lowed by a newline.  Printf prints its arguments using a
          format string with print(1) syntax.  However, there is no
          need to specify the argument size, e.g. %d works for all
          integer types.

          Statements of the form @name[index] = aggregation-expr col-
          lect statistics using a data structure referred to as an
          aggregation.  Each time the statement is evaluated adds
          another datapoint to the aggregation, which will be printed
          in tabular form when dtracy finishes.  Index is effectively
          a label for the datapoint; statistics are evaluated over all
          datapoints of the same index.

          Aggregation-expr specifies the type of statistic to be col-
          lected.  Available options are

          count()      number of datapoints
          avg(expr)    average
          sum(expr)    sum
          min(expr)    minimum
          max(expr)    maximum
          std(expr)    average and standard deviation

     EXAMPLES
               sys:: { print probe, pid, arg0, arg1 }

          The world's worst syscall tracer.

               sys:pread:entry if pid == 42 { printf "time %d, fd %d\n", time, arg0 }

          Every time the process with PID 42 executes pread(2), write
          down the timestamp and the file descriptor used.

               sys:open:entry { print (string)arg0 }

          Print the names of files as they are being opened.

               sys:pread:entry { @size[pid] = avg(arg2) }

          Determine the average pread buffer size for each process.

     SOURCE
          /sys/src/cmd/dtracy

     BUGS
          Yes.

     HISTORY
          Dtracy appeared in 9front in November, 2018.

     DTRACY(1)                                               DTRACY(1)