tools: add tcptracer (#762)

* tools: add tcptracer

This allows tracking TCP connections by tracking TCP connects, closes
and accepts.

This is different from existing tools like tcpconnect or tcpaccept in
that:

* It includes more information like network namespace or source ports
for tcpconnects or remote ports for tcpaccepts
* It traces tcp_close allowing to see when a connection ends
* It only shows information about established connections

* tcptracer: add to README

* tcptracer: add example

* tcptracer: add man page

README.md

@@ -133,6 +133,7 @@ pair of .c and .py files, and some are directories of files.
 - tools/[tcplife](tools/tcplife.py): Trace TCP sessions and summarize lifespan. [Examples](tools/tcplife_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/[tcptracer](tools/tcptracer.py): Trace TCP established connections (connect(), accept(), close()). [Examples](tools/tcptracer_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/[ttysnoop](tools/ttysnoop.py): Watch live output from a tty or pts device. [Examples](tools/ttysnoop_example.txt).

man/man8/tcptracer.8

+.TH tcptracer 8  "2017-03-27" "USER COMMANDS"
+.SH NAME
+tcptracer \- Trace TCP established connections. Uses Linux eBPF/bcc.
+.SH SYNOPSIS
+.B tcptracer [\-h] [\-v] [\-p PID] [\-N NETNS]
+.SH DESCRIPTION
+This tool traces established TCP connections that open and close while tracing,
+and prints a line of output per connect, accept and close events. This includes
+the type of event, PID, IP addresses and ports.
+
+This tool works by using kernel dynamic tracing, and will need to be updated if
+the kernel implementation changes. Only established TCP connections are traced,
+so it is expected that the overhead of this tool is rather low.
+
+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
+\-v
+Print full lines, with long event type names and network namespace numbers.
+.TP
+\-p PID
+Trace this process ID only (filtered in-kernel).
+.TP
+\-N NETNS
+Trace this network namespace only (filtered in-kernel).
+.TP
+.SH EXAMPLES
+.TP
+Trace all TCP established connections:
+#
+.B tcptracer
+.TP
+Trace all TCP established connections with verbose lines:
+#
+.B tcptracer \-v
+.TP
+Trace PID 181 only:
+#
+.B tcptracer \-p 181
+.TP
+Trace connections in network namespace 4026531969 only:
+#
+.B tcptracer \-N 4026531969
+.SH FIELDS
+.TP
+TYPE
+Type of event. In non-verbose mode: C for connect, A for accept, X for close.
+.TP
+PID
+Process ID
+.TP
+COMM
+Process name
+.TP
+IP
+IP address family (4 or 6)
+.TP
+SADDR
+Source IP address.
+.TP
+DADDR
+Destination IP address.
+.TP
+SPORT
+Source port.
+.TP
+DPORT
+Destination port.
+.TP
+NETNS
+Network namespace where the event originated.
+.SH OVERHEAD
+This traces the kernel inet accept function, and the TCP connect, close,
+and set state functions. However, it only prints information for connections
+that are established, so it shouldn't have a huge overhead.
+
+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
+Iago López Galeiras
+.SH SEE ALSO
+tcpaccept(8), tcpconnect(8), tcptop(8), tcplife(8)

tools/tcptracer_example.txt

+Demonstrations of tcptracer, the Linux eBPF/bcc version.
+
+
+This tool traces the kernel function performing TCP connections (eg, via a
+connect() or accept() syscalls) and closing them (explicitly or if the process
+dies). Some example output (IP addresses are fake):
+
+```
+# ./tcptracer
+Tracing TCP established connections. Ctrl-C to end.
+T  PID    COMM             IP SADDR            DADDR            SPORT  DPORT
+C  28943  telnet           4  192.168.1.2      192.168.1.1      59306  23
+C  28818  curl             6  [::1]            [::1]            55758  80
+X  28943  telnet           4  192.168.1.2      192.168.1.1      59306  23
+A  28817  nc               6  [::1]            [::1]            80     55758
+X  28818  curl             6  [::1]            [::1]            55758  80
+X  28817  nc               6  [::1]            [::1]            80     55758
+A  28978  nc               4  10.202.210.1     10.202.109.12    8080   59160
+X  28978  nc               4  10.202.210.1     10.202.109.12    8080   59160
+```
+
+This output shows three conections, one outgoing from a "telnet" process, one
+outgoing from "curl" to a local netcat, and one incoming received by the "nc"
+process. The output details show the kind of event (C for connection, X for
+close and A for accept), PID, IP version, source address, destination address,
+source port and destination port.