blob: 47aabeebbdf63ddf8c30e0b39659eefac08c58e6 [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
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020027
Masami Hiramatsuf52487e2009-09-10 19:53:53 -040028 GRP : Group name. If omitted, use "kprobes" for it.
Masami Hiramatsu2fba0c82009-09-10 19:53:14 -040029 EVENT : Event name. If omitted, the event name is generated
30 based on SYMBOL+offs or MEMADDR.
31 SYMBOL[+offs] : Symbol+offset where the probe is inserted.
32 MEMADDR : Address where the probe is inserted.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020033
Masami Hiramatsu2fba0c82009-09-10 19:53:14 -040034 FETCHARGS : Arguments. Each probe can have up to 128 args.
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040035 %REG : Fetch register REG
36 @ADDR : Fetch memory at ADDR (ADDR should be in kernel)
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020037 @SYM[+|-offs] : Fetch memory at SYM +|- offs (SYM should be a data symbol)
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040038 $stackN : Fetch Nth entry of stack (N >= 0)
39 $stack : Fetch stack address.
40 $argN : Fetch function argument. (N >= 0)(*)
41 $retval : Fetch return value.(**)
Masami Hiramatsueca0d912009-09-10 19:53:38 -040042 +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(***)
43 NAME=FETCHARG: Set NAME as the argument name of FETCHARG.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020044
45 (*) aN may not correct on asmlinkaged functions and at the middle of
46 function body.
47 (**) only for return probe.
48 (***) this is useful for fetching a field of data structures.
49
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
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040085 echo p:myprobe do_sys_open dfd=$arg0 filename=$arg1 flags=$arg2 mode=$arg3 > /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 Hiramatsueca0d912009-09-10 19:53:38 -0400881st to 4th arguments as "myprobe" event. As this example shows, users can
89choose more familiar names for each arguments.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020090
Masami Hiramatsu2e06ff62009-10-07 18:27:59 -040091 echo r:myretprobe do_sys_open $retval >> /sys/kernel/debug/tracing/kprobe_events
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020092
93 This sets a kretprobe on the return point of do_sys_open() function with
Masami Hiramatsu99329c42009-10-07 18:27:48 -040094recording return value as "myretprobe" event.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +020095 You can see the format of these events via
96/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.
97
98 cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format
99name: myprobe
Masami Hiramatsueca0d912009-09-10 19:53:38 -0400100ID: 75
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200101format:
102 field:unsigned short common_type; offset:0; size:2;
103 field:unsigned char common_flags; offset:2; size:1;
104 field:unsigned char common_preempt_count; offset:3; size:1;
105 field:int common_pid; offset:4; size:4;
106 field:int common_tgid; offset:8; size:4;
107
108 field: unsigned long ip; offset:16;tsize:8;
109 field: int nargs; offset:24;tsize:4;
Masami Hiramatsueca0d912009-09-10 19:53:38 -0400110 field: unsigned long dfd; offset:32;tsize:8;
111 field: unsigned long filename; offset:40;tsize:8;
112 field: unsigned long flags; offset:48;tsize:8;
113 field: unsigned long mode; offset:56;tsize:8;
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200114
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400115print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->ip, REC->dfd, REC->filename, REC->flags, REC->mode
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200116
117
Masami Hiramatsueca0d912009-09-10 19:53:38 -0400118 You can see that the event has 4 arguments as in the expressions you specified.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200119
120 echo > /sys/kernel/debug/tracing/kprobe_events
121
Masami Hiramatsu5a0d9052009-09-14 16:49:37 -0400122 This clears all probe points.
123
124 Right after definition, each event is disabled by default. For tracing these
125events, you need to enable it.
126
127 echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable
128 echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable
129
130 And you can see the traced information via /sys/kernel/debug/tracing/trace.
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200131
132 cat /sys/kernel/debug/tracing/trace
133# tracer: nop
134#
135# TASK-PID CPU# TIMESTAMP FUNCTION
136# | | | | |
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400137 <...>-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 -0400138 <...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400139 <...>-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 -0400140 <...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400141 <...>-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 -0400142 <...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200143
144
Masami Hiramatsu6e9f23d2009-09-10 19:53:45 -0400145 Each line shows when the kernel hits an event, and <- SYMBOL means kernel
Masami Hiramatsud8ec9182009-08-19 21:13:57 +0200146returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
147returns from do_sys_open to sys_open+0x1b).
148
149