NAME
BT —
Bug Tracing language
SYNTAX
/
filter / {
action }DESCRIPTION
The BT language, also known as BPFtrace
syntax, describes how to format and display information gathered from
specified probe events.
Events are generated by the dynamic tracer dt(4) when an enabled probe is triggered. They are periodically collected by btrace(8), which formats them using the corresponding action. If a recorded event doesn't match the optional filter, it will be silently ignored.
A valid BT source file contains at least
one probe clause associated with an
action statement.
PROBE
The list of available probes may vary from system to system and can be queried with btrace(8).
The special probes BEGIN and
END may be used to manipulate states before the
first event is recorded and after the last. They cannot be combined with any
filter.
FILTER
Define under which condition an event should be recorded when its related probe is executed. An empty filter means record all events.
Variable names available in filters:
- pid
- Process ID of the current thread.
- tid
- Thread ID of the current thread.
ACTION
An action is a sequence of statements that are evaluated for each event recorded by the associated probe.
Variable names with special meaning:
- $N
- Command line argument N after the script name.
- argN
- Argument N of the corresponding probe.
- comm
- Command name of the current process.
- cpu
- ID of the processor that recorded the event.
- kstack
- Kernel stack of the current thread.
- nsecs
- Timestamp of the event in nanoseconds.
- pid
- Process ID of the current thread.
- probe
- Full name of the probe.
- retval
- Return value of the traced syscall.
- tid
- Thread ID of the current thread.
- ustack
- Userland stack of the current thread.
Functions:
clear(@map)- Delete all (key, value) pairs from @map.
delete(@map[key])- Delete the pair indexed by key from @map.
exit()- Terminate execution with exit code 0. The
ENDprobe, if any, is executed and the contents of all non-empty maps are printed. hist(value)- Increment the bucket corresponding to value in a power-of-two histogram.
lhist(value, min, max, step)- Increment the bucket corresponding to value in the linear histogram spawning between the positive value min and max with buckets of step size.
print(@map)- Print all pairs from @map.
print(@map, n)- Print only the first n entries in @map.
printf(fmt, ...)- Print formatted string fmt.
str($N, [index])- Return the string from argument $N, truncated to index characters (up to 64, the default) including a guaranteed NUL-terminator.
time(timefmt)- Print timestamps using strftime(3).
zero(@map)- Set all values from @map to 0.
The following functions only work on a specific map entry.
- @map[key] =
count() - Increase the stored value for key by one.
- @map[key] =
max(value) - Store the maximum recorded value for key.
- @map[key] =
min(value) - Store the minimum recorded value for key.
- @map[key] =
sum(value) - Store the sum of all recorded values for key.
SEE ALSO
BPFtrace reference guide, https://github.com/iovisor/bpftrace/blob/master/docs/reference_guide.md.
STANDARDS
The dialect of the BT language described
in this manual and supported by
btrace(8) is compatible with BPFtrace. The syntax is similar to
awk(1) and dtrace.