205 lines
4.7 KiB
Groff
205 lines
4.7 KiB
Groff
.\" $OpenBSD: bt.5,v 1.15 2023/06/27 14:13:33 claudio Exp $
|
|
.\"
|
|
.\" Copyright (c) 2019 Martin Pieuchot <mpi@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: June 27 2023 $
|
|
.Dt BT 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm BT
|
|
.Nd Bug Tracing language
|
|
.Sh SYNTAX
|
|
.D1 Ar probe Ic \&/ Ar filter Ic \&/ \&{ Ar action Ic \&}
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
language, also known as BPFtrace syntax, describes how to format and display
|
|
information gathered from specified
|
|
.Ar probe
|
|
events.
|
|
.Pp
|
|
Events are generated by the dynamic tracer
|
|
.Xr dt 4
|
|
when an enabled
|
|
.Ar probe
|
|
is triggered.
|
|
They are periodically collected by
|
|
.Xr btrace 8 ,
|
|
which formats them using the corresponding
|
|
.Ar action .
|
|
If a recorded event doesn't match the optional
|
|
.Ar filter ,
|
|
it will be silently ignored.
|
|
.Pp
|
|
A valid
|
|
.Nm
|
|
source file contains at least one
|
|
.Ar probe
|
|
clause associated with an
|
|
.Ar action
|
|
statement.
|
|
.Sh PROBE
|
|
The list of available probes may vary from system to system and can be queried
|
|
with
|
|
.Xr btrace 8 .
|
|
.Pp
|
|
The special probes
|
|
.Ic BEGIN
|
|
and
|
|
.Ic END
|
|
may be used to manipulate states before the first event is recorded and after
|
|
the last.
|
|
They cannot be combined with any
|
|
.Ar filter .
|
|
.Sh FILTER
|
|
Define under which condition an event should be recorded when its related
|
|
.Ar probe
|
|
is executed.
|
|
An empty
|
|
.Ar filter
|
|
means record all events.
|
|
.Pp
|
|
Variable names available in filters:
|
|
.Pp
|
|
.Bl -tag -width "kstack " -compact -offset indent
|
|
.It Va pid
|
|
Process ID of the current thread.
|
|
.It Va tid
|
|
Thread ID of the current thread.
|
|
.El
|
|
.Sh ACTION
|
|
An action is a sequence of statements that are evaluated for each event recorded
|
|
by the associated
|
|
.Ar probe .
|
|
.Pp
|
|
Variable names with special meaning:
|
|
.Pp
|
|
.Bl -tag -width "kstack " -compact -offset indent
|
|
.It Va $N
|
|
Command line argument
|
|
.Va N
|
|
after the script name.
|
|
.It Va argN
|
|
Argument
|
|
.Va N
|
|
of the corresponding probe.
|
|
.It Va comm
|
|
Command name of the current process.
|
|
.It Va cpu
|
|
ID of the processor that recorded the event.
|
|
.It Va kstack
|
|
Kernel stack of the current thread.
|
|
.It Va nsecs
|
|
Timestamp of the event in nanoseconds.
|
|
.It Va pid
|
|
Process ID of the current thread.
|
|
.It Va probe
|
|
Full name of the probe.
|
|
.It Va retval
|
|
Return value of the traced syscall.
|
|
.It Va tid
|
|
Thread ID of the current thread.
|
|
.It Va ustack
|
|
Userland stack of the current thread.
|
|
.El
|
|
.Pp
|
|
Functions:
|
|
.Bl -tag -width "lhist(value, min, max, step)"
|
|
.It Fn clear "@map"
|
|
Delete all (key, value) pairs from
|
|
.Va @map .
|
|
.It Fn delete "@map[key]"
|
|
Delete the pair indexed by
|
|
.Va key
|
|
from
|
|
.Va @map .
|
|
.It Fn exit
|
|
Terminate execution with exit code 0.
|
|
.It Fn hist "value"
|
|
Increment the bucket corresponding to
|
|
.Va value
|
|
in a power-of-two histogram.
|
|
.It Fn lhist "value" "min" "max" "step"
|
|
Increment the bucket corresponding to
|
|
.Va value
|
|
in the linear histogram spawning between the positive value
|
|
.Va min
|
|
and
|
|
.Va max
|
|
with buckets of
|
|
.Va step
|
|
size.
|
|
.It Fn print "@map"
|
|
Print all pairs from
|
|
.Va @map .
|
|
.It Fn print "@map" n
|
|
Print only the first
|
|
.Va n
|
|
entries in
|
|
.Va @map .
|
|
.It Fn printf "fmt" ...
|
|
Print formatted string
|
|
.Va fmt .
|
|
.It Fn str "$N" "[index]"
|
|
Return the string from argument
|
|
.Va $N ,
|
|
truncated to
|
|
.Va index
|
|
characters (up to 64, the default) including a guaranteed NUL-terminator.
|
|
.It Fn time timefmt
|
|
Print timestamps using
|
|
.Xr strftime 3 .
|
|
.It Fn zero "@map"
|
|
Set all values from
|
|
.Va @map
|
|
to 0.
|
|
.El
|
|
.Pp
|
|
The following functions only work on a sepcific map entry.
|
|
.Bl -tag -width "lhist(value, min, max, step)"
|
|
.It "@map[key]" = Fn count
|
|
Increase the stored value for
|
|
.Va key
|
|
by one.
|
|
.It "@map[key]" = Fn max "value"
|
|
Store the maximum recorded value for
|
|
.Va key .
|
|
.It "@map[key]" = Fn min "value"
|
|
Store the minimum recorded value for
|
|
.Va key .
|
|
.It "@map[key]" = Fn sum "value"
|
|
Store the sum of all recorded values for
|
|
.Va key .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr awk 1 ,
|
|
.Xr dt 4 ,
|
|
.Xr btrace 8
|
|
.Rs
|
|
.\"%A First Last
|
|
.%T BPFtrace reference guide
|
|
.%U https://github.com/iovisor/bpftrace/blob/master/docs/reference_guide.md
|
|
.\"%D November 1, 1901
|
|
.Re
|
|
.Sh STANDARDS
|
|
The dialect
|
|
of the
|
|
.Nm
|
|
language described in this manual and supported by
|
|
.Xr btrace 8
|
|
is compatible with BPFtrace.
|
|
The syntax is similar to
|
|
.Xr awk 1
|
|
and dtrace.
|