blob: d0d0bb9e3e25653ce46189a046f622d207c0dbc9 [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 Hiramatsu61424312011-06-27 16:26:56 +090025 p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe
26 r[:[GRP/]EVENT] [MOD:]SYM[+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
Masami Hiramatsu61424312011-06-27 16:26:56 +090031 based on SYM+offs or MEMADDR.
32 MOD : Module name which has given SYM.
33 SYM[+offs] : Symbol+offset where the probe is inserted.
Masami Hiramatsu2fba0c82009-09-10 19:53:14 -040034 MEMADDR : Address where the probe is inserted.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020035
Masami Hiramatsu2fba0c82009-09-10 19:53:14 -040036 FETCHARGS : Arguments. Each probe can have up to 128 args.
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040037 %REG : Fetch register REG
38 @ADDR : Fetch memory at ADDR (ADDR should be in kernel)
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020039 @SYM[+|-offs] : Fetch memory at SYM +|- offs (SYM should be a data symbol)
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040040 $stackN : Fetch Nth entry of stack (N >= 0)
41 $stack : Fetch stack address.
Masami Hiramatsu14640102010-01-05 17:46:48 -050042 $retval : Fetch return value.(*)
43 +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**)
Masami Hiramatsu93ccae72010-04-12 13:17:08 -040044 NAME=FETCHARG : Set NAME as the argument name of FETCHARG.
45 FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types
Masami Hiramatsu1ff511e2011-02-04 21:52:05 +090046 (u8/u16/u32/u64/s8/s16/s32/s64), "string" and bitfield
47 are supported.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020048
Masami Hiramatsu14640102010-01-05 17:46:48 -050049 (*) only for return probe.
50 (**) this is useful for fetching a field of data structures.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020051
Masami Hiramatsu1ff511e2011-02-04 21:52:05 +090052Types
53-----
54Several types are supported for fetch-args. Kprobe tracer will access memory
55by given type. Prefix 's' and 'u' means those types are signed and unsigned
56respectively. Traced arguments are shown in decimal (signed) or hex (unsigned).
57String type is a special type, which fetches a "null-terminated" string from
58kernel space. This means it will fail and store NULL if the string container
59has been paged out.
60Bitfield is another special type, which takes 3 parameters, bit-width, bit-
61offset, and container-size (usually 32). The syntax is;
62
63 b<bit-width>@<bit-offset>/<container-size>
64
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020065
66Per-Probe Event Filtering
67-------------------------
68 Per-probe event filtering feature allows you to set different filter on each
69probe and gives you what arguments will be shown in trace buffer. If an event
Masami Hiramatsu77b44d12009-11-03 19:12:47 -050070name is specified right after 'p:' or 'r:' in kprobe_events, it adds an event
71under tracing/events/kprobes/<EVENT>, at the directory you can see 'id',
72'enabled', 'format' and 'filter'.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020073
74enabled:
75 You can enable/disable the probe by writing 1 or 0 on it.
76
77format:
Masami Hiramatsueca0d912009-09-10 19:53:38 -040078 This shows the format of this probe event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020079
80filter:
Masami Hiramatsueca0d912009-09-10 19:53:38 -040081 You can write filtering rules of this event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020082
Masami Hiramatsue08d1c62009-09-10 19:53:30 -040083id:
84 This shows the id of this probe event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020085
Masami Hiramatsu77b44d12009-11-03 19:12:47 -050086
Masami Hiramatsucd7e7bd2009-08-13 16:35:42 -040087Event Profiling
88---------------
89 You can check the total number of probe hits and probe miss-hits via
90/sys/kernel/debug/tracing/kprobe_profile.
91 The first column is event name, the second is the number of probe hits,
92the third is the number of probe miss-hits.
93
94
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020095Usage examples
96--------------
97To add a probe as a new event, write a new definition to kprobe_events
98as below.
99
Motohiro KOSAKI580d9e02010-01-18 21:35:05 -0500100 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 +0200101
102 This sets a kprobe on the top of do_sys_open() function with recording
Masami Hiramatsu14640102010-01-05 17:46:48 -05001031st to 4th arguments as "myprobe" event. Note, which register/stack entry is
104assigned to each function argument depends on arch-specific ABI. If you unsure
105the ABI, please try to use probe subcommand of perf-tools (you can find it
106under tools/perf/).
107As this example shows, users can choose more familiar names for each arguments.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200108
Motohiro KOSAKI580d9e02010-01-18 21:35:05 -0500109 echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200110
111 This sets a kretprobe on the return point of do_sys_open() function with
Masami Hiramatsu99329c42009-10-07 18:27:48 -0400112recording return value as "myretprobe" event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200113 You can see the format of these events via
114/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.
115
116 cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format
117name: myprobe
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500118ID: 780
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200119format:
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500120 field:unsigned short common_type; offset:0; size:2; signed:0;
121 field:unsigned char common_flags; offset:2; size:1; signed:0;
122 field:unsigned char common_preempt_count; offset:3; size:1;signed:0;
123 field:int common_pid; offset:4; size:4; signed:1;
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200124
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500125 field:unsigned long __probe_ip; offset:12; size:4; signed:0;
126 field:int __probe_nargs; offset:16; size:4; signed:1;
127 field:unsigned long dfd; offset:20; size:4; signed:0;
128 field:unsigned long filename; offset:24; size:4; signed:0;
129 field:unsigned long flags; offset:28; size:4; signed:0;
130 field:unsigned long mode; offset:32; size:4; signed:0;
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200131
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200132
Masami Hiramatsuec3a9032010-01-05 17:46:41 -0500133print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
134REC->dfd, REC->filename, REC->flags, REC->mode
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200135
Masami Hiramatsueca0d912009-09-10 19:53:38 -0400136 You can see that the event has 4 arguments as in the expressions you specified.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200137
138 echo > /sys/kernel/debug/tracing/kprobe_events
139
Masami Hiramatsu5a0d9052009-09-14 16:49:37 -0400140 This clears all probe points.
141
Motohiro KOSAKIdf3ab702010-01-18 21:35:12 -0500142 Or,
143
144 echo -:myprobe >> kprobe_events
145
146 This clears probe points selectively.
147
Masami Hiramatsu5a0d9052009-09-14 16:49:37 -0400148 Right after definition, each event is disabled by default. For tracing these
149events, you need to enable it.
150
151 echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable
152 echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable
153
154 And you can see the traced information via /sys/kernel/debug/tracing/trace.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200155
156 cat /sys/kernel/debug/tracing/trace
157# tracer: nop
158#
159# TASK-PID CPU# TIMESTAMP FUNCTION
160# | | | | |
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400161 <...>-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 -0400162 <...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400163 <...>-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 -0400164 <...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400165 <...>-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 -0400166 <...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200167
168
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400169 Each line shows when the kernel hits an event, and <- SYMBOL means kernel
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200170returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
171returns from do_sys_open to sys_open+0x1b).
172