tcplife(8)

💖 tcplife(8) 💖

Okay bestie, this is the manual for tcplife, from the System Manager's Manual 🧚. It's all about tracing TCP sessions and summarizing their lifespan. It runs on Linux with eBPF/bcc ✨.

✨ NAME ✨

tcplife is the tool that traces TCP sessions and summarizes their lifespan 🦋. It uses Linux eBPF/bcc, so yeah, it's giving kernel-level main character energy 👑.

🎀 SYNOPSIS 🎀

tcplife [-h] [-T] [-t] [-w] [-s] [-p PID] [-D PORTS] [-L PORTS] [-4 | -6]

🌸 DESCRIPTION 🌸

Okay so this tool watches TCP sessions that open and close while it's running, and prints one line of output for each session 💅. Each line tells you the IP addresses, ports, duration, and throughput ✨. It's super useful for workload characterisation and flow accounting, aka figuring out which connections are happening and how many bytes moved through them 📊. Literally iconic.

Lowkey the trick is how it works: it uses the sock:inet_sock_set_state tracepoint if your kernel has it (that was added in Linux 4.16 🔥). For older kernels, it switches over to kernel dynamic tracing instead. It only traces TCP state changes, so the overhead is expected to be way lower than typical send/receive tracing. No cap 🫶.

💀 Since this uses BPF, only the root user can run this tool. Sorry bestie, no exceptions 🙈.

🧚 REQUIREMENTS 🧚

You need CONFIG_BPF and bcc ✨.

👑 OPTIONS 👑

• -h — Prints the usage message 💜.
• -s — Gives you comma separated values output, which is parseable 🍓.
• -t — Adds a timestamp column, in seconds ⏱️.
• -T — Adds a time column, in HH:MM:SS format 🕒.
• -w — Wide column output, so IPv6 addresses actually fit 🌈.
• -p PID — Only traces this process ID. The filtering happens in-kernel 🔥.
• -L PORTS — Only traces these local ports. Pass a comma-separated list, and the filtering happens in-kernel 🦋.
• -D PORTS — Only traces these destination ports. Also comma-separated, also filtered in-kernel 💖.
• -4 — Traces the IPv4 family only 🌸.
• -6 — Traces the IPv6 family only ⭐.

🍓 EXAMPLES 🍓

Trace all TCP sessions, and summarize lifespan and throughput:

# tcplife

Include a timestamp column, and wide column output:

# tcplife -tw

Trace PID 181 only:

# tcplife -p 181

Trace connections to local ports 80 and 81 only:

# tcplife -L 80,81

Trace connections to remote port 80 only:

# tcplife -D 80

Trace IPv4 family only:

# tcplife -4

Trace IPv6 family only:

# tcplife -6

🫶 FIELDS 🫶

• TIME — The time of the call, in HH:MM:SS format 🕒.
• TIME(s) — The time of the call, in seconds ⏱️.
• PID — The process ID 🆔.
• COMM — The process name 💅.
• IP — The IP address family, which is either 4 or 6 🌐.
• LADDR — The local IP address 🏠.
• RADDR — The remote IP address 🌍.
• LPORT — The local port 🚪.
• RPORT — The remote port 🎯.
• TX_KB — The total transmitted Kbytes 📤.
• RX_KB — The total received Kbytes 📥.
• MS — The lifespan of the session, in milliseconds ⌛.

🔥 OVERHEAD 🔥

Okay this part is important. The tool traces the kernel TCP set state function, which should get called way less often than send/receive tracing, so the overhead should be lower 💜. The real overhead depends on the rate of new TCP sessions. If that's high, like over 10,000 per second, there may be noticeable overhead just from printing 10k lines of formatted output every second 😭.

To find out the rate of new TCP sessions, you can run sar -n TCP 1 and add up the active/s and passive/s columns 📈.

⚠️ As always, test and understand this tool's overhead for your type of workload before you use it in production. Don't skip this, it's giving "I-learned-the-hard-way" 🙈.

🌈 SOURCE 🌈

This is from bcc ✨. You can find it here:

https://github.com/iovisor/bcc

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

🦋 OS 🦋

Linux 🐧

🧪 STABILITY 🧪

Unstable, since it's still in development 🚧.

🎀 AUTHOR 🎀

Brendan Gregg 👑.

🔗 SEE ALSO 🔗

tcpaccept(8), tcpconnect(8), tcptop(8) 💖

---

Bye bestie, that's the whole page 🫶✨. It's from the USER COMMANDS section, dated 2016-10-19, for tcplife(8) 💅🌸.