ugc(8)

✨ ugc(8) — System Manager's Manual ✨

🦋 NAME 🦋

okay so ugc is the bestie who knows every garbage collection event in a high-level language 🗑️✨ The tool goes by four names: ugc, javagc, nodegc, pythongc, and rubygc. Its whole job is to trace garbage collection events, aka Trace garbage collection events in high-level languages. 💅

💖 SYNOPSIS 💖

javagc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
nodegc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
pythongc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
rubygc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
ugc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] [-l {java,node,python,ruby}]
pid

🌸 DESCRIPTION 🌸

okay so this traces garbage collection events as they happen 😭 You get the duration of each one, plus any extra info the language's runtime hands over, like which generation got collected or what kind of GC it was. Main character energy, literally. ✨

This tool runs on USDT probes that are baked into lots of high-level languages, like Java, Node, Python, and Ruby 🧚 The catch is that your runtime has to be built with these probes turned on. Sometimes that means compiling from source with a USDT-specific flag, like "--enable-dtrace" or "--with-dtrace". Not me being picky, it's just how it works 🙈

🚨 Since this uses BPF, only the root user can use this tool. No sneaking in as a regular user, bestie 🔐

🎀 REQUIREMENTS 🎀

You'll need CONFIG_BPF and bcc. 🔧

👑 OPTIONS 👑

• -h — Pulls up the help text. (This one isn't in the original options list, so I'm leaving it as the synopsis shows it. ✨)
• -v — Prints the resulting BPF program so you can debug. Super useful when things go sideways 🐛
• -m — Shows times in milliseconds instead of the default microseconds 🍓
• -M MINIMUM — Only shows collections that run longer than this threshold. The value is in milliseconds. By default, you get every collection, no filter, full vibes 💜
• -F FILTER — Only shows collections whose text description contains this string. Default is showing all of them. ⚠️ Heads up: this filtering happens in user-space, not inside the BPF program. So if you've got thousands of collection events, using this filter won't shrink the amount of data sent from the BPF program to the user-space script. It's giving "filter after the fact" 🙃
• {java,node,python,ruby} — The language you want to trace 🌈
• pid — The process id you want to trace 🆔

🍓 EXAMPLES 🍓

Trace garbage collections in a specific Node process:

# ugc node 148

Trace garbage collections in a specific Java process and print GC times in milliseconds:

# ugc -m java 6004

Trace garbage collections in a specific Java process, and only display them if they're longer than 10ms and have the string "Tenured" in their detailed description:

# ugc -M 10 -F Tenured java 6004

🧚 FIELDS 🧚

• START — The start time of the GC, measured in seconds from the beginning of the trace ⏱️
• TIME — How long the garbage collection event took ⏳
• DESCRIPTION — The runtime's own description of this GC event 📝

💅 OVERHEAD 💅

ngl, the overhead is lowkey tiny. GC events, even when they're frequent, shouldn't cause a big hit when you trace them, because they're still not super common. Even hundreds of GCs per second (which is a very high rate) will still produce a pretty negligible overhead. Iconic. 🫶

🌈 SOURCE 🌈

This comes from bcc 🦋 You can find it at:

https://github.com/iovisor/bcc

Also check the bcc distribution for a companion _example.txt file. It has example usage, output, and commentary for this tool, so it's basically a cheat sheet 📚

🫧 OS 🫧

Linux 🐧

🙈 STABILITY 🙈

Unstable, still in development 🚧 Not ready for prime time yet, so keep that in mind 💀

💜 AUTHOR 💜

Sasha Goldshtein 🌟

✨ SEE ALSO ✨

trace(8), ustat(8), uobjnew(8) 🔗

---

💖 Okay bestie, that's the whole tea! This page is from the USER COMMANDS collection, dated 2018-10-09, and it's all about ugc(8) ✨ Go trace some garbage and slay 💅🎀