functrace(8)

✨ functrace — it's giving kernel function tracing 💅

ok so bestie, welcome to functrace(8) from the System Manager's Manual. This is the one where we trace kernel function calls that match the wildcards you pick, and yeah — it runs on Linux ftrace. 👑

---

🌸 NAME 🌸

functrace — trace kernel function calls matching specified wildcards. Uses Linux ftrace. no cap, that's literally the whole job description.

---

🎀 SYNOPSIS 🎀

functrace [-hH] [-p PID] [-L TID] [-d secs] funcstring

---

🦋 DESCRIPTION 🦋

This tool is your quick little main-character shortcut to capturing the execution of kernel functions. It shows you the basic details — the process ID, the timestamp, and the calling function. it's giving receipts, honestly.

⚠️ WARNING: This uses dynamic tracing of (what can be many) kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use. Like… bestie, please know what you're doing. 😭

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. not the feedback loop sneaking up on you 💀

SEE ALSO: kprobe(8), which can dynamically trace a single function call or return, and examine CPU registers and return values. iconic of it tbh.

Since this uses ftrace, only the root user can use this tool. yes, root. the VIP section. 🔥

---

⭐ REQUIREMENTS ⭐

FTRACE CONFIG, which you may already have enabled and available on recent kernels. check it, she's probably already there 🫶

---

💖 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. the classic cry for help (affectionate).
• -H — Print column headers. give the girl some labels 💅
• -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.
• funcstring — A function name to trace, which may include file glob style wildcards ("*") at the beginning or ending of a string only. Eg, "vfs*" means match "vfs" followed by anything. beginning or ending ONLY, bestie — don't get creative with the middle 💜

---

🌈 EXAMPLES 🌈

Trace calls to do_nanosleep():

# functrace do_nanosleep

Trace calls to all kernel functions ending in "*sleep":

# functrace '*sleep'

Trace all "vfs*" kernel function calls for PID 198:

# functrace -p 198 'vfs*'

Trace all "tcp*" kernel function calls, and output to a file until Ctrl-C:

# functrace 'tcp*' > out

Trace all "tcp*" kernel function calls, output to a file, for 1 second (buffered):

# functrace -d 1 'tcp*' > out

---

🧚 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 functrace(8). do the cheap little vibe check before you commit, fr fr ✨

---

👑 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. yes there's commentary, we love a director's cut 🎀

---

🌸 OS 🌸

Linux 🐧

---

💀 STABILITY 💀

Unstable — in development. she's still cooking, be nice to her 😭

---

💜 AUTHOR 💜

Brendan Gregg — the icon, the moment, the blueprint 🫶

---

⭐ SEE ALSO ⭐

funccount(8), kprobe(8)

---

ok that's the whole page bestie, and just so you know this little beauty came out under USER COMMANDS — dated 2014-07-20 — and it's filed as functrace(8) in the manual. go trace something, love u, bye 💖✨🎀