ustat(8)

🎀 USTAT(8) 🎀 System Manager's Manual

✨ NAME ✨

ustat, javastat, nodestat, perlstat, phpstat, pythonstat, rubystat, tclstat — activity stats from high-level languages 💖

🦋 SYNOPSIS 🦋

javastat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
[-d] [interval [count]]
nodestat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
[-d] [interval [count]]
perlstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
[-d] [interval [count]]
phpstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d]
[interval [count]]
pythonstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
[-d] [interval [count]]
rubystat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
[-d] [interval [count]]
tclstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d]
[interval [count]]
ustat [-l {java,node,perl,php,python,ruby,tcl}] [-C] [-S
{cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval
[count]]

💅 DESCRIPTION 💅

okay so this is basically "top" but for high-level language events 🔥 we're talking garbage collections, exceptions, thread creations, object allocations, method calls, and more, bestie. 😭 The events get aggregated for each process and printed in a top-like table, which you can sort by different fields. Heads up though: not every language runtime gives you the same set of details 💀

This uses in-kernel eBPF maps to store per-process summaries, which is so efficient it's giving 🧚

This tool relies on USDT probes embedded in a bunch of high-level languages, like Java, Node, Perl, PHP, Python, Ruby, and Tcl ✨ It needs 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, some probes aren't enabled by default, but you can turn them on by running the Java process with the -XX:+ExtendedDTraceProbes flag. For PHP processes, the environment variable USE_ZEND_DTRACE must be set to 1. 🌸

Newly-created processes only get traced at the next interval. If you run this with a short interval (say, 1-5 seconds), it should be virtually unnoticeable 🫶 For longer intervals, you might miss processes that started and terminated during the interval window 🙈

Since this uses BPF, only the root user can use this tool. Not me being strict, it's just the rule 👑

---

🧚 REQUIREMENTS 🧚

CONFIG_BPF and bcc.

🌈 OPTIONS 🌈

• -l {java,node,perl,php,python,ruby,tcl} — the language you want to trace. By default, all languages get traced 💜
• -C — don't clear the screen between updates 🍓
• -S {cload,excp,gc,method,objnew,thread} — sort the output by the field you pick 💅
• -r MAXROWS — don't print more than this many rows 🎀
• -d — prints the resulting BPF program, for debugging purposes 🔥
• interval — the gap between updates, in seconds ⭐
• count — how many interval summaries you get 🦋

🍓 EXAMPLES 🍓

Summarize activity in high-level languages, 1 second refresh:

# ustat

Don't clear the screen, and only show the top 8 rows:

# ustat -Cr 8

5 second summaries, 10 times only:

# ustat 5 10

🔮 FIELDS 🔮

• loadavg — the contents of /proc/loadavg ✨
• PID — process ID 🆔
• CMDLINE — the process command line. Honestly the second and following arguments often give you a hint as to which application is being run 👀
• METHOD/s — count of method invocations during the interval 💜
• GC/s — count of garbage collections during the interval 🗑️
• OBJNEW/s — count of objects allocated during the interval 🌸
• CLOAD/s — count of classes loaded during the interval 📦
• EXC/s — count of exceptions thrown during the interval 💀
• THR/s — count of threads created during the interval 🧵

🫧 OVERHEAD 🫧

⚠️ Real talk: when you use this with high-frequency events, like method calls, you can expect a very significant slow-down 😭

That said, a lot of the high-level languages covered here already have a pretty high per-method invocation cost, especially in interpreted mode, so it's not all on this tool 🙈 For the lower-frequency events, like garbage collections or thread creations, the overhead should not be significant 💖 Specifically, when probing Java processes without the -XX:+ExtendedDTraceProbes flag, the most expensive probes aren't emitted, so the overhead should be acceptable ✨

🌐 SOURCE 🌐

This is from bcc. 🐝

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file containing example usage, output, and commentary for this tool 📚

💻 OS 💻

Linux 🐧

🧪 STABILITY 🧪

Unstable - in development. 🚧

👩‍💻 AUTHOR 👩‍💻

Sasha Goldshtein 👑

🔗 SEE ALSO 🔗

trace(8), argdist(8), tplist(8) 💜

---

Okay bestie, that's the whole page! 💖 It's the ustat(8) manual from the USER COMMANDS section, dated 2018-10-09 🎀 Now go trace some garbage collections and slay your way through your Unix era 😭✨🫶