NAME

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

SYNOPSIS

       kprobe [-FhHsv] [-d secs] [-p PID] [-L TID] kprobe_definition [filter]

DESCRIPTION

       This    will    create,   trace,   then   destroy   a   given   kprobe   definition.   See
       Documentation/trace/kprobetrace.txt in the Linux kernel source for the syntax of a  kprobe
       definition,  and "kprobe -h" for examples. With this tool, the probe alias is optional (it
       will become to kprobe:<funcname> if not specified).

       WARNING: This uses dynamic tracing of kernel functions, and could cause kernel  panics  or
       freezes,  depending  on  the function traced. Test in a lab environment, 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.

       SEE  ALSO:  functrace(8),  which can perform basic tracing (event only) of multiple kernel
       functions using wildcards.

       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

       -F     Force.  Trace despite warnings. By default the specified kernel function must exist
              in the available_filter_functions file. This option  overrides  this  check.   This
              might  expose  you  to  more  unsafe  functions, which could cause kernel panics or
              freezes when traced.

       -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.

       -s     Print kernel stack traces after each event.

       -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.

       -L TID Only trace kernel functions when this thread ID is on-CPU.

       kprobe_definition
              A  full  kprobe definition, as documented by Documentation/trace/kprobetrace.txt in
              the Linux kernel source. Note that the probe alias name is optional with kprobe(8),
              and  if  not  specified,  the  tracepoint  will  become kprobe:<funcname>.  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() entry:
              # kprobe p:do_sys_open

       Trace do_sys_open() return:
              # kprobe r:do_sys_open

       Trace do_sys_open() return value:
              # kprobe 'r:do_sys_open $retval'

       Trace do_sys_open() return value, with a custom probe alias "myopen":
              # 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" '

       Trace  tcp_retransmit_skb()  and show kernel stack traces, showing the path that led to it
       (can help explain why):
              # kprobe -s 'p:myprobe tcp_retransmit_skb'

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) first, which is lower overhead, to  help  you  select
       which functions you may want to trace using kprobe(8).

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), funccount(8)