perf/Documentation/perf-probe.txt

1 perf-probe(1)
4 NAME
5 ----
6 perf-probe - Define new dynamic tracepoints
9 --------
11 'perf probe' [options] --add='PROBE' [...]
15 'perf probe' [options] --del='[GROUP:]EVENT' [...]
17 'perf probe' --list[=[GROUP:]EVENT]
19 'perf probe' [options] --line='LINE'
21 'perf probe' [options] --vars='PROBEPOINT'
23 'perf probe' [options] --funcs
25 'perf probe' [options] --definition='PROBE' [...]
28 -----------
30 without debuginfo, or by C expressions (C line numbers, C function names,
35 -------
36 -k::
37 --vmlinux=PATH::
39 	Only when using this with --definition, you can give an offline
42 -m::
43 --module=MODNAME|PATH::
44 	Specify module name in which perf-probe searches probe points
45 	or lines. If a path of module file is passed, perf-probe
49 -s::
50 --source=PATH::
53 -v::
54 --verbose::
56 	Can not use with -q.
58 -q::
59 --quiet::
61 	Can not use with -v.
63 -a::
64 --add=::
67 -d::
68 --del=::
70 	classes(e.g. [a-z], [!A-Z]).
72 -l::
73 --list[=[GROUP:]EVENT]::
76 	When this is used with --cache, perf shows all cached probes instead of
79 -L::
80 --line=::
82 	which specifies a range of the source code. (see LINE SYNTAX for detail)
84 -V::
85 --vars=::
89 --externs::
90 	(Only for --vars) Show external defined variables in addition to local
93 --no-inlines::
94 	(Only for --add) Search only for non-inlined functions. The functions
97 -F::
98 --funcs[=FILTER]::
99 	Show available functions in given module or kernel. With -x/--exec,
103 -D::
104 --definition=::
105 	Show trace-event definition converted from given probe-event instead
108 --filter=FILTER::
109 	(Only for --vars and --funcs) Set filter. FILTER is a combination of glob
111 	Default FILTER is "!__k???tab_* & !__crc_*" for --vars, and "!_*"
112 	for --funcs.
115 -f::
116 --force::
117 	Forcibly add events with existing name.
119 -n::
120 --dry-run::
121 	Dry run. With this option, --add and --del doesn't execute actual
124 --cache::
125 	(With --add) Cache the probes. Any events which successfully added
127 	(With --list) Show cached probes.
128 	(With --del) Remove cached probes.
130 --max-probes=NUM::
133 --target-ns=PID:
138 -x::
139 --exec=PATH::
141 	space tracing. Can also be used with --funcs option.
143 --demangle::
144 	Demangle application symbols. --no-demangle is also available
147 --demangle-kernel::
148 	Demangle kernel symbols. --no-demangle-kernel is also available
151 In absence of -m/-x options, perf probe checks if the first argument after
152 the options is an absolute path name. If its an absolute path, perf probe
156 ------------
159     1) Define event based on function name
162     2) Define event based on source file with line number
168     4) Pre-defined SDT events or cached event with name
173 …name of new event, if omitted, it will be set the name of the probed function, and for return prob…
174 Note that using existing group name can conflict with other events. Especially, using the group nam…
176 …name, and it may have one of the following options; '+OFFS' is the offset from function entry addr…
177 …by the source line number or lazy matching by using 'SRC:ALN' or 'SRC;PTN' syntax, where 'SRC' is …
179 …VIDER' is the pre-defined event name which is defined by user SDT (Statically Defined Tracing) or …
180 …inary (on which SDT events are defined) must be scanned by linkperf:perf-buildid-cache[1] to make …
183 https://sourceware.org/gdb/onlinedocs/gdb/Static-Probe-Points.html
186 -----------------
194 --------------
197  [NAME=]LOCALVAR|$retval|%REG|@SYMBOL[:TYPE][@user]
199 …NAME' specifies the name of this argument (optional). You can use the name of local variable, loca…
200 '$vars' and '$params' special arguments are also available for NAME, '$vars' is expanded to the loc…
203 "@user" is a special attribute which means the LOCALVAR will be treated as a user-space memory. Thi…
206 -----
207 …e its size auto-detected by perf probe. Moreover, you can use 'x' to explicitly specify to be show…
208 String type is a special type, which fetches a "null-terminated" string from kernel space. This mea…
209 Bitfield is another special type, which takes 3 parameters, bit-width, bit-offset, and container-si…
211  b<bit-width>@<bit-offset>/<container-size>
213 LINE SYNTAX
214 -----------
215 Line range is described by following syntax.
217  "FUNC[@SRC][:RLN[+NUM|-RLN2]]|SRC[:ALN[+NUM|-ALN2]]"
219 FUNC specifies the function name of showing lines. 'RLN' is the start line
220 number from function entry line, and 'RLN2' is the end line number. As same as
221 probe syntax, 'SRC' means the source file path, 'ALN' is start line number,
222 and 'ALN2' is end line number in the file. It is also possible to specify how
224 for searching a specific function when several functions share same name.
225 So, "source.c:100-120" shows lines between 100th to 120th in source.c file. And "func:10+20" shows …
228 -------------
229 …line matching is similar to glob matching but ignoring spaces in both of pattern and target. So th…
234 …e changes. For example, actual 10th line of schedule() can be moved easily by modifying schedule()…
237 --------------
239 In addition, you can use "!" for specifying filter-out rule. You also can give several rules combin…
242  With --filter "foo* | bar*", perf probe -V shows variables which start with "foo" or "bar".
243 …With --filter "!foo* & *bar", perf probe -V shows variables which don't start with "foo" and end w…
246 --------
249  ./perf probe --line schedule
251 Add a probe on schedule() function 12th line with recording cpu local variable:
255  ./perf probe --add='schedule:12 cpu'
257 Add one or more probes which has the name start with "schedule".
261  ./perf probe --add='schedule*'
267  ./perf probe --add='schedule;update_rq_clock*'
271  ./perf probe --del='schedule*'
275  ./perf probe -x /bin/zsh zfree or ./perf probe /bin/zsh zfree
279  ./perf probe -x /lib/libc.so.6 malloc or ./perf probe /lib/libc.so.6 malloc
283  ./perf probe --target-ns <target pid> -x /lib64/libc.so.6 malloc
287 …./perf probe --target-ns <target pid> -x /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.121-0.b13.el7_3.x86…
291  ./perf probe -x /lib64/libc-2.25.so 'malloc_get_state\@GLIBC_2.2.5'
295  ./perf probe -x /opt/test/a.out 'foo\+bar.c:4'
299 ----------------------
302 …- Since tracefs and kallsyms requires root or privileged user to access it, the following perf pro…
304 …- The system admin can remount the tracefs with 755 (`sudo mount -o remount,mode=755 /sys/kernel/t…
306 …- /proc/sys/kernel/kptr_restrict = 2 (restrict all users) also prevents perf probe to retrieve the…
308 …- Since the perf probe commands read the vmlinux (for kernel) and/or the debuginfo file (including…
312 --------
313 linkperf:perf-trace[1], linkperf:perf-record[1], linkperf:perf-buildid-cache[1]