add tcplife (#773)
diff --git a/tools/tcplife_example.txt b/tools/tcplife_example.txt
new file mode 100644
index 0000000..457fe78
--- /dev/null
+++ b/tools/tcplife_example.txt
@@ -0,0 +1,135 @@
+Demonstrations of tcplife, the Linux BPF/bcc version.
+
+
+tcplife summarizes TCP sessions that open and close while tracing. For example:
+
+# ./tcplife
+PID COMM LADDR LPORT RADDR RPORT TX_KB RX_KB MS
+22597 recordProg 127.0.0.1 46644 127.0.0.1 28527 0 0 0.23
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 46644 0 0 0.28
+22598 curl 100.66.3.172 61620 52.205.89.26 80 0 1 91.79
+22604 curl 100.66.3.172 44400 52.204.43.121 80 0 1 121.38
+22624 recordProg 127.0.0.1 46648 127.0.0.1 28527 0 0 0.22
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 46648 0 0 0.27
+22647 recordProg 127.0.0.1 46650 127.0.0.1 28527 0 0 0.21
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 46650 0 0 0.26
+[...]
+
+This caught a program, "recordProg" making a few short-lived TCP connections
+to "redis-serv", lasting about 0.25 milliseconds each connection. A couple of
+"curl" sessions were also traced, connecting to port 80, and lasting 91 and 121
+milliseconds.
+
+This tool is useful for workload characterisation and flow accounting:
+identifying what connections are happening, with the bytes transferred.
+
+
+Process names are truncated to 10 characters. By using the wide option, -w,
+the column width becomes 16 characters. The IP address columns are also wider
+to fit IPv6 addresses:
+
+# ./tcplife -w
+PID COMM IP LADDR LPORT RADDR RPORT TX_KB RX_KB MS
+26315 recordProgramSt 4 127.0.0.1 44188 127.0.0.1 28527 0 0 0.21
+3277 redis-server 4 127.0.0.1 28527 127.0.0.1 44188 0 0 0.26
+26320 ssh 6 fe80::8a3:9dff:fed5:6b19 22440 fe80::8a3:9dff:fed5:6b19 22 1 1 457.52
+26321 sshd 6 fe80::8a3:9dff:fed5:6b19 22 fe80::8a3:9dff:fed5:6b19 22440 1 1 458.69
+26341 recordProgramSt 4 127.0.0.1 44192 127.0.0.1 28527 0 0 0.27
+3277 redis-server 4 127.0.0.1 28527 127.0.0.1 44192 0 0 0.32
+
+
+In this example, I uploaded a 10 Mbyte file to the server, and then downloaded
+it again, using scp:
+
+# ./tcplife
+PID COMM LADDR LPORT RADDR RPORT TX_KB RX_KB MS
+7715 recordProg 127.0.0.1 50894 127.0.0.1 28527 0 0 0.25
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 50894 0 0 0.30
+7619 sshd 100.66.3.172 22 100.127.64.230 63033 5 10255 3066.79
+7770 recordProg 127.0.0.1 50896 127.0.0.1 28527 0 0 0.20
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 50896 0 0 0.24
+7793 recordProg 127.0.0.1 50898 127.0.0.1 28527 0 0 0.23
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 50898 0 0 0.27
+7847 recordProg 127.0.0.1 50900 127.0.0.1 28527 0 0 0.24
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 50900 0 0 0.29
+7870 recordProg 127.0.0.1 50902 127.0.0.1 28527 0 0 0.29
+3277 redis-serv 127.0.0.1 28527 127.0.0.1 50902 0 0 0.30
+7798 sshd 100.66.3.172 22 100.127.64.230 64925 10265 6 2176.15
+[...]
+
+You can see the 10 Mbytes received by sshd, and then later transmitted. Looks
+like receive was slower (3.07 seconds) than transmit (2.18 seconds).
+
+
+Timestamps can be added with -t:
+
+# ./tcplife -t
+TIME(s) PID COMM LADDR LPORT RADDR RPORT TX_KB RX_KB MS
+0.000000 5973 recordProg 127.0.0.1 47986 127.0.0.1 28527 0 0 0.25
+0.000059 3277 redis-serv 127.0.0.1 28527 127.0.0.1 47986 0 0 0.29
+1.022454 5996 recordProg 127.0.0.1 47988 127.0.0.1 28527 0 0 0.23
+1.022513 3277 redis-serv 127.0.0.1 28527 127.0.0.1 47988 0 0 0.27
+2.044868 6019 recordProg 127.0.0.1 47990 127.0.0.1 28527 0 0 0.24
+2.044924 3277 redis-serv 127.0.0.1 28527 127.0.0.1 47990 0 0 0.28
+3.069136 6042 recordProg 127.0.0.1 47992 127.0.0.1 28527 0 0 0.22
+3.069204 3277 redis-serv 127.0.0.1 28527 127.0.0.1 47992 0 0 0.28
+
+This shows that the recordProg process was connecting once per second.
+
+There's also a -T for HH:MM:SS formatted times.
+
+
+There's a comma separated values mode, -s. Here it is with both -t and -T
+timestamps:
+
+# ./tcplife -stT
+TIME,TIME(s),PID,COMM,IP,LADDR,LPORT,RADDR,RPORT,TX_KB,RX_KB,MS
+23:39:38,0.000000,7335,recordProgramSt,4,127.0.0.1,48098,127.0.0.1,28527,0,0,0.26
+23:39:38,0.000064,3277,redis-server,4,127.0.0.1,28527,127.0.0.1,48098,0,0,0.32
+23:39:39,1.025078,7358,recordProgramSt,4,127.0.0.1,48100,127.0.0.1,28527,0,0,0.25
+23:39:39,1.025141,3277,redis-server,4,127.0.0.1,28527,127.0.0.1,48100,0,0,0.30
+23:39:41,2.040949,7381,recordProgramSt,4,127.0.0.1,48102,127.0.0.1,28527,0,0,0.24
+23:39:41,2.041011,3277,redis-server,4,127.0.0.1,28527,127.0.0.1,48102,0,0,0.29
+23:39:42,3.067848,7404,recordProgramSt,4,127.0.0.1,48104,127.0.0.1,28527,0,0,0.30
+23:39:42,3.067914,3277,redis-server,4,127.0.0.1,28527,127.0.0.1,48104,0,0,0.35
+[...]
+
+
+There are options for filtering on local and remote ports. Here is filtering
+on local ports 22 and 80:
+
+# ./tcplife.py -L 22,80
+PID COMM LADDR LPORT RADDR RPORT TX_KB RX_KB MS
+8301 sshd 100.66.3.172 22 100.127.64.230 58671 3 3 1448.52
+[...]
+
+
+USAGE:
+
+# ./tcplife.py -h
+usage: tcplife.py [-h] [-T] [-t] [-w] [-s] [-p PID] [-L LOCALPORT]
+ [-D REMOTEPORT]
+
+Trace the lifespan of TCP sessions and summarize
+
+optional arguments:
+ -h, --help show this help message and exit
+ -T, --time include time column on output (HH:MM:SS)
+ -t, --timestamp include timestamp on output (seconds)
+ -w, --wide wide column output (fits IPv6 addresses)
+ -s, --csv comma seperated values output
+ -p PID, --pid PID trace this PID only
+ -L LOCALPORT, --localport LOCALPORT
+ comma-separated list of local ports to trace.
+ -D REMOTEPORT, --remoteport REMOTEPORT
+ comma-separated list of remote ports to trace.
+
+examples:
+ ./tcplife # trace all TCP connect()s
+ ./tcplife -t # include time column (HH:MM:SS)
+ ./tcplife -w # wider colums (fit IPv6)
+ ./tcplife -stT # csv output, with times & timestamps
+ ./tcplife -p 181 # only trace PID 181
+ ./tcplife -L 80 # only trace local port 80
+ ./tcplife -L 80,81 # only trace local ports 80 and 81
+ ./tcplife -D 80 # only trace remote port 80