tcplife.bt(8)

📦 version 0.17.0, in debian bookworm

💖 tcplife.bt — the manual page, bestie edition 💖

okay so you found the tcplife.bt(8) page in the System Manager's Manual section and you're like "what is this". don't worry. I got you. no cap, this is one of my faves 🫶

✨ NAME ✨

tcplife.bt — trace TCP session lifespans with connection details. uses bpftrace/eBPF. it's giving "watch your TCP babies be born and also watch them leave" 😭

🌸 SYNOPSIS 🌸

tcplife

that's it. that's the whole vibe. no args, no flags, just run it 💅

🦋 DESCRIPTION 🦋

okay so listen. this tool shows you the lifespan of TCP sessions that open and close while you're tracing, and it also shows the duration and throughput statistics. the way it does this is so smart: for efficiency, it only instruments TCP state changes, rather than every single packet. not me being obsessed with not doing extra work 🙈 iconic behaviour honestly.

the way it works: it uses the sock:inet_sock_set_state tracepoint, which was added in Linux 4.16. so if your kernel is ancient, this is gonna be a no from it, sorry bestie.

and because this uses BPF, only the root user can use this tool. like, root only. periodt. 🔥

🎀 REQUIREMENTS 🎀

  • CONFIG_BPF
  • bpftrace
  • the sock:inet_sock_set_state tracepoint (Linux 4.16+)

miss any of these and the whole thing just does not slay, I'm sorry 💀

⭐ EXAMPLES ⭐

show TCP sessions with details:

# tcplife.bt

that's the entire example. chef's kiss. it just works ✨

💜 FIELDS 💜

  • PID — process ID
  • COMM — process name
  • LADDR — local IP address.
  • DADDR — remote IP address.
  • LPORT — local port.
  • RPORT — remote port.
  • TX_KB — total transmitted Kbytes.
  • RX_KB — total received Kbytes.
  • MS — lifespan of the session, in milliseconds.

nine fields. all bangers. no filler 🧚

🍓 OVERHEAD 🍓

this traces the kernel TCP set state function, which should be called much less often than send/receive tracing, and therefore has lower overhead. so that's the good news bestie 💚

but — and this is important — the overhead of the tool is relative to the rate of new TCP sessions. if that rate is high, over 10,000 per second, then there may be noticeable overhead just to print out 10k lines of formatted output per second. like, the printing alone. not even the tracing. the printing 😭

you can find out the rate of new TCP sessions using sar -n TCP 1, and adding the active/s and passive/s columns. do that. it's your vibe check 📊

as always, test and understand this tool's overhead for your types of workloads before production use. I am literally begging you. production is not the place to find out 🙏

🌈 SOURCE 🌈

this tool originated from BCC:

https://github.com/iovisor/bcc

the BCC version has many command line options for customizing the output. (this one does not. we keep it simple here. minimalism era 💅)

this bpftrace version originated from the book "BPF Performance Tools", published by Addison Wesley (2019):

http://www.brendangregg.com/bpf-performance-tools-book.html

see the book for more documentation on this tool. it's a whole read, highly recommend 📚

this bpftrace version is in the bpftrace repository:

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. lowkey the commentary is the best part 👑

👑 OS 👑

Linux

just linux. that's the whole section. iykyk 🐧

💀 STABILITY 💀

Unstable — in development.

so like... it works, but it's still growing. be nice to it. it's doing its best 🥺

🌸 AUTHOR 🌸

Brendan Gregg

legend. icon. the moment. main character energy fr fr 💖

💖 SEE ALSO 💖

and that's the whole page bestie!! this came from USER COMMANDS, dated 2019-07-03, and it's the tcplife.bt(8) page — go trace some sessions, you got this, mwah 💅✨🎀🦋
📦 where this page comes from