1
.TH kprobe 8 "2014-07-20" "USER COMMANDS"
3
kprobe \- trace a given kprobe definition. Kernel dynamic tracing. Uses Linux ftrace.
6
[\-hv] [\-d secs] [\-p PIDs] kprobe_definition [filter]
8
This will create, trace, then destroy a given kprobe. See
9
Documentation/trace/kprobetrace.txt in the Linux kernel source for the
10
syntax of a kprobe definition.
12
WARNING: This uses kernel dynamic tracing, which can cause cause kernel panics
13
or freezes. Test, and know what you are doing, before use.
15
Also beware of feedback loops: tracing tcp functions over an ssh session,
16
or writing ext4 functions to an ext4 file system. For the former, tcp
17
trace data could be redirected to a file (as in the usage message). For
18
the latter, trace to the screen or a different file system.
20
Since this uses ftrace, only the root user can use this tool.
22
FTRACE and KPROBES CONFIG, which you may already have enabled and available on
27
Set the duration of tracing, in seconds. Trace output will be buffered and
28
printed at the end. This also reduces overheads by buffering in-kernel,
29
instead of printing events as they occur.
31
The ftrace buffer has a fixed size per-CPU (see
32
/sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing,
33
try increasing that size.
42
Show the kprobe format file only (do not trace), identifying possible variables
43
for use in a custom filter.
46
Only trace kernel functions when this process ID is on-CPU.
49
A full kprobe definition, as documented by Documentation/trace/kprobetrace.txt
50
in the Linux kernel source. See the EXAMPLES section.
53
An ftrace filter definition.
55
These examples may need modification to match your kernel version's function
56
names and platform's register usage. If using platform specific registers
57
becomes too painful in practice, consider a kernel debuginfo-based tracer,
58
which can trace variables names instead. For example, perf_events.
60
Trace do_sys_open() return values:
62
.B kprobe 'r:myopen do_sys_open $retval'
64
Trace do_sys_open() file mode:
66
.B kprobe 'p:myopen do_sys_open mode=%cx:u16'
68
Trace do_sys_open() file mode for PID 81:
70
.B kprobe -p 81 'p:myopen do_sys_open mode=%cx:u16'
72
Trace do_sys_open() with filename string:
74
.B kprobe 'p:myopen do_sys_open filename=+0(%si):string'
76
Trace do_sys_open() for filenames ending in "stat"
78
.B kprobe 'p:myopen do_sys_open fn=+0(%si):string' 'fn ~ """*stat"""'
80
The output format depends on the kernel version, and headings can be printed
81
using \-H. The format is the same as the ftrace function trace format, described
82
in the kernel source under Documentation/trace/ftrace.txt.
87
The process name (which could include dashes), a dash, and the process ID.
90
The CPU ID, in brackets.
93
Kernel state flags. For example, on Linux 3.16 these are for irqs-off,
94
need-resched, hardirq/softirq, and preempt-depth.
97
Time of event, in seconds.
100
Kernel function name.
102
This can generate a lot of trace data quickly, depending on the
103
frequency of the traced events. Such data will cause performance overheads.
104
This also works without buffering by default, printing function events
105
as they happen (uses trace_pipe), context switching and consuming CPU to do
106
so. If needed, you can try the "\-d secs" option, which buffers events
107
instead, reducing overhead. If you think the buffer option is losing events,
108
try increasing the buffer size (buffer_size_kb).
110
It's a good idea to use funccount(8) first, which is lower overhead, to
111
help you select which functions you may want to trace using kprobe(8).
113
This is from the perf-tools collection:
115
https://github.com/brendangregg/perf-tools
117
Also look under the examples directory for a text file containing example
118
usage, output, and commentary for this tool.
122
Unstable - in development.
126
functrace(8), funccount(8)
added
removed
man/man8/kprobe.8
