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 operators (including casts) are supported. Available integer types are u8, u16, u32, u64, s8, s16, s32 and s64; they correspond 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 arguments (cast to s64)  

time

timestamp when the probe was triggered  

machno

CPU number on which the probe was triggered  

Print prints all its arguments, separated by spaces and followed 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 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 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 collected. 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.