]> git.proxmox.com Git - mirror_ubuntu-zesty-kernel.git/blame - Documentation/trace/kprobetrace.txt
Merge branch 'for-4.2' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq
[mirror_ubuntu-zesty-kernel.git] / Documentation / trace / kprobetrace.txt
CommitLineData
77b44d1b
MH
1 Kprobe-based Event Tracing
2 ==========================
d8ec9185
MH
3
4 Documentation is written by Masami Hiramatsu
5
6
7Overview
8--------
77b44d1b
MH
9These 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.
d8ec9185 14
9c33c512 15To enable this feature, build your kernel with CONFIG_KPROBE_EVENT=y.
d8ec9185 16
77b44d1b
MH
17Similar 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.
d8ec9185
MH
21
22
23Synopsis of kprobe_events
24-------------------------
61424318
MH
25 p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe
26 r[:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe
df3ab708 27 -:[GRP/]EVENT : Clear a probe
d8ec9185 28
f52487e9 29 GRP : Group name. If omitted, use "kprobes" for it.
2fba0c88 30 EVENT : Event name. If omitted, the event name is generated
61424318
MH
31 based on SYM+offs or MEMADDR.
32 MOD : Module name which has given SYM.
33 SYM[+offs] : Symbol+offset where the probe is inserted.
2fba0c88 34 MEMADDR : Address where the probe is inserted.
d8ec9185 35
2fba0c88 36 FETCHARGS : Arguments. Each probe can have up to 128 args.
2e06ff63
MH
37 %REG : Fetch register REG
38 @ADDR : Fetch memory at ADDR (ADDR should be in kernel)
d8ec9185 39 @SYM[+|-offs] : Fetch memory at SYM +|- offs (SYM should be a data symbol)
2e06ff63
MH
40 $stackN : Fetch Nth entry of stack (N >= 0)
41 $stack : Fetch stack address.
14640106
MH
42 $retval : Fetch return value.(*)
43 +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**)
93ccae7a
MH
44 NAME=FETCHARG : Set NAME as the argument name of FETCHARG.
45 FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types
1ff511e3
MH
46 (u8/u16/u32/u64/s8/s16/s32/s64), "string" and bitfield
47 are supported.
d8ec9185 48
14640106
MH
49 (*) only for return probe.
50 (**) this is useful for fetching a field of data structures.
d8ec9185 51
1ff511e3
MH
52Types
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
d8ec9185
MH
65
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
77b44d1b
MH
70name 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'.
d8ec9185
MH
73
74enabled:
75 You can enable/disable the probe by writing 1 or 0 on it.
76
77format:
eca0d916 78 This shows the format of this probe event.
d8ec9185
MH
79
80filter:
eca0d916 81 You can write filtering rules of this event.
d8ec9185 82
e08d1c65
MH
83id:
84 This shows the id of this probe event.
d8ec9185 85
77b44d1b 86
cd7e7bd5
MH
87Event 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
d8ec9185
MH
95Usage examples
96--------------
97To add a probe as a new event, write a new definition to kprobe_events
98as below.
99
580d9e00 100 echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events
d8ec9185
MH
101
102 This sets a kprobe on the top of do_sys_open() function with recording
14640106
MH
1031st 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.
d8ec9185 108
580d9e00 109 echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events
d8ec9185
MH
110
111 This sets a kretprobe on the return point of do_sys_open() function with
99329c44 112recording return value as "myretprobe" event.
d8ec9185
MH
113 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
ec3a9039 118ID: 780
d8ec9185 119format:
ec3a9039
MH
120 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;
ec3a9039
MH
124
125 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;
131
132
133print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
134REC->dfd, REC->filename, REC->flags, REC->mode
d8ec9185 135
eca0d916 136 You can see that the event has 4 arguments as in the expressions you specified.
d8ec9185
MH
137
138 echo > /sys/kernel/debug/tracing/kprobe_events
139
5a0d9050
MH
140 This clears all probe points.
141
df3ab708
MK
142 Or,
143
144 echo -:myprobe >> kprobe_events
145
146 This clears probe points selectively.
147
5a0d9050
MH
148 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.
d8ec9185
MH
155
156 cat /sys/kernel/debug/tracing/trace
157# tracer: nop
158#
159# TASK-PID CPU# TIMESTAMP FUNCTION
160# | | | | |
6e9f23d1 161 <...>-1447 [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flags=8000 mode=0
2e06ff63 162 <...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe
6e9f23d1 163 <...>-1447 [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6
2e06ff63 164 <...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
6e9f23d1 165 <...>-1447 [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 flags=98800 mode=10
2e06ff63 166 <...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
d8ec9185
MH
167
168
6e9f23d1 169 Each line shows when the kernel hits an event, and <- SYMBOL means kernel
d8ec9185
MH
170returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
171returns from do_sys_open to sys_open+0x1b).
172