tpoint(8)

💖 tpoint(8) — trace a given tracepoint, bestie 💖

okay so this is tpoint, from the System Manager's Manual section 8 (yes, the big-kid sysadmin section, we're in our root era 💅). Static tracing. Uses Linux ftrace. Let's get into it fr fr.

---

✨ 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 🦋

So the vibe is: this turns on a tracepoint you pick, prints the events as they happen, and then turns that tracepoint back off when the program ends. It's like the low-key baby version of the perf command, but only for printing live tracepoint events. Wildcards are not supported right now (sorry bestie, no * magic today). And if for literally any reason tpoint(8) isn't giving enough, go use the way more powerful perf command for tracing tracepoints instead. no cap.

🚨 Beware of feedback loops, for real. Tracing tcp functions over an ssh session? Yeah that's a loop. Writing ext4 events to an ext4 file system? Also a loop. For the tcp situation you can redirect the tcp trace data to a file (like the usage message shows). For the ext4 situation, trace to the screen or to a different file system. don't do a chaos, bestie. 😭

And since this uses ftrace, only the root user can use this tool. periodt. 👑

---

🎀 REQUIREMENTS 🎀

FTRACE CONFIG and tracepoints — which you may already have enabled and available on recent kernels. you might already be that girl and not even know it ✨

---

💅 OPTIONS 💅

• -d seconds — sets how long you trace, in seconds. The trace output gets buffered and printed at the end. This also lowkey reduces overheads by buffering in-kernel instead of printing events as they occur.

heads up: the ftrace buffer has a fixed size per-CPU (check /sys/kernel/debug/tracing/buffer_size_kb). If you think events are going missing, try bumping that size up. 🔥

• -h — print the 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 (no tracing), so you can spot possible variables to use in a custom filter. iykyk 👀
• -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 your 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, fast, depending on how frequently the traced events fire. And that data will cause performance overheads, no cap. Also, by default it works without buffering — printing function events as they happen (uses trace_pipe), context switching and eating CPU to do it. If you need to, try the -d secs option, which buffers events instead and reduces overhead. And if you think the buffer option is losing events, try increasing the buffer size (buffer_size_kb). 🫶

Before you even use tpoint(8), you can use perf_events to count the rate of events for the tracepoint you're curious about, just to gauge the overhead. Like:

perf stat -e block:block_rq_issue -a sleep 5

That counts the occurrences of the block:block_rq_issue tracepoint for 5 seconds. cute, right?

Also consider using perf_events, which manages buffers differently and more efficiently, for higher frequency applications. main character energy tbh. 👑

---

🧚 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. (she's still growing, okay? we support her 💜)

---

💖 AUTHOR 💖

Brendan Gregg

---

👑 SEE ALSO 👑

functrace(8), funccount(8), perf(1)

---

okay that's the whole page bestie, go trace something iconic ✨

sign-off time: this little baddie comes from the USER COMMANDS crew and got her glow-up on 2014-07-20, still stamped as tpoint(8) forever 💅🦋💜