tcpcong(8)

💅 tcpcong(8) — the manual page, but make it make sense ✨

okay bestie, so this is a page from the System Manager's Manual — it's tcpcong, and it's about to become your new fave little chaos-gremlin of a tool 🦋

---

🌸 NAME 🌸

tcpcong — measure how long tcp sockets sit in each congestion state. it uses Linux eBPF/bcc, no cap 💅

---

⭐ SYNOPSIS ⭐

tcpcong [-h] [-T] [-L] [-R] [-u] [-d] [interval] [outputs]

---

🎀 DESCRIPTION 🎀

so this tool measures the congestion control status duration for tcp sockets, and then prints you a lil summary of how long tcp lingered in each congestion state, plus the total number of state changes. it's giving observability 👑

it works by dynamically tracing the kernel tcp congestion control status updating functions — which means, heads up, if the kernel changes, the tool will need to be updated to match. keep that in mind, fr fr.

the traced functions only get called when there's an actual congestion state update, so the overhead is lowkey tiny. they also use a BPF map to stash the traced data and keep the overhead down even more — peep the OVERHEAD section if you want the deets. and since this uses BPF, only the root user can use this tool 🙈 (sorry bestie, root only, no cap).

---

🫶 REQUIREMENTS 🫶

• CONFIG_BPF
• bcc

that's it. that's the list. 🍓

---

✨ OPTIONS ✨

• -h — prints the usage message. your classic cry-for-help flag 😭
• -T — adds a timestamp column. time-stamped slay ⏰
• -L — specify a local tcp port range.
• -R — specify a remote tcp port range.
• -u — output in microseconds.
• -d — show the congestion status duration distribution as histograms. pretty little bars, iconic 🌈

---

🔥 EXAMPLES 🔥

show all tcp sockets congestion status duration until you hit Ctrl+C:

# tcpcongestdura

show all tcp sockets congestion status duration every 1 second, 10 times:

# tcpcong 1 10

show only local port 3000-3006 congestion status duration every 1 second:

# tcpcong -L 3000-3006 1

show only remote port 5000-5005 congestion status duration every 1 second:

# tcpcong -R 5000-5005 1

show 1 second summaries, printed in microseconds, with timestamps:

# tcpcong -uT 1

show all tcp sockets congestion status duration as histograms:

# tcpcong -d

---

🦋 FIELDS 🦋

here's your decoder ring for the output columns, bestie 🎀

• LAddrPort — local ip address and tcp socket port.
• RAddrPort — remote ip address and tcp socket port.
• Open_us — total duration in open status, in microseconds.
• Dod_us — total duration in disorder status, in microseconds.
• Rcov_us — total duration in recovery status, in microseconds.
• Cwr_us — total duration in cwr status, in microseconds.
• Los_us — total duration in loss status, in microseconds.
• Open_ms — total duration in open status, in milliseconds.
• Dod_ms — total duration in disorder status, in milliseconds.
• Rcov_ms — total duration in recovery status, in milliseconds.
• Cwr_ms — total duration in cwr status, in milliseconds.
• Loss_ms — total duration in loss status, in milliseconds.
• Chgs — total number of status changes.
• usecs — range of microseconds for this bucket.
• msecs — range of milliseconds for this bucket.
• count — number of congestion status in this time range.
• distribution — ASCII representation of the distribution (the count column).

---

🧚 OVERHEAD 🧚

this traces the kernel tcp congestion status change functions. the called rate per second of these functions per socket is low (<10000), so the overhead is expected to be negligible — like, genuinely nothing, iykyk.

but listen: if you've got an application that creates thousands of tcp connections, then test and understand the overhead before you use this. no impulsive production runs, babe 💀

---

💜 SOURCE 💜

this is from bcc.

https://github.com/iovisor/bcc

also go look in the bcc distribution for a companion _examples.txt file — it's got example usage, output, and commentary for this tool. free lore drop 📚

---

👑 OS 👑

Linux 🐧

---

💀 STABILITY 💀

Unstable — in development. it's in its experimental era, we respect it 🙏

---

🌟 AUTHOR 🌟

jacky gan

---

🌈 SEE ALSO 🌈

tcpretrans(8), tcpconnect(8), tcptop(8), tcpdrop(8)

---

and that's the whole page, bestie 🫶 this lil beauty came out of the USER COMMANDS pile on 2022-01-27 — go forth, trace some congestion, and remember: root only, test your overhead, and hydrate 💖✨🎀