Provided by: perf-tools-unstable_0.0.1~20150130+git85414b0-1_all bug

NAME

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

SYNOPSIS

       kprobe [-FhHsv] [-d secs] [-p PID] 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.

       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)