tcptop (iovisor#726)

README.md

@@ -120,6 +120,7 @@ Examples:
 - tools/[tcpconnect](tools/tcpconnect.py): Trace TCP active connections (connect()). [Examples](tools/tcpconnect_example.txt).
 - tools/[tcpconnlat](tools/tcpconnlat.py): Trace TCP active connection latency (connect()). [Examples](tools/tcpconnlat_example.txt).
 - tools/[tcpretrans](tools/tcpretrans.py): Trace TCP retransmits and TLPs. [Examples](tools/tcpretrans_example.txt).
+- tools/[tcptop](tools/tcptop.py): Summarize TCP send/recv throughput by host. Top for TCP. [Examples](tools/tcptop_example.txt).
 - tools/[tplist](tools/tplist.py): Display kernel tracepoints or USDT probes and their formats. [Examples](tools/tplist_example.txt).
 - tools/[trace](tools/trace.py): Trace arbitrary functions, with filters. [Examples](tools/trace_example.txt)
 - tools/[vfscount](tools/vfscount.py) tools/[vfscount.c](tools/vfscount.c): Count VFS calls. [Examples](tools/vfscount_example.txt).

man/man8/tcptop.8

@@ -0,0 +1,112 @@
+.TH tcptop 8  "2016-09-13" "USER COMMANDS"
+.SH NAME
+tcptop \- Summarize TCP send/recv throughput by host. Top for TCP.
+.SH SYNOPSIS
+.B tcptop [\-h] [\-C] [\-S] [\-p PID] [interval] [count]
+.SH DESCRIPTION
+This is top for TCP sessions.
+
+This summarizes TCP send/receive Kbytes by host, and prints a summary that
+refreshes, along other system-wide metrics.
+
+This uses dynamic tracing of kernel TCP send/receive functions, and will
+need to be updated to match kernel changes.
+
+The traced TCP functions are usually called at a lower rate than
+per-packet functions, and therefore have lower overhead. The traced data is
+summarized in-kernel using a BPF map to further reduce overhead. At very high
+TCP event rates, the overhead may still be measurable. See the OVERHEAD
+section for more details.
+
+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
+\-C
+Don't clear the screen.
+.TP
+\-S
+Don't print the system summary line (load averages).
+.TP
+\-p PID
+Trace this PID only.
+.TP
+interval
+Interval between updates, seconds (default 1).
+.TP
+count
+Number of interval summaries (default is many).
+.SH EXAMPLES
+.TP
+Summarize TCP throughput by active sessions, 1 second refresh:
+#
+.B tcptop
+.TP
+Don't clear the screen (rolling output), and 5 second summaries:
+#
+.B tcptop \-C 5
+.TP
+Trace PID 181 only, and don't clear the screen:
+#
+.B tcptop \-Cp 181
+.SH FIELDS
+.TP
+loadavg:
+The contents of /proc/loadavg
+.TP
+PID
+Process ID.
+.TP
+COMM
+Process name.
+.TP
+LADDR
+Local address (IPv4), and TCP port
+.TP
+RADDR
+Remote address (IPv4), and TCP port
+.TP
+LADDR6
+Source address (IPv6), and TCP port
+.TP
+RADDR6
+Destination address (IPv6), and TCP port
+.TP
+RX_KB
+Received Kbytes
+.TP
+TX_KB
+Transmitted Kbytes
+.SH OVERHEAD
+This traces all send/receives in TCP, high in the TCP/IP stack (close to the
+application) which are usually called at a lower rate than per-packet
+functions, lowering overhead. It also summarizes data in-kernel to further
+reduce overhead. These techniques help, but there may still be measurable
+overhead at high send/receive rates, eg, ~13% of one CPU at 100k events/sec.
+use funccount to count the kprobes in the tool to find out this rate, as the
+overhead is relative to the rate. Some sample production servers tested found
+total TCP event rates of 4k to 15k per second, and the CPU overhead at these
+rates ranged from 0.5% to 2.0% of one CPU. If your send/receive rate is low
+(eg, <1000/sec) then the overhead is expected to be negligible; Test in a lab
+environment first.
+.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 INSPIRATION
+top(1) by William LeFebvre
+.SH SEE ALSO
+tcpconnect(8), tcpaccept(8)