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
Page 1 Plan 9 (printed 9/19/24)
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(2) 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.
Page 2 Plan 9 (printed 9/19/24)
DTRACY(1) DTRACY(1)
Page 3 Plan 9 (printed 9/19/24)