tcpcong(8)

💖 tcpcong(8) 💖

✨ NAME ✨

okay so tcpcong is the tool that measures how long TCP sockets hang out in each congestion control state 💅 It's built on Linux eBPF/bcc, so it's giving low-level energy 🔥

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

bestie, this tool tracks how long TCP sockets spend in each congestion control status, then prints a summary of those durations plus the total number of state changes. ✨ Main character energy, fr fr.

It works by dynamically tracing the kernel functions that update TCP congestion control status. Those functions can change between kernel versions, so this tool will need updating to match kernel changes 🙈

The traced functions only fire when the congestion state actually updates, so the overhead is lowkey tiny 🫶 It also stores the traced data in a BPF map to keep things light. Check the OVERHEAD section for the full tea ☕ And since this runs on BPF, only the root user can use it 🔐

🧩 REQUIREMENTS 🧩

You need CONFIG_BPF enabled in your kernel, plus bcc installed 🌸

💅 OPTIONS 💅

• -h — Pulls up the usage message 📖
• -T — Adds a timestamp column 🕰️
• -L — Lets you pick a local TCP port range 🎯
• -R — Lets you pick a remote TCP port range 🌍
• -u — Prints everything in microseconds 🔬
• -d — Shows the congestion status duration distribution as histograms 📊

🍓 EXAMPLES 🍓

Show all TCP sockets' congestion status durations until you hit Ctrl-C 🛑

# tcpcongestdura

Show all TCP sockets' congestion status durations every 1 second, 10 times 🔁

# tcpcong 1 10

Show only local ports 3000-3006 every 1 second 🎯

# tcpcong -L 3000-3006 1

Show only remote ports 5000-5005 every 1 second 🌍

# tcpcong -R 5000-5005 1

Show 1 second summaries in microseconds, with timestamps ⏱️

# tcpcong -uT 1

Show all TCP sockets' congestion status durations as histograms 📊

# tcpcong -d

📋 FIELDS 📋

• LAddrPort — the local IP address and TCP socket port 🏠
• RAddrPort — the remote IP address and TCP socket port 🌐
• Open_us — total time spent in the open status, in microseconds 🌞
• Dod_us — total time spent in the disorder status, in microseconds 🌀
• Rcov_us — total time spent in the recovery status, in microseconds 🩹
• Cwr_us — total time spent in the cwr status, in microseconds 🌊
• Los_us — total time spent in the loss status, in microseconds 💔
• Open_ms — total time spent in the open status, in milliseconds 🌞
• Dod_ms — total time spent in the disorder status, in milliseconds 🌀
• Rcov_ms — total time spent in the recovery status, in milliseconds 🩹
• Cwr_ms — total time spent in the cwr status, in milliseconds 🌊
• Loss_ms — total time spent in the loss status, in milliseconds 💔
• Chgs — total number of status changes 🔄
• usecs — the microsecond range for this bucket 🔬
• msecs — the millisecond range for this bucket ⏳
• count — how many congestion statuses landed in this time range 🔢
• distribution — an ASCII picture of the distribution (based on the count column) 📊

🌙 OVERHEAD 🌙

This traces the kernel's TCP congestion status change functions. Those functions get called at a low rate per socket (under 10000 calls per second), so the overhead is expected to be negligible 🫧

⚠️ If your app is going to create thousands of TCP connections, test it and understand the overhead before you use this tool in production, bestie 😭

🌐 SOURCE 🌐

This comes from bcc 🐝

https://github.com/iovisor/bcc

Also check out the companion _examples.txt file in the bcc distribution. It has example usage, output, and commentary for this tool 📚

💻 OS 💻

Linux 🐧

🧪 STABILITY 🧪

Unstable — it's still in development 🚧

👩‍💻 AUTHOR 👩‍💻

jacky gan 💜

🔗 SEE ALSO 🔗

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

---

🌸 That's the tea, bestie: tcpcong(8) from the USER COMMANDS section, dated 2022-01-27 💖