---
name: "kprobe"
section: "8"
platform: "linux"
package: "perf-tools-unstable"
version: "0.0.1~20140723+git942be0b-4"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/kprobe"
---

# kprobe(8)

trace a given kprobe definition. Kernel dynamic tracing. Uses Linux ftrace.

## NAME

kprobe - trace a given kprobe definition. Kernel dynamic tracing. Uses Linux ftrace.

## SYNOPSIS

**kprobe** \[-hv\] \[-d secs\] \[-p PIDs\] kprobe\_definition \[filter\]

## DESCRIPTION

This will create, trace, then destroy a given kprobe. See Documentation/trace/kprobetrace.txt in the Linux kernel source for the syntax of a kprobe definition.

WARNING: This uses kernel dynamic tracing, which can cause cause kernel panics or freezes. Test, and know what you are doing, before use.

Also beware of feedback loops: tracing tcp functions over an ssh session, or writing ext4 functions to an ext4 file system. For the former, tcp trace data could be redirected to a file (as in the usage message). For the latter, trace to the screen or a different file system.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS

FTRACE and KPROBES CONFIG, which you may already have enabled and available on recent kernels.

## OPTIONS

- \-d seconds

  Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur.

  The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer\_size\_kb). If you think events are missing, try increasing that size.

- \-h

  Print usage message.

- \-H

  Print column headers.

- \-v

  Show the kprobe format file only (do not trace), identifying possible variables for use in a custom filter.

- \-p PID

  Only trace kernel functions when this process ID is on-CPU.

- kprobe\_definition

  A full kprobe definition, as documented by Documentation/trace/kprobetrace.txt in the Linux kernel source. See the EXAMPLES section.

- filter

  An ftrace filter definition.

## EXAMPLES

These examples may need modification to match your kernel version's function names and platform's register usage. If using platform specific registers becomes too painful in practice, consider a kernel debuginfo-based tracer, which can trace variables names instead. For example, perf\_events.

- Trace do\_sys\_open() return values:

  \# **kprobe 'r:myopen do\_sys\_open $retval'**

- Trace do\_sys\_open() file mode:

  \# **kprobe 'p:myopen do\_sys\_open mode=%cx:u16'**

- Trace do\_sys\_open() file mode for PID 81:

  \# **kprobe -p 81 'p:myopen do\_sys\_open mode=%cx:u16'**

- Trace do\_sys\_open() with filename string:

  \# **kprobe 'p:myopen do\_sys\_open filename=+0(%si):string'**

- Trace do\_sys\_open() for filenames ending in "stat"

  \# **kprobe 'p:myopen do\_sys\_open fn=+0(%si):string' 'fn ~ "\*stat" '**

## FIELDS

The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

- TASK-PID

  The process name (which could include dashes), a dash, and the process ID.

- CPU#

  The CPU ID, in brackets.

- \|\|\|\|

  Kernel state flags. For example, on Linux 3.16 these are for irqs-off, need-resched, hardirq/softirq, and preempt-depth.

- TIMESTAMP

  Time of event, in seconds.

- FUNCTION

  Kernel function name.

## OVERHEAD

This can generate a lot of trace data quickly, depending on the frequency of the traced events. Such data will cause performance overheads. This also works without buffering by default, printing function events as they happen (uses trace\_pipe), context switching and consuming CPU to do so. If needed, you can try the "-d secs" option, which buffers events instead, reducing overhead. If you think the buffer option is losing events, try increasing the buffer size (buffer\_size\_kb).

It's a good idea to use [funccount(8)](/funccount/8.md) first, which is lower overhead, to help you select which functions you may want to trace using [kprobe(8)](/kprobe/8.md).

## SOURCE

This is from the perf-tools collection:

-

  https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS

Linux

## STABILITY

Unstable - in development.

## AUTHOR

Brendan Gregg

## SEE ALSO

[functrace(8)](/functrace/8.md), [funccount(8)](/funccount/8.md)