ucalls(8)

✨ ucalls(8) ✨

ucalls is part of the System Manager's Manual 🎀 and it's the bestie for this job. Its manual name is ucalls(8).

💅 NAME 💅

ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls, tclcalls: summarize method calls from high-level languages and Linux syscalls ✨

🫶 SYNOPSIS 🫶

javacalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
perlcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
phpcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
pythoncalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
rubycalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
tclcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP] [-L] [-S] [-v]
[-m] pid [interval]

🦋 DESCRIPTION 🦋

okay so this tool summarizes method calls from high-level languages like Java, Perl, PHP, Python, Ruby, and Tcl 💜 It can also trace Linux system calls too, which is so iconic. Every time a method gets invoked, ucalls records the call count and, if you want, the method's execution time (latency), and then shows you a summary. Main character energy 👑

This uses in-kernel eBPF maps to store per-process summaries, so it stays efficient ⭐

Real talk, this tool relies on USDT probes that are embedded in lots of high-level languages, like Java, Perl, PHP, Python, Ruby, and Tcl. You need a runtime that's instrumented with these probes 🔥 In some cases that means building from source with a USDT-specific flag, like --enable-dtrace or --with-dtrace. For Java, method probes aren't enabled by default, so you have to start the Java process with the -XX:+ExtendedDTraceProbes flag to turn them on. For PHP processes, the environment variable USE_ZEND_DTRACE must be set to 1.

🚨 Since this uses BPF, only the root user can use this tool. No exceptions, bestie.

🎀 REQUIREMENTS 🎀

CONFIG_BPF and bcc. Make sure you've got both ✨

💖 OPTIONS 💖

• -l {java,perl,php,python,ruby,tcl} — pick the language you want to trace. If you don't give one, only syscalls get traced, and only when you also use the -S option 🌸
• -T TOP — only print the top methods, ranked by frequency or latency 🍓
• -L — collect method invocation latency (duration) 🧚
• -S — collect Linux syscalls frequency and timing 🌈
• -v — print the resulting BPF program. This is for debugging, so use it when you're investigating 🙈
• -m — print times in milliseconds. The default is microseconds, so keep that in mind 💜
• pid — the process id you want to trace 🦋
• interval — print the summary after this many seconds, then exit. By default it just waits for Ctrl+C to terminate ⭐

🌸 EXAMPLES 🌸

Trace the top 10 Ruby method calls:

# ucalls -T 10 -l ruby 1344

Trace Python method calls and Linux syscalls, including latency in milliseconds:

# ucalls -l python -mL 2020

Trace only syscalls and print a summary after 10 seconds:

# ucalls -S 788 10

🥵 OVERHEAD 🥵

Tracing individual method calls creates a considerable overhead in all high-level languages, so it's giving heavy. For languages with just-in-time compilation, like Java, the overhead can be even bigger than for interpreted languages. On the other hand, syscall tracing is typically tolerable for most processes, unless they have a very unusual rate of system calls 💅

🧚 SOURCE 🧚

This is from bcc 🎀

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file. It has example usage, output, and commentary for this tool, and it's honestly so helpful 🫶

🍓 OS 🍓

Linux 🐧

🙈 STABILITY 🙈

Unstable - in development. So it's still cooking, bestie 🍳

👑 AUTHOR 👑

Sasha Goldshtein ✨

🦋 SEE ALSO 🦋

ustat(8), argdist(8) 💜

---

Okay that's the whole tea 🫖 This page is from the System Manager's Manual and was filed under USER COMMANDS, dated 2018-10-09, as ucalls(8). Slay forever 💅🌈