blob: 5f77d94598dd577aca9a9f36c9cdee13ca86fec6 [file] [log] [blame]
Masami Hiramatsu77b44d12009-11-03 19:12:47 -05001 Kprobe-based Event Tracing
2 ==========================
Masami Hiramatsud8ec9182009-08-19 21:13:57 +02003
4 Documentation is written by Masami Hiramatsu
5
6
7Overview
8--------
Masami Hiramatsu77b44d12009-11-03 19:12:47 -05009These events are similar to tracepoint based events. Instead of Tracepoint,
10this is based on kprobes (kprobe and kretprobe). So it can probe wherever
11kprobes can probe (this means, all functions body except for __kprobes
12functions). Unlike the Tracepoint based event, this can be added and removed
13dynamically, on the fly.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020014
Masami Hiramatsu77b44d12009-11-03 19:12:47 -050015To enable this feature, build your kernel with CONFIG_KPROBE_TRACING=y.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020016
Masami Hiramatsu77b44d12009-11-03 19:12:47 -050017Similar to the events tracer, this doesn't need to be activated via
18current_tracer. Instead of that, add probe points via
19/sys/kernel/debug/tracing/kprobe_events, and enable it via
20/sys/kernel/debug/tracing/events/kprobes/<EVENT>/enabled.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020021
22
23Synopsis of kprobe_events
24-------------------------
Masami Hiramatsuf52487e2009-09-10 19:53:53 -040025 p[:[GRP/]EVENT] SYMBOL[+offs]|MEMADDR [FETCHARGS] : Set a probe
26 r[:[GRP/]EVENT] SYMBOL[+0] [FETCHARGS] : Set a return probe
Motohiro KOSAKIdf3ab702010-01-18 21:35:12 -050027 -:[GRP/]EVENT : Clear a probe
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020028
Masami Hiramatsuf52487e2009-09-10 19:53:53 -040029 GRP : Group name. If omitted, use "kprobes" for it.
Masami Hiramatsu2fba0c82009-09-10 19:53:14 -040030 EVENT : Event name. If omitted, the event name is generated
31 based on SYMBOL+offs or MEMADDR.
32 SYMBOL[+offs] : Symbol+offset where the probe is inserted.
33 MEMADDR : Address where the probe is inserted.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020034
Masami Hiramatsu2fba0c82009-09-10 19:53:14 -040035 FETCHARGS : Arguments. Each probe can have up to 128 args.
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040036 %REG : Fetch register REG
37 @ADDR : Fetch memory at ADDR (ADDR should be in kernel)
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020038 @SYM[+|-offs] : Fetch memory at SYM +|- offs (SYM should be a data symbol)
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040039 $stackN : Fetch Nth entry of stack (N >= 0)
40 $stack : Fetch stack address.
Masami Hiramatsu14640102010-01-05 17:46:48 -050041 $retval : Fetch return value.(*)
42 +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**)
Masami Hiramatsu93ccae72010-04-12 13:17:08 -040043 NAME=FETCHARG : Set NAME as the argument name of FETCHARG.
44 FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types
Masami Hiramatsue09c8612010-07-05 15:54:45 -030045 (u8/u16/u32/u64/s8/s16/s32/s64) and string are supported.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020046
Masami Hiramatsu14640102010-01-05 17:46:48 -050047 (*) only for return probe.
48 (**) this is useful for fetching a field of data structures.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020049
50
51Per-Probe Event Filtering
52-------------------------
53 Per-probe event filtering feature allows you to set different filter on each
54probe and gives you what arguments will be shown in trace buffer. If an event
Masami Hiramatsu77b44d12009-11-03 19:12:47 -050055name is specified right after 'p:' or 'r:' in kprobe_events, it adds an event
56under tracing/events/kprobes/<EVENT>, at the directory you can see 'id',
57'enabled', 'format' and 'filter'.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020058
59enabled:
60 You can enable/disable the probe by writing 1 or 0 on it.
61
62format:
Masami Hiramatsueca0d912009-09-10 19:53:38 -040063 This shows the format of this probe event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020064
65filter:
Masami Hiramatsueca0d912009-09-10 19:53:38 -040066 You can write filtering rules of this event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020067
Masami Hiramatsue08d1c62009-09-10 19:53:30 -040068id:
69 This shows the id of this probe event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020070
Masami Hiramatsu77b44d12009-11-03 19:12:47 -050071
Masami Hiramatsucd7e7bd2009-08-13 16:35:42 -040072Event Profiling
73---------------
74 You can check the total number of probe hits and probe miss-hits via
75/sys/kernel/debug/tracing/kprobe_profile.
76 The first column is event name, the second is the number of probe hits,
77the third is the number of probe miss-hits.
78
79
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020080Usage examples
81--------------
82To add a probe as a new event, write a new definition to kprobe_events
83as below.
84
Motohiro KOSAKI580d9e02010-01-18 21:35:05 -050085 echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020086
87 This sets a kprobe on the top of do_sys_open() function with recording
Masami Hiramatsu14640102010-01-05 17:46:48 -0500881st to 4th arguments as "myprobe" event. Note, which register/stack entry is
89assigned to each function argument depends on arch-specific ABI. If you unsure
90the ABI, please try to use probe subcommand of perf-tools (you can find it
91under tools/perf/).
92As this example shows, users can choose more familiar names for each arguments.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020093
Motohiro KOSAKI580d9e02010-01-18 21:35:05 -050094 echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020095
96 This sets a kretprobe on the return point of do_sys_open() function with
Masami Hiramatsu99329c42009-10-07 18:27:48 -040097recording return value as "myretprobe" event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020098 You can see the format of these events via
99/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.
100
101 cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format
102name: myprobe
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500103ID: 780
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200104format:
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500105 field:unsigned short common_type; offset:0; size:2; signed:0;
106 field:unsigned char common_flags; offset:2; size:1; signed:0;
107 field:unsigned char common_preempt_count; offset:3; size:1;signed:0;
108 field:int common_pid; offset:4; size:4; signed:1;
109 field:int common_lock_depth; offset:8; size:4; signed:1;
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200110
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500111 field:unsigned long __probe_ip; offset:12; size:4; signed:0;
112 field:int __probe_nargs; offset:16; size:4; signed:1;
113 field:unsigned long dfd; offset:20; size:4; signed:0;
114 field:unsigned long filename; offset:24; size:4; signed:0;
115 field:unsigned long flags; offset:28; size:4; signed:0;
116 field:unsigned long mode; offset:32; size:4; signed:0;
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200117
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200118
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500119print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
120REC->dfd, REC->filename, REC->flags, REC->mode
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200121
Masami Hiramatsueca0d912009-09-10 19:53:38 -0400122 You can see that the event has 4 arguments as in the expressions you specified.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200123
124 echo > /sys/kernel/debug/tracing/kprobe_events
125
Masami Hiramatsu5a0d9052009-09-14 16:49:37 -0400126 This clears all probe points.
127
Motohiro KOSAKIdf3ab702010-01-18 21:35:12 -0500128 Or,
129
130 echo -:myprobe >> kprobe_events
131
132 This clears probe points selectively.
133
Masami Hiramatsu5a0d9052009-09-14 16:49:37 -0400134 Right after definition, each event is disabled by default. For tracing these
135events, you need to enable it.
136
137 echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable
138 echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable
139
140 And you can see the traced information via /sys/kernel/debug/tracing/trace.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200141
142 cat /sys/kernel/debug/tracing/trace
143# tracer: nop
144#
145# TASK-PID CPU# TIMESTAMP FUNCTION
146# | | | | |
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400147 <...>-1447 [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flags=8000 mode=0
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -0400148 <...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400149 <...>-1447 [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -0400150 <...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400151 <...>-1447 [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 flags=98800 mode=10
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -0400152 <...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200153
154
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400155 Each line shows when the kernel hits an event, and <- SYMBOL means kernel
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200156returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
157returns from do_sys_open to sys_open+0x1b).
158