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(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 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.