| perf-probe(1) |
| ============= |
| |
| NAME |
| ---- |
| perf-probe - Define new dynamic tracepoints |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'perf probe' [options] --add='PROBE' [...] |
| or |
| 'perf probe' [options] PROBE |
| or |
| 'perf probe' [options] --del='[GROUP:]EVENT' [...] |
| or |
| 'perf probe' --list |
| or |
| 'perf probe' --line='FUNC[:RLN[+NUM|:RLN2]]|SRC:ALN[+NUM|:ALN2]' |
| |
| DESCRIPTION |
| ----------- |
| This command defines dynamic tracepoint events, by symbol and registers |
| without debuginfo, or by C expressions (C line numbers, C function names, |
| and C local variables) with debuginfo. |
| |
| |
| OPTIONS |
| ------- |
| -k:: |
| --vmlinux=PATH:: |
| Specify vmlinux path which has debuginfo (Dwarf binary). |
| |
| -v:: |
| --verbose:: |
| Be more verbose (show parsed arguments, etc). |
| |
| -a:: |
| --add=:: |
| Define a probe event (see PROBE SYNTAX for detail). |
| |
| -d:: |
| --del=:: |
| Delete probe events. This accepts glob wildcards('*', '?') and character |
| classes(e.g. [a-z], [!A-Z]). |
| |
| -l:: |
| --list:: |
| List up current probe events. |
| |
| -L:: |
| --line=:: |
| Show source code lines which can be probed. This needs an argument |
| which specifies a range of the source code. (see LINE SYNTAX for detail) |
| |
| -f:: |
| --force:: |
| Forcibly add events with existing name. |
| |
| PROBE SYNTAX |
| ------------ |
| Probe points are defined by following syntax. |
| |
| "[EVENT=]FUNC[+OFFS|:RLN|%return][@SRC]|SRC:ALN [ARG ...]" |
| |
| 'EVENT' specifies the name of new event, if omitted, it will be set the name of the probed function. Currently, event group name is set as 'probe'. |
| 'FUNC' specifies a probed function name, and it may have one of the following options; '+OFFS' is the offset from function entry address in bytes, 'RLN' is the relative-line number from function entry line, and '%return' means that it probes function return. In addition, 'SRC' specifies a source file which has that function. |
| It is also possible to specify a probe point by the source line number by using 'SRC:ALN' syntax, where 'SRC' is the source file path and 'ALN' is the line number. |
| 'ARG' specifies the arguments of this probe point. You can use the name of local variable, or kprobe-tracer argument format (e.g. $retval, %ax, etc). |
| |
| LINE SYNTAX |
| ----------- |
| Line range is descripted by following syntax. |
| |
| "FUNC[:RLN[+NUM|:RLN2]]|SRC:ALN[+NUM|:ALN2]" |
| |
| FUNC specifies the function name of showing lines. 'RLN' is the start line |
| number from function entry line, and 'RLN2' is the end line number. As same as |
| probe syntax, 'SRC' means the source file path, 'ALN' is start line number, |
| and 'ALN2' is end line number in the file. It is also possible to specify how |
| many lines to show by using 'NUM'. |
| So, "source.c:100-120" shows lines between 100th to l20th in source.c file. And "func:10+20" shows 20 lines from 10th line of func function. |
| |
| EXAMPLES |
| -------- |
| Display which lines in schedule() can be probed: |
| |
| ./perf probe --line schedule |
| |
| Add a probe on schedule() function 12th line with recording cpu local variable: |
| |
| ./perf probe schedule:12 cpu |
| or |
| ./perf probe --add='schedule:12 cpu' |
| |
| this will add one or more probes which has the name start with "schedule". |
| |
| Delete all probes on schedule(). |
| |
| ./perf probe --del='schedule*' |
| |
| |
| SEE ALSO |
| -------- |
| linkperf:perf-trace[1], linkperf:perf-record[1] |
