tcpdrop.bt(8)

📦 version 0.17.0, in debian bookworm

🦋 tcpdrop.bt — the manual, but make it make sense

okay bestie, welcome to tcpdrop.bt(8) from the System Manager's Manual 💅 this is the page for the tool that traces kernel-based TCP packet drops with details, powered by Linux bpftrace/eBPF. yes, eBPF. we're doing kernel magic today, periodt. ✨

💖 NAME

tcpdrop.bt — trace kernel-based TCP packet drops with details. it runs on Linux bpftrace/eBPF, and honestly? iconic. 👑

🌸 SYNOPSIS

tcpdrop.bt

that's it. that's the whole synopsis. no flags, no arguments, just vibes and root privileges. 🫶

✨ DESCRIPTION

so here's the tea: this tool traces TCP packets or segments that got dropped by the kernel, and it shows you the details from the IP and TCP headers, the socket state, and the kernel stack trace. 🕵️‍♀️

why do you care? because this is literally the move for debugging cases of high kernel drops, which can cause timer-based retransmits and performance issues. like, your network is struggling and you don't know why? this. this is why. 😭

this tool works by dynamically tracing the tcp_drop() kernel function, which — heads up — requires a recent kernel version. no old kernels allowed, sorry babe. 💅

it's also limited to ipv4, and it cannot parse tcpflags because bpftrace currently cannot parse socket buffers the way that bcc can. not us being limited, it's just the way it is. 🙈

and since this uses BPF, only the root user can use this tool. no cap. 🔒

🎀 REQUIREMENTS

  • CONFIG_BPF
  • bpftrace

that's the whole shopping list. ✨

🌈 EXAMPLES

trace all tcp drops:

# tcpdrop.bt

🍓 FIELDS

okay so when the output comes at you, here's what each column is giving:

  • TIME — time of the call, in HH:MM:SS format. ⏰
  • PID — the process ID that was on-CPU during the drop. ⚠️ careful though, this may be unrelated, as drops can occur on the receive interrupt and be unrelated to the PID that was interrupted.
  • COMM — process name. 💬
  • SADDR — source IP address.
  • SPORT — source TCP port.
  • DADDR — destination IP address.
  • DPORT — destination TCP port.
  • STATE — TCP session state (like "ESTABLISHED", etc).

🔥 OVERHEAD

this traces the kernel tcp_drop() function, which should be low frequency, and therefore the overhead of this tool should be negligible. lowkey free. 🧚

but as always — and I mean always — test and understand this tool's overhead for your types of workloads before production use. don't be out here yolo-ing production, bestie. 💀

💜 SOURCE

this is from bpftrace:

https://github.com/iovisor/bpftrace

also, look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool. it's giving extra credit. 📚

this is a bpftrace version of the bcc tool of the same name. and ngl, the bcc tool may provide more options and customizations. so if you want the deluxe edition:

https://github.com/iovisor/bcc

👑 OS

Linux

⭐ STABILITY

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

🌸 AUTHOR

Brendan Gregg, adapted for bpftrace by Dale Hamel. legends only. 💅

🦋 SEE ALSO

and that's the whole page, babe. 🎀 this one's from USER COMMANDS, dated 2018-11-24, and yeah the footer says tcpdrop.bt(8) again because manpages love a little repetition. slay, go drop some packets (or rather, go watch them get dropped). ✨💖

📦 where this page comes from