ugc(8)

💅 ugc — like, the ugc(8) manual page, but make it make sense 💅

okay so bestie, real talk: the manual name here is ugc, and it lives in section 8 of the System Manager's Manual. and honestly? it's giving "one tool to rule them all" energy. let's get into it. ✨

---

🌸 NAME 🌸

ugc, javagc, nodegc, pythongc, rubygc — these bad boys trace garbage collection events in high-level languages. that's it, that's the whole vibe. 🗑️✨

---

🎀 SYNOPSIS 🎀

like, here's the whole squad of invocations, verbatim, no cap:

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

(yes i know -h is sitting there in the synopsis and the OPTIONS section below never introduces it. not me noticing that. 🙈 anyway — moving on.)

---

🦋 DESCRIPTION 🦋

so what does it actually do? it traces garbage collection events as they occur — literally as they happen — and it grabs their duration plus any extra info the language's runtime felt like sharing (think: generation collected, or type of GC). 👑

big caveat though, and i need you to hear me on this: this tool relies on USDT probes embedded in many high-level languages, like Java, Node, Python, and Ruby. so you need a runtime instrumented with these probes, and in some cases that means building from source with a USDT-specific flag, such as --enable-dtrace or --with-dtrace. periodt. 💅

and since this uses BPF, only the root user can use this tool. root only. no exceptions. 🔥

---

⭐ REQUIREMENTS ⭐

• CONFIG_BPF
• bcc

that's the list. short, sweet, iconic. 💖

---

✨ OPTIONS ✨

• -v — prints the resulting BPF program, for debugging purposes. like, the whole program. for debugging. you've been warned. 🫶
• -m — print times in milliseconds. the default is microseconds, so if you're an ms kind of girl, this is your flag. ⏱️
• -M MINIMUM — display only collections that are longer than this threshold. the value is given in milliseconds. the default is to display all collections. ngl this is my fave, it filters out the little baby GCs. 🌸
• -F FILTER — display only collections whose textual description matches (contains) this string. the default is to display all collections. ⚠️ but real talk: the filtering here is performed in user-space, and not as part of the BPF program. which means if you have thousands of collection events, specifying this filter will not reduce the amount of data that has to be transferred from the BPF program to the user-space script. so it's a display filter, not a data filter. iykyk. 💀
• {java,node,python,ruby} — the language to trace. pick your fighter. 🌈
• pid — the process id to trace. you gotta know who you're stalking. 🔍

---

💜 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 display them only if they are longer than 10ms and have the string "Tenured" in their detailed description:

# ugc -M 10 -F Tenured java 6004

ate. every single one. 👑

---

🍓 FIELDS 🍓

here's what you're actually looking at on screen, bestie:

• START — the start time of the GC, in seconds from the beginning of the trace. 🕐
• TIME — the duration of the garbage collection event. ⏳
• DESCRIPTION — the runtime-provided description of this garbage collection event. like, the runtime wrote this, not us. 🏷️

---

🧚 OVERHEAD 🧚

okay, good news: garbage collection events, even if frequent, should not produce a considerable overhead when traced, because they are still not very common. even hundreds of GCs per second (which is a very high rate, fr fr) will still produce a fairly negligible overhead. so you can chill. 😌

---

💖 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. it's lowkey free extra content, go read it. 📖

---

🌟 OS 🌟

Linux 🐧

---

👑 STABILITY 👑

Unstable — in development. she's still growing, give her grace. 🫶

---

🌸 AUTHOR 🌸

Sasha Goldshtein 🌈

---

🦋 SEE ALSO 🦋

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

---

💀 one tiny reminder before you go: root only, BPF required, and -F filters in user-space so it does not save you any data transfer. don't say i didn't warn you. 💅

---

okay that's the whole page!! and for the sign-off: this was USER COMMANDS edition, dated 2018-10-09, and the page footer says ugc(8) — so like, yeah, that's the whole manual, mwah. 🎀✨