1 perf-probe(1)
2 =============
3
4 NAME
5 ----
6 perf-probe - Define new dynamic tracepoints
7
8 SYNOPSIS
9 --------
10 [verse]
11 'perf probe' [options] --add='PROBE' [...]
12 or
13 'perf probe' [options] PROBE
14 or
15 'perf probe' [options] --del='[GROUP:]EVENT' [
16 or
17 'perf probe' --list[=[GROUP:]EVENT]
18 or
19 'perf probe' [options] --line='LINE'
20 or
21 'perf probe' [options] --vars='PROBEPOINT'
22 or
23 'perf probe' [options] --funcs
24 or
25 'perf probe' [options] --definition='PROBE' [.
26
27 DESCRIPTION
28 -----------
29 This command defines dynamic tracepoint events
30 without debuginfo, or by C expressions (C line
31 and C local variables) with debuginfo.
32
33
34 OPTIONS
35 -------
36 -k::
37 --vmlinux=PATH::
38 Specify vmlinux path which has debugin
39 Only when using this with --definition
40 vmlinux file.
41
42 -m::
43 --module=MODNAME|PATH::
44 Specify module name in which perf-prob
45 or lines. If a path of module file is
46 treat it as an offline module (this me
47 a module which has not been loaded yet
48
49 -s::
50 --source=PATH::
51 Specify path to kernel source.
52
53 -v::
54 --verbose::
55 Be more verbose (show parsed arguments
56 Can not use with -q.
57
58 -q::
59 --quiet::
60 Do not show any warnings or messages.
61 Can not use with -v.
62
63 -a::
64 --add=::
65 Define a probe event (see PROBE SYNTAX
66
67 -d::
68 --del=::
69 Delete probe events. This accepts glob
70 classes(e.g. [a-z], [!A-Z]).
71
72 -l::
73 --list[=[GROUP:]EVENT]::
74 List up current probe events. This can
75 event names.
76 When this is used with --cache, perf s
77 the live probes.
78
79 -L::
80 --line=::
81 Show source code lines which can be pr
82 which specifies a range of the source
83
84 -V::
85 --vars=::
86 Show available local variables at give
87 syntax is same as PROBE SYNTAX, but NO
88
89 --externs::
90 (Only for --vars) Show external define
91 variables.
92
93 --no-inlines::
94 (Only for --add) Search only for non-i
95 which do not have instances are ignore
96
97 -F::
98 --funcs[=FILTER]::
99 Show available functions in given modu
100 can also list functions in a user spac
101 This also can accept a FILTER rule arg
102
103 -D::
104 --definition=::
105 Show trace-event definition converted
106 of write it into tracing/[k,u]probe_ev
107
108 --filter=FILTER::
109 (Only for --vars and --funcs) Set filt
110 pattern, see FILTER PATTERN for detail
111 Default FILTER is "!__k???tab_* & !__c
112 for --funcs.
113 If several filters are specified, only
114
115 -f::
116 --force::
117 Forcibly add events with existing name
118
119 -n::
120 --dry-run::
121 Dry run. With this option, --add and -
122 adding and removal operations.
123
124 --cache::
125 (With --add) Cache the probes. Any eve
126 are also stored in the cache file.
127 (With --list) Show cached probes.
128 (With --del) Remove cached probes.
129
130 --max-probes=NUM::
131 Set the maximum number of probe points
132
133 --target-ns=PID:
134 Obtain mount namespace information fro
135 used when creating a uprobe for a proc
136 different mount namespace from the per
137
138 -x::
139 --exec=PATH::
140 Specify path to the executable or shar
141 space tracing. Can also be used with -
142
143 --demangle::
144 Demangle application symbols. --no-dem
145 for disabling demangling.
146
147 --demangle-kernel::
148 Demangle kernel symbols. --no-demangle
149 for disabling kernel demangling.
150
151 In absence of -m/-x options, perf probe checks
152 the options is an absolute path name. If its a
153 uses it as a target module/target user space b
154
155 PROBE SYNTAX
156 ------------
157 Probe points are defined by following syntax.
158
159 1) Define event based on function name
160 [[GROUP:]EVENT=]FUNC[@SRC][:RLN|+OFFS|%re
161
162 2) Define event based on source file with
163 [[GROUP:]EVENT=]SRC:ALN [ARG ...]
164
165 3) Define event based on source file with
166 [[GROUP:]EVENT=]SRC;PTN [ARG ...]
167
168 4) Pre-defined SDT events or cached event
169 %[sdt_PROVIDER:]SDTEVENT
170 or,
171 sdt_PROVIDER:SDTEVENT
172
173 'EVENT' specifies the name of new event, if om
174 Note that using existing group name can confli
175 modules.
176 'FUNC' specifies a probed function name, and i
177 It is also possible to specify a probe point b
178 'ARG' specifies the arguments of this probe po
179 'SDTEVENT' and 'PROVIDER' is the pre-defined e
180 Note that before using the SDT event, the targ
181
182 For details of the SDT, see below.
183 https://sourceware.org/gdb/onlinedocs/gdb/Stat
184
185 ESCAPED CHARACTER
186 -----------------
187
188 In the probe syntax, '=', '@', '+', ':' and ';
189 This is useful if you need to probe on a speci
190 Note that usually single backslash is consumed
191 See EXAMPLES how it is used.
192
193 PROBE ARGUMENT
194 --------------
195 Each probe argument follows below syntax.
196
197 [NAME=]LOCALVAR|$retval|%REG|@SYMBOL[:TYPE][@
198
199 'NAME' specifies the name of this argument (op
200 '$vars' and '$params' special arguments are al
201 'TYPE' casts the type of this argument (option
202 On x86 systems %REG is always the short form o
203 "@user" is a special attribute which means the
204
205 TYPES
206 -----
207 Basic types (u8/u16/u32/u64/s8/s16/s32/s64) an
208 String type is a special type, which fetches a
209 Bitfield is another special type, which takes
210
211 b<bit-width>@<bit-offset>/<container-size>
212
213 LINE SYNTAX
214 -----------
215 Line range is described by following syntax.
216
217 "FUNC[@SRC][:RLN[+NUM|-RLN2]]|SRC[:ALN[+NUM|-
218
219 FUNC specifies the function name of showing li
220 number from function entry line, and 'RLN2' is
221 probe syntax, 'SRC' means the source file path
222 and 'ALN2' is end line number in the file. It
223 many lines to show by using 'NUM'. Moreover, '
224 for searching a specific function when several
225 So, "source.c:100-120" shows lines between 100
226
227 LAZY MATCHING
228 -------------
229 The lazy line matching is similar to glob matc
230
231 e.g.
232 'a=*' can matches 'a=b', 'a = b', 'a == b' an
233
234 This provides some sort of flexibility and rob
235
236 FILTER PATTERN
237 --------------
238 The filter pattern is a glob matching pattern(
239 In addition, you can use "!" for specifying fi
240
241 e.g.
242 With --filter "foo* | bar*", perf probe -V sh
243 With --filter "!foo* & *bar", perf probe -V s
244
245 EXAMPLES
246 --------
247 Display which lines in schedule() can be probe
248
249 ./perf probe --line schedule
250
251 Add a probe on schedule() function 12th line w
252
253 ./perf probe schedule:12 cpu
254 or
255 ./perf probe --add='schedule:12 cpu'
256
257 Add one or more probes which has the name star
258
259 ./perf probe schedule*
260 or
261 ./perf probe --add='schedule*'
262
263 Add probes on lines in schedule() function whi
264
265 ./perf probe 'schedule;update_rq_clock*'
266 or
267 ./perf probe --add='schedule;update_rq_clock*
268
269 Delete all probes on schedule().
270
271 ./perf probe --del='schedule*'
272
273 Add probes at zfree() function on /bin/zsh
274
275 ./perf probe -x /bin/zsh zfree or ./perf prob
276
277 Add probes at malloc() function on libc
278
279 ./perf probe -x /lib/libc.so.6 malloc or ./pe
280
281 Add a uprobe to a target process running in a
282
283 ./perf probe --target-ns <target pid> -x /lib
284
285 Add a USDT probe to a target process running i
286
287 ./perf probe --target-ns <target pid> -x /usr
288
289 Add a probe on specific versioned symbol by ba
290
291 ./perf probe -x /lib64/libc-2.25.so 'malloc_g
292
293 Add a probe in a source file using special cha
294
295 ./perf probe -x /opt/test/a.out 'foo\+bar.c:4
296
297
298 PERMISSIONS AND SYSCTL
299 ----------------------
300 Since perf probe depends on ftrace (tracefs) a
301
302 - Since tracefs and kallsyms requires root or
303
304 - The system admin can remount the tracefs wi
305
306 - /proc/sys/kernel/kptr_restrict = 2 (restric
307
308 - Since the perf probe commands read the vmli
309
310
311 SEE ALSO
312 --------
313 linkperf:perf-trace[1], linkperf:perf-record[1
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.