[linux-block.git] / tools / perf / Documentation / perf-probe.txt

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' [options] --line='FUNC[:RLN[+NUM|:RLN2]]|SRC:ALN[+NUM|:ALN2]'
or
'perf probe' [options] --vars='PROBEPOINT'

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).

-m::
--module=MODNAME::
	Specify module name in which perf-probe searches probe points
	or lines.

-s::
--source=PATH::
	Specify path to kernel source.

-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)

-V::
--vars=::
	Show available local variables at given probe point. The argument
	syntax is same as PROBE SYNTAX, but NO ARGs.

--externs::
	(Only for --vars) Show external defined variables in addition to local
	variables.

-F::
--funcs::
	Show available functions in given module or kernel.

--filter=FILTER::
	(Only for --vars) Set filter for variables. FILTER is a combination of
	glob pattern, see FILTER PATTERN for details.
	Default FILTER is "!__k???tab_* & !__crc_*".
	If several filters are specified, only the last filter is valid.

-f::
--force::
	Forcibly add events with existing name.

-n::
--dry-run::
	Dry run. With this option, --add and --del doesn't execute actual
	adding and removal operations.

--max-probes::
	Set the maximum number of probe points for an event. Default is 128.

PROBE SYNTAX
------------
Probe points are defined by following syntax.

    1) Define event based on function name
     [EVENT=]FUNC[@SRC][:RLN|+OFFS|%return|;PTN] [ARG ...]

    2) Define event based on source file with line number
     [EVENT=]SRC:ALN [ARG ...]

    3) Define event based on source file with lazy pattern
     [EVENT=]SRC;PTN [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. And ';PTN' means lazy matching pattern (see LAZY MATCHING). Note that ';PTN' must be the end of the probe point definition.  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 or lazy matching by using 'SRC:ALN' or 'SRC;PTN' syntax, where 'SRC' is the source file path, ':ALN' is the line number and ';PTN' is the lazy matching pattern.
'ARG' specifies the arguments of this probe point, (see PROBE ARGUMENT).

PROBE ARGUMENT
--------------
Each probe argument follows below syntax.

 [NAME=]LOCALVAR|$retval|%REG|@SYMBOL[:TYPE]

'NAME' specifies the name of this argument (optional). You can use the name of local variable, local data structure member (e.g. var->field, var.field2), local array with fixed index (e.g. array[1], var->array[0], var->pointer[2]), or kprobe-tracer argument format (e.g. $retval, %ax, etc). Note that the name of this argument will be set as the last member name if you specify a local data structure member (e.g. field2 for 'var->field1.field2'.)
'TYPE' casts the type of this argument (optional). If omitted, perf probe automatically set the type based on debuginfo. You can specify 'string' type only for the local variable or structure member which is an array of or a pointer to 'char' or 'unsigned char' type.

LINE SYNTAX
-----------
Line range is described 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.

LAZY MATCHING
-------------
 The lazy line matching is similar to glob matching but ignoring spaces in both of pattern and target. So this accepts wildcards('*', '?') and character classes(e.g. [a-z], [!A-Z]).

e.g.
 'a=*' can matches 'a=b', 'a = b', 'a == b' and so on.

This provides some sort of flexibility and robustness to probe point definitions against minor code changes. For example, actual 10th line of schedule() can be moved easily by modifying schedule(), but the same line matching 'rq=cpu_rq*' may still exist in the function.)

FILTER PATTERN
--------------
 The filter pattern is a glob matching pattern(s) to filter variables.
 In addition, you can use "!" for specifying filter-out rule. You also can give several rules combined with "&" or "|", and fold those rules as one rule by using "(" ")".

e.g.
 With --filter "foo* | bar*", perf probe -V shows variables which start with "foo" or "bar".
 With --filter "!foo* & *bar", perf probe -V shows variables which don't start with "foo" and end with "bar", like "fizzbar". But "foobar" is filtered out.

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".

 Add probes on lines in schedule() function which calls update_rq_clock().

 ./perf probe 'schedule;update_rq_clock*'
 or
 ./perf probe --add='schedule;update_rq_clock*'

Delete all probes on schedule().

 ./perf probe --del='schedule*'


SEE ALSO
--------
linkperf:perf-trace[1], linkperf:perf-record[1]
Commit	Line	Data
	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
	18	or
	19	'perf probe' [options] --line='FUNC[:RLN[+NUM\|:RLN2]]\|SRC:ALN[+NUM\|:ALN2]'
	20	or
	21	'perf probe' [options] --vars='PROBEPOINT'
	22
	23	DESCRIPTION
	24	-----------
	25	This command defines dynamic tracepoint events, by symbol and registers
	26	without debuginfo, or by C expressions (C line numbers, C function names,
	27	and C local variables) with debuginfo.
	28
	29
	30	OPTIONS
	31	-------
	32	-k::
	33	--vmlinux=PATH::
	34	Specify vmlinux path which has debuginfo (Dwarf binary).
	35
	36	-m::
	37	--module=MODNAME::
	38	Specify module name in which perf-probe searches probe points
	39	or lines.
	40
	41	-s::
	42	--source=PATH::
	43	Specify path to kernel source.
	44
	45	-v::
	46	--verbose::
	47	Be more verbose (show parsed arguments, etc).
	48
	49	-a::
	50	--add=::
	51	Define a probe event (see PROBE SYNTAX for detail).
	52
	53	-d::
	54	--del=::
	55	Delete probe events. This accepts glob wildcards('*', '?') and character
	56	classes(e.g. [a-z], [!A-Z]).
	57
	58	-l::
	59	--list::
	60	List up current probe events.
	61
	62	-L::
	63	--line=::
	64	Show source code lines which can be probed. This needs an argument
	65	which specifies a range of the source code. (see LINE SYNTAX for detail)
	66
	67	-V::
	68	--vars=::
	69	Show available local variables at given probe point. The argument
	70	syntax is same as PROBE SYNTAX, but NO ARGs.
	71
	72	--externs::
	73	(Only for --vars) Show external defined variables in addition to local
	74	variables.
	75
	76	-F::
	77	--funcs::
	78	Show available functions in given module or kernel.
	79
	80	--filter=FILTER::
	81	(Only for --vars) Set filter for variables. FILTER is a combination of
	82	glob pattern, see FILTER PATTERN for details.
	83	Default FILTER is "!__k???tab_* & !__crc_*".
	84	If several filters are specified, only the last filter is valid.
	85
	86	-f::
	87	--force::
	88	Forcibly add events with existing name.
	89
	90	-n::
	91	--dry-run::
	92	Dry run. With this option, --add and --del doesn't execute actual
	93	adding and removal operations.
	94
	95	--max-probes::
	96	Set the maximum number of probe points for an event. Default is 128.
	97
	98	PROBE SYNTAX
	99	------------
	100	Probe points are defined by following syntax.
	101
	102	1) Define event based on function name
	103	[EVENT=]FUNC[@SRC][:RLN\|+OFFS\|%return\|;PTN] [ARG ...]
	104
	105	2) Define event based on source file with line number
	106	[EVENT=]SRC:ALN [ARG ...]
	107
	108	3) Define event based on source file with lazy pattern
	109	[EVENT=]SRC;PTN [ARG ...]
	110
	111
	112	'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'.
	113	'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. And ';PTN' means lazy matching pattern (see LAZY MATCHING). Note that ';PTN' must be the end of the probe point definition. In addition, '@SRC' specifies a source file which has that function.
	114	It is also possible to specify a probe point by the source line number or lazy matching by using 'SRC:ALN' or 'SRC;PTN' syntax, where 'SRC' is the source file path, ':ALN' is the line number and ';PTN' is the lazy matching pattern.
	115	'ARG' specifies the arguments of this probe point, (see PROBE ARGUMENT).
	116
	117	PROBE ARGUMENT
	118	--------------
	119	Each probe argument follows below syntax.
	120
	121	[NAME=]LOCALVAR\|$retval\|%REG\|@SYMBOL[:TYPE]
	122
	123	'NAME' specifies the name of this argument (optional). You can use the name of local variable, local data structure member (e.g. var->field, var.field2), local array with fixed index (e.g. array[1], var->array[0], var->pointer[2]), or kprobe-tracer argument format (e.g. $retval, %ax, etc). Note that the name of this argument will be set as the last member name if you specify a local data structure member (e.g. field2 for 'var->field1.field2'.)
	124	'TYPE' casts the type of this argument (optional). If omitted, perf probe automatically set the type based on debuginfo. You can specify 'string' type only for the local variable or structure member which is an array of or a pointer to 'char' or 'unsigned char' type.
	125
	126	LINE SYNTAX
	127	-----------
	128	Line range is described by following syntax.
	129
	130	"FUNC[:RLN[+NUM\|-RLN2]]\|SRC[:ALN[+NUM\|-ALN2]]"
	131
	132	FUNC specifies the function name of showing lines. 'RLN' is the start line
	133	number from function entry line, and 'RLN2' is the end line number. As same as
	134	probe syntax, 'SRC' means the source file path, 'ALN' is start line number,
	135	and 'ALN2' is end line number in the file. It is also possible to specify how
	136	many lines to show by using 'NUM'.
	137	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.
	138
	139	LAZY MATCHING
	140	-------------
	141	The lazy line matching is similar to glob matching but ignoring spaces in both of pattern and target. So this accepts wildcards('*', '?') and character classes(e.g. [a-z], [!A-Z]).
	142
	143	e.g.
	144	'a=*' can matches 'a=b', 'a = b', 'a == b' and so on.
	145
	146	This provides some sort of flexibility and robustness to probe point definitions against minor code changes. For example, actual 10th line of schedule() can be moved easily by modifying schedule(), but the same line matching 'rq=cpu_rq*' may still exist in the function.)
	147
	148	FILTER PATTERN
	149	--------------
	150	The filter pattern is a glob matching pattern(s) to filter variables.
	151	In addition, you can use "!" for specifying filter-out rule. You also can give several rules combined with "&" or "\|", and fold those rules as one rule by using "(" ")".
	152
	153	e.g.
	154	With --filter "foo* \| bar*", perf probe -V shows variables which start with "foo" or "bar".
	155	With --filter "!foo* & *bar", perf probe -V shows variables which don't start with "foo" and end with "bar", like "fizzbar". But "foobar" is filtered out.
	156
	157	EXAMPLES
	158	--------
	159	Display which lines in schedule() can be probed:
	160
	161	./perf probe --line schedule
	162
	163	Add a probe on schedule() function 12th line with recording cpu local variable:
	164
	165	./perf probe schedule:12 cpu
	166	or
	167	./perf probe --add='schedule:12 cpu'
	168
	169	this will add one or more probes which has the name start with "schedule".
	170
	171	Add probes on lines in schedule() function which calls update_rq_clock().
	172
	173	./perf probe 'schedule;update_rq_clock*'
	174	or
	175	./perf probe --add='schedule;update_rq_clock*'
	176
	177	Delete all probes on schedule().
	178
	179	./perf probe --del='schedule*'
	180
	181
	182	SEE ALSO
	183	--------
	184	linkperf:perf-trace[1], linkperf:perf-record[1]