tools/tcpsubnet: example file, minor tweaks

tools/tcpsubnet.py

@@ -60,7 +60,7 @@ parser.add_argument("--ebpf", action="store_true",
     help=argparse.SUPPRESS)
 parser.add_argument("-f", "--format", default="B",
     help="[bkmBKM] format to report: bits, Kbits, Mbits, bytes, " +
-    "KBytes, MBytes", choices=["b", "k", "m", "B", "K", "M"])
+    "KBytes, MBytes (default B)", choices=["b", "k", "m", "B", "K", "M"])
 parser.add_argument("-i", "--interval", default=1, type=int,
     help="output interval, in seconds (default 1)")
 args = parser.parse_args()
@@ -213,8 +213,8 @@ b = BPF(text=bpf_text)
 
 ipv4_send_bytes = b["ipv4_send_bytes"]
 
-print("Tracing... Output every %d secs. Hit Ctrl-C to end" %
-        args.interval)
+if not args.json:
+    print("Tracing... Output every %d secs. Hit Ctrl-C to end" % args.interval)
 
 # output
 exiting = 0

tools/tcpsubnet_example.txt

+Demonstrations of tcpsubnet, the Linux eBPF/bcc version.
+
+
+tcpsubnet summarizes throughput by destination subnet.
+It works only for IPv4. Eg:
+
+# tcpsubnet
+Tracing... Output every 1 secs. Hit Ctrl-C to end
+127.0.0.1/32               8
+127.0.0.1/32              10
+
+This example output shows the number of bytes sent to 127.0.0.1/32 (the
+loopback interface). For demo purposes, I set netcat listening on port
+8080, connected to it and sent the following payloads.
+
+# nc 127.0.0.1 8080
+1111111
+111111111
+
+The first line sends 7 digits plus the null character (8 bytes)
+The second line sends 9 digits plus the null character (10 bytes)
+
+Try it yourself to get a feeling of how tcpsubnet works.
+
+By default, tcpsubnet will categorize traffic in the following subnets:
+
+- 127.0.0.1/32
+- 10.0.0.0/8
+- 172.16.0.0/12
+- 192.168.0.0/16
+
+You can change this default behavoir by passing a comma separated list
+of subnets. Let's say we would like to know how much traffic we
+are sending to github.com. We first find out what IPs github.com resolves
+to, Eg:
+
+# dig +short github.com
+192.30.253.112
+192.30.253.113
+
+With this information, we can come up with a reasonable range of IPs
+to monitor, Eg:
+ 
+# tcpsubnet.py 192.30.253.110/27,0.0.0.0/0
+Tracing... Output every 1 secs. Hit Ctrl-C to end
+0.0.0.0/0               3516
+192.30.253.110/27       2501
+192.30.253.110/27         37
+0.0.0.0/0               2037
+192.30.253.110/27       1146
+192.30.253.110/27      12698
+
+If we would like to be more accurate, we can use the two IPs returned
+by dig, Eg:
+
+# tcpsubnet 192.30.253.113/32,192.130.253.112/32,0.0.0.0/0
+Tracing... Output every 1 secs. Hit Ctrl-C to end
+0.0.0.0/0               4416
+192.30.253.113/32        230
+0.0.0.0/0               3138
+192.30.253.113/32       1337
+0.0.0.0/0               2537
+0.0.0.0/0               3206
+0.0.0.0/0              12736
+
+NOTE: When used in production, it is expected that you will have full
+information about your network topology. In which case you won't need
+to approximate subnets nor need to put individual IP addresses like
+we just did.
+
+Notice that the order of the subnet matters. Say, we put 0.0.0.0/0 as
+the first element of the list and 192.130.253.112/32 as the second, all the
+traffic going to 192.130.253.112/32 will have been categorized in
+0.0.0.0/0 as 192.130.253.112/32 is contained in 0.0.0.0/0.
+
+The default ouput unit is bytes. You can change it by using the
+-f [--format] flag. tcpsubnet uses the same flags as iperf for the unit
+format and adds mM. When using kmKM, the output will be rounded to floor.
+Eg:
+
+# tcpsubnet -fK 0.0.0.0/0
+0.0.0.0/0                  5
+0.0.0.0/0                 10
+0.0.0.0/0                 16
+
+Just like the majority of the bcc tools, tcpsubnet supports -i and --ebpf
+
+It also supports -v [--verbose] which gives useful debugging information
+on how the subnets are evaluated and the BPF program is constructed.
+
+Last but not least, it supports -J [--json] to print the output in
+JSON format. This is handy if you're calling tcpsubnet from another
+program (say a nodejs server) and would like to have a structured stdout.
+Eg:
+
+# tcpsubnet -J -fK 192.130.253.110/27,0.0.0.0/0
+{}
+{"0.0.0.0/0": 3, "192.30.253.110/27": 2}
+{"192.30.253.110/27": 0}
+{"0.0.0.0/0": 1, "192.30.253.110/27": 1}
+{"0.0.0.0/0": 0}
+{"192.30.253.110/27": 13}
+{}
+
+
+USAGE:
+
+# ./tcpsubnet -h
+usage: tcpsubnet.py [-h] [-v] [-J] [-f {b,k,m,B,K,M}] [-i INTERVAL] [subnets]
+
+Summarize TCP send and aggregate by subnet
+
+positional arguments:
+  subnets               comma separated list of subnets
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -v, --verbose         output debug statements
+  -J, --json            format output in JSON
+  -f {b,k,m,B,K,M}, --format {b,k,m,B,K,M}
+                        [bkmBKM] format to report: bits, Kbits, Mbits, bytes,
+                        KBytes, MBytes (default B)
+  -i INTERVAL, --interval INTERVAL
+                        output interval, in seconds (default 1)
+
+examples:
+    ./tcpsubnet                 # Trace TCP sent to the default subnets:
+                                # 127.0.0.1/32,10.0.0.0/8,172.16.0.0/12,
+                                # 192.168.0.0/16
+    ./tcpsubnet -f K            # Trace TCP sent to the default subnets
+                                # aggregated in KBytes.
+    ./tcpsubnet 10.80.0.0/24    # Trace TCP sent to 10.80.0.0/24 only
+    ./tcpsubnet -J              # Format the output in JSON.
+