1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
.\" $OpenBSD: bt.5,v 1.17 2023/10/22 19:30:35 cheloha 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: October 22 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.
The
.Ic END
probe,
if any,
is executed and the contents of all non-empty maps are printed.
.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 specific 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.
|
