NAME

       tpoint - trace a given tracepoint. Static tracing. Uses Linux ftrace.

SYNOPSIS

       tpoint [-hHsv] [-d secs] [-p PID] [-L TID] tracepoint [filter]

       tpoint -l

DESCRIPTION

       This  will  enable  a given tracepoint, print events, then disable the tracepoint when the
       program ends. This is like a simple version  of  the  "perf"  command  for  printing  live
       tracepoint  events  only.  Wildcards  are  currently  not  supported.   If  for any reason
       tpoint(8) is insufficient, use the more powerful  perf  command  for  tracing  tracepoints
       instead.

       Beware  of  feedback  loops:  tracing  tcp  functions over an ssh session, or writing ext4
       events 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 CONFIG and tracepoints, 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.

       -l     List tracepoints only.

       -s     Print kernel stack traces after each event.

       -v     Show the tpoint 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.

       tracepoint
              A tracepoint name. Eg, block:block_rq_issue. See the EXAMPLES section.

       filter An ftrace filter definition.

EXAMPLES

       List tracepoints containing "open":
              # tpoint -l | grep open

       Trace open() syscall entry:
              # tpoint syscalls:sys_enter_open

       Trace open() syscall entry, showing column headers:
              # tpoint -H syscalls:sys_enter_open

       Trace block I/O issue:
              # tpoint block:block_rq_issue

       Trace block I/O issue with stack traces:
              # tpoint -s block:block_rq_issue

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

       Before using tpoint(8), you can use perf_events to  count  the  rate  of  events  for  the
       tracepoint of interest, to gauge overhead. For example:

       perf stat -e block:block_rq_issue -a sleep 5

       That counts the occurrences of the block:block_rq_issue tracepoint for 5 seconds.

       Also  consider  using perf_events, which manages buffers differently and more efficiently,
       for higher frequency applications.

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), perf(1)