focal (8) tpoint-perf.8.gz

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)