OpenBSD manual page server

Manual Page Search Parameters

BT(5) File Formats Manual BT(5)

BTBug Tracing language

probe / filter / { action }

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.

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.

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.

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.

Functions:

(@map)
Delete all (key, value) pairs from @map.
(@map[key])
Delete the pair indexed by key from @map.
()
Terminate execution with exit code 0.
(value)
Increment the bucket corresponding to value in a power-of-two histogram.
(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.
()
Returns the maximum recorded value.
()
Returns the minimum recorded value.
(@map)
Print all pairs from @map.
print(@map, n)
Print only the first n entries in @map.
(fmt, ...)
Print formatted string fmt.
($N, [index])
Return the string from argument $N, truncated to index characters (up to 64, the default) including a guaranteed NUL-terminator.
()
Returns the sum of all recorded values.
(timefmt)
Print timestamps using strftime(3).
(@map)
Set all values from @map to 0.

awk(1), dt(4), btrace(8)

BPFtrace reference guide, https://github.com/iovisor/bpftrace/blob/master/docs/reference_guide.md.

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.

March 31, 2022 OpenBSD-7.2