| .TH tcplife 8 "2016-10-19" "USER COMMANDS" |
| .SH NAME |
| tcplife \- Trace TCP sessions and summarize lifespan. Uses Linux eBPF/bcc. |
| .SH SYNOPSIS |
| .B tcplife [\-h] [\-T] [\-t] [\-w] [\-s] [\-p PID] [\-D PORTS] [\-L PORTS] [\-4 | \-6] |
| .SH DESCRIPTION |
| This tool traces TCP sessions that open and close while tracing, and prints |
| a line of output to summarize each one. This includes the IP addresses, ports, |
| duration, and throughput for the session. This is useful for workload |
| characterisation and flow accounting: identifying what connections are |
| happening, with the bytes transferred. |
| |
| This tool works using the sock:inet_sock_set_state tracepoint if it exists, |
| added to Linux 4.16, and switches to using kernel dynamic tracing for older |
| kernels. Only TCP state changes are traced, so it is expected that the |
| overhead of this tool is much lower than typical send/receive tracing. |
| |
| Since this uses BPF, only the root user can use this tool. |
| .SH REQUIREMENTS |
| CONFIG_BPF and bcc. |
| .SH OPTIONS |
| .TP |
| \-h |
| Print usage message. |
| .TP |
| \-s |
| Comma separated values output (parseable). |
| .TP |
| \-t |
| Include a timestamp column (seconds). |
| .TP |
| \-T |
| Include a time column (HH:MM:SS). |
| .TP |
| \-w |
| Wide column output (fits IPv6 addresses). |
| .TP |
| \-p PID |
| Trace this process ID only (filtered in-kernel). |
| .TP |
| \-L PORTS |
| Comma-separated list of local ports to trace (filtered in-kernel). |
| .TP |
| \-D PORTS |
| Comma-separated list of destination ports to trace (filtered in-kernel). |
| .TP |
| \-4 |
| Trace IPv4 family only. |
| .TP |
| \-6 |
| Trace IPv6 family only. |
| .SH EXAMPLES |
| .TP |
| Trace all TCP sessions, and summarize lifespan and throughput: |
| # |
| .B tcplife |
| .TP |
| Include a timestamp column, and wide column output: |
| # |
| .B tcplife \-tw |
| .TP |
| Trace PID 181 only: |
| # |
| .B tcplife \-p 181 |
| .TP |
| Trace connections to local ports 80 and 81 only: |
| # |
| .B tcplife \-L 80,81 |
| .TP |
| Trace connections to remote port 80 only: |
| # |
| .B tcplife \-D 80 |
| .TP |
| Trace IPv4 family only: |
| # |
| .B tcplife \-4 |
| .TP |
| Trace IPv6 family only: |
| # |
| .B tcplife \-6 |
| .SH FIELDS |
| .TP |
| TIME |
| Time of the call, in HH:MM:SS format. |
| .TP |
| TIME(s) |
| Time of the call, in seconds. |
| .TP |
| PID |
| Process ID |
| .TP |
| COMM |
| Process name |
| .TP |
| IP |
| IP address family (4 or 6) |
| .TP |
| LADDR |
| Local IP address. |
| .TP |
| RADDR |
| Remote IP address. |
| .TP |
| LPORT |
| Local port. |
| .TP |
| RPORT |
| Remote port. |
| .TP |
| TX_KB |
| Total transmitted Kbytes. |
| .TP |
| RX_KB |
| Total received Kbytes. |
| .TP |
| MS |
| Lifespan of the session, in milliseconds. |
| .SH OVERHEAD |
| This traces the kernel TCP set state function, which should be called much |
| less often than send/receive tracing, and therefore have lower overhead. The |
| overhead of the tool is relative to the rate of new TCP sessions: if this is |
| high, over 10,000 per second, then there may be noticeable overhead just to |
| print out 10k lines of formatted output per second. |
| |
| You can find out the rate of new TCP sessions using "sar \-n TCP 1", and |
| adding the active/s and passive/s columns. |
| |
| As always, test and understand this tools overhead for your types of |
| workloads before production use. |
| .SH SOURCE |
| This is from bcc. |
| .IP |
| https://github.com/iovisor/bcc |
| .PP |
| Also look in the bcc distribution for a companion _examples.txt file containing |
| example usage, output, and commentary for this tool. |
| .SH OS |
| Linux |
| .SH STABILITY |
| Unstable - in development. |
| .SH AUTHOR |
| Brendan Gregg |
| .SH SEE ALSO |
| tcpaccept(8), tcpconnect(8), tcptop(8) |
