tcptop(8)

✨ tcptop(8) — NAME ✨

okay so tcptop is literally top, but for TCP 💖 It summarizes TCP send/recv throughput by host. Top for TCP. iconic. 💅

🌸 SYNOPSIS 🌸

tcptop [-h] [-C] [-S] [-p PID] [--cgroupmap MAPPATH]
          [--mntnsmap MAPPATH] [interval] [count] [-4 | -6]

💜 DESCRIPTION 💜

bestie, this is top for TCP sessions 🦋

It summarizes TCP send/receive Kbytes by host and prints a summary that refreshes, along with other system-wide metrics. main character energy ✨

This uses dynamic tracing of kernel TCP send/receive functions, so it will need to be updated to match kernel changes. ngl that's a little bit of a chore 🙈

The traced TCP functions are usually called at a lower rate than per-packet functions, so they have lower overhead 🫶 The traced data is summarized in-kernel using a BPF map to reduce overhead even more. At very high TCP event rates the overhead may still be measurable, so check the OVERHEAD section for the tea ☕

Since this uses BPF, only the root user can use this tool. 🔥 not me trying to run it as a normal user 💀

🎀 REQUIREMENTS 🎀

You need CONFIG_BPF and bcc. 🧚

✨ OPTIONS ✨

• -h — print the USAGE message 💅
• -C — don't clear the screen 🌈
• -S — don't print the system summary line (the load averages) 🍓
• -p PID — trace this PID only 🎯
• --cgroupmap MAPPATH — trace cgroups in this BPF map only (filtered in-kernel) 🫧
• --mntnsmap MAPPATH — trace mount namespaces in this BPF map only (filtered in-kernel) 🦄
• interval — interval between updates, in seconds (default 1) ⏱️
• count — number of interval summaries (default is many) 💫
• -4 — trace the IPv4 family only 🌷
• -6 — trace the IPv6 family only 🌺

🍓 EXAMPLES 🍓

Summarize TCP throughput by active sessions, 1 second refresh:

# tcptop

Don't clear the screen (rolling output), and 5 second summaries:

# tcptop -C 5

Trace PID 181 only, and don't clear the screen:

# tcptop -Cp 181

Trace a set of cgroups only (see special_filtering.md from the bcc sources for more details):

# tcptop --cgroupmap /sys/fs/bpf/test01

Trace IPv4 family only:

# tcptop -4

Trace IPv6 family only:

# tcptop -6

🦋 FIELDS 🦋

• loadavg — the contents of /proc/loadavg 📈
• PID — process ID 🆔
• COMM — process name 🏷️
• LADDR — local address (IPv4), and TCP port 🏠
• RADDR — remote address (IPv4), and TCP port 🌍
• LADDR6 — source address (IPv6), and TCP port 🏡
• RADDR6 — destination address (IPv6), and TCP port 🗺️
• RX_KB — received Kbytes 📥
• TX_KB — transmitted Kbytes 📤

💀 OVERHEAD 💀

This traces all sends/receives in TCP, high up in the TCP/IP stack (close to the application). Those are usually called at a lower rate than per-packet functions, which keeps overhead low. It also summarizes data in-kernel to shave off even more overhead. These techniques help, but there may still be measurable overhead at high send/receive rates, eg, ~13% of one CPU at 100k events/sec. Use funccount to count the kprobes in the tool to find out this rate, since the overhead is relative to the rate. Some sample production servers tested found total TCP event rates of 4k to 15k per second, and the CPU overhead at those rates ranged from 0.5% to 2.0% of one CPU. If your send/receive rate is low (eg, <1000/sec) then the overhead is expected to be negligible. Test in a lab environment first! 🧪

🌈 SOURCE 🌈

This is from bcc.

https://github.com/iovisor/bcc

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

🫶 OS 🫶

Linux 🐧

🔥 STABILITY 🔥

Unstable, still in development 🚧

👑 AUTHOR 👑

Brendan Gregg 🙌

🧚 INSPIRATION 🧚

top(1) by William LeFebvre 💜

⭐ SEE ALSO ⭐

tcpconnect(8), tcpaccept(8) 👯

---

ttyl, the manual is cooked 🍳 this has been USER COMMANDS, bcc's tcptop(8) page, dated 2020-03-08 🎀 slay forever 💖