Man pages sections > man8 > tpoint-perf

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

tpoint(8) System Manager's Manual tpoint(8)

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)
2014-07-20 USER COMMANDS