plan9fox/sys/man/1/dtracy

.TH DTRACY 1
.SH NAME
dtracy \- dynamic tracing language
.SH SYNOPSIS
.B dtracy
[
.B -d
]
.I prog
.SH DESCRIPTION
.I 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.
.PP
.I Dtracy
uses an
.IR awk (1)
inspired syntax.
A
.I dtracy
program is a series of statements of one of the following forms
.IP
\fIprobes\fR \fL{\fR \fIactions\fL } \fR
.br
\fIprobes\fR \fLif\fR \fIpredicate \fL{\fR \fIactions\fL } \fR
.PP
\fIProbes\fR is a comma-separated list of probes, such as \fLsys:pwrite:entry\fR.
Each probe name consists of any number of parts separated by \fL:\fR.
If a part is omitted (e.g. \fLqsys::entry\fR), it matches all probes that match the remaining parts.
If the probe name is enclosed in quotation marks, the wildcards \fL*\fR and \fL?\fR are available, e.g. \fL"sys:*stat:entry"\fR.
.PP
\fIPredicate\fR, if specified, is an expression that must evaluate to a non-zero value for the actions to be executed.
.PP
\fIActions\fR is a semicolon-separated list of statements of one of the following forms:
.IP
\fIexpr\fR
.br
\fLprint \fIa\fL, \fIb\fL, \fI...\fR
.br
\fLprintf "\fIfmt\fR", \fIa\fL, \fIb\fL, \fI...\fR
.br
\fL@\fIname\fL[\fIindex\fL] = \fIaggregation-expr\fR
.PP
Expressions follow C syntax and semantics and all C operators (including casts) are supported.
Available integer types are
.BR u8 ,
.BR u16 ,
.BR u32 ,
.BR u64 ,
.BR s8 ,
.BR s16 ,
.B s32
and
.BR s64 ;
they correspond to the C types
.BR u8int ,
etc.
Additionally, a string type \fIstring\fR is available.
.PP
Expressions can use the following variables
.TF "\fLarg0\fR, \fLarg1\fR, ...  "
.TP
\fLprobe\fR
name of the probe that was triggered
.TP
\fLpid\fR
PID of the process triggering the probe
.TP
\fLarg0\fR, \fLarg1\fR, ...
for a syscall probe, the syscall arguments (cast to \fBs64\fR)
.TP
\fLtime\fR
timestamp when the probe was triggered
.TP
\fLmachno\fR
CPU number on which the probe was triggered
.PD
.PP
.I Print
prints all its arguments, separated by spaces and followed by a newline.
.I Printf
prints its arguments using a format string with
.IR print (2)
syntax.
However, there is no need to specify the argument size, e.g. \fL%d\fR works for all integer types.
.PP
Statements of the form \fL@\fIname\fL[\fIindex\fL] = \fIaggregation-expr\fR collect 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
.I dtracy
finishes.
\fIIndex\fR is effectively a label for the datapoint; statistics are evaluated over all datapoints of the same index.
.PP
\fIAggregation-expr\fR specifies the type of statistic to be collected.
Available options are
.TF "\fLavg(\fIexpr\fL)\fR  "
.TP
\fLcount()\fR
number of datapoints
.TP
\fLavg(\fIexpr\fL)\fR
average
.TP
\fLsum(\fIexpr\fL)\fR
sum
.TP
\fLmin(\fIexpr\fL)\fR
minimum
.TP
\fLmax(\fIexpr\fL)\fR
maximum
.TP
\fLstd(\fIexpr\fL)\fR
average and standard deviation
.PD
.PP
.SH EXAMPLES
.IP
.EX
sys:: { print probe, pid, arg0, arg1 }
.EE
.PP
The world's worst syscall tracer.
.IP
.EX
sys:pread:entry if pid == 42 { printf "time %d, fd %d\\n", time, arg0 }
.EE
.PP
Every time the process with PID 42 executes
.IR pread (2),
write down the timestamp and the file descriptor used.
.IP
.EX
sys:open:entry { print (string)arg0 }
.EE
.PP
Print the names of files as they are being opened.
.IP
.EX
sys:pread:entry { @size[pid] = avg(arg2) }
.EE
.PP
Determine the average
.I pread
buffer size for each process.
.SH SOURCE
.B /sys/src/cmd/dtracy
.SH BUGS
Yes.
.SH HISTORY
.I Dtracy
appeared in 9front in November, 2018.