.TH tcplife.bt 8  "2019-07-03" "USER COMMANDS"
.SH NAME
tcplife.bt \- Trace TCP session lifespans with connection details. Uses bpftrace/eBPF.
.SH SYNOPSIS
.B tcplife
.SH DESCRIPTION
This tool shows the lifespan of TCP sessions that open and close while tracing,
and shows the duration and throughput statistics. For efficiency, this tool
only instruments TCP state changes, rather than all packets.

This tool works by using the sock:inet_sock_set_state tracepoint, which was
added in Linux 4.16.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF, bpftrace, and the sock:inet_sock_set_state tracepoint (Linux 4.16+).
.SH EXAMPLES
.TP
Show TCP sessions with details:
#
.B tcplife.bt
.SH FIELDS
.TP
PID
Process ID
.TP
COMM
Process name
.TP
LADDR
Local IP address.
.TP
DADDR
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 tool originated from BCC:
.IP
https://github.com/iovisor/bcc
.PP
The BCC version has many command line options for customizing the output.
.PP
This bpftrace version originated from the book "BPF Performance Tools",
published by Addison Wesley (2019):
.IP
http://www.brendangregg.com/bpf-performance-tools-book.html
.PP
See the book for more documentation on this tool.
.PP
This bpftrace version is in the bpftrace repository:
.IP
https://github.com/iovisor/bpftrace
.PP
Also look in the bpftrace 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
tcptop(8)