tcpretrans.bt(8)

📦
version 0.27.0 · 4 versions
, in alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

✨ tcpretrans.bt — the manual page, but make it a group chat ✨

okay bestie, gather round 💖 this is tcpretrans.bt, and it lives in section 8 of the manual (System Manager's Manual, so you know it's the cool sysadmin section 💅).

🌸 NAME 🌸

tcpretrans.bt — trace or count TCP retransmits. Uses Linux bpftrace/eBPF. no cap, that's the whole vibe ✨

🦋 SYNOPSIS 🦋

tcpretrans.bt

that's it. that's the whole invocation. she's lowkey minimal 🎀

💜 DESCRIPTION 💜

So here's the tea, bestie: this thing traces TCP retransmits, and it shows you the address, the port, and the TCP state info, and sometimes the PID — although usually not, because retransmits are usually sent by the kernel on timeouts. so the PID field is giving "we tried" energy 😭

To keep overhead very low, it only traces the TCP retransmit functions. It does not trace every packet like tcpdump(8) or a packet sniffer would. it's not doing all that. it's doing one job and slaying it 💅

Optionally — and this part is iconic — it can count retransmits over a user signalled interval to spot potentially dropping network paths the flows are traversing. iykyk, that's your network being shady and this tool catching it in 4K 📸

This uses dynamic tracing of the kernel tcp_retransmit_skb() and tcp_send_loss_probe() functions, and will need to be updated to match kernel changes to these functions. fr fr, kernel moves, this tool has to move with it 🫶

⚠️ Since this uses BPF, only the root user can use this tool. not root? not today. sorry bestie 💀

🌈 REQUIREMENTS 🌈

  • CONFIG_BPF and bcc.
  • CONFIG_BPF and bpftrace.

both flavors listed, both valid, we don't gatekeep here 👑

🍓 EXAMPLES 🍓

Trace TCP retransmits:

# tcpretrans.bt

look at her go ✨ that # is doing heavy lifting btw, that's your root prompt, that's the whole point 🌸

🧚 FIELDS 🧚

  • TIME — Time of the call, in HH:MM:SS format. clock in, bestie ⏰
  • PID — Process ID that was on-CPU. This is less useful than it might sound, as it may usually be 0, for the kernel, for timer-based retransmits. yeah. it's giving mostly-zeros 😭
  • LADDR:LPORT — Local IP address and local port. your side of the convo 💖
  • RADDR:RPORT — Remote IP address and remote port. their side 👀
  • STATE — TCP session state. the situationship status, but for sockets 🌸

🔥 OVERHEAD 🔥

Should be negligible: TCP retransmit events should be low (<1000/s), and the low overhead this tool adds to each event should make the cost negligible.

translation: she's lightweight, she's polite, she does not eat your CPU for breakfast 🎀

⭐ SOURCE ⭐

This is from bpftrace:

https://github.com/bpftrace/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool. yes bestie, there's bonus content 💅

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

two tools, one name, sibling energy 🫶

🌸 OS 🌸

Linux. obviously. we been knew 🐧

💀 STABILITY 💀

Unstable — in development. she's growing, she's evolving, she's a work in progress and honestly? relatable 🦋

👑 AUTHOR 👑

Brendan Gregg, adapted for bpftrace by Dale Hamel. legends only, we stan 💖

🎀 SEE ALSO 🎀

the whole friend group, go read them too ✨

and that's the page bestie!! this was USER COMMANDS, dated 2018-11-24, and it's the tcpretrans.bt(8) page — go forth and trace those retransmits, mwah 💅💖✨

📦 where this page comes from