initial commit

.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+.vscode
+.venv*

LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2024 Cloudflare, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

README

@@ -0,0 +1,89 @@
+# Copyright (c) 2024 Cloudflare, Inc.
+# Licensed under the Apache 2.0 license found in the LICENSE file or at https://www.apache.org/licenses/LICENSE-2.0
+
+bbperf measures the following for both TCP and UDP:
+
+* End-to-end latency, both unloaded and loaded
+* Throughput
+* Bandwidth Delay Product (BDP)
+* Usage of buffers between the endpoints
+* Bufferbloat (when the usage of buffers is excessive)
+
+For UDP, it also measures:
+
+* Packet rates
+* Packet loss rates
+
+Features that distinguish this tool from existing tools include:
+
+* Latency, both unloaded and loaded, is measured by the same flow that is under test.
+
+    Other tools will commonly measure latency using a different flow or different protocol.  One of the
+    reasons why using different protocols and/or different flows is not desirable is because fair queuing
+    will cause the latency of those other flows to be much lower (better) than the flow that matters.
+
+* Bufferbloat is calculated
+
+    It is often assumed that TCP receive buffers are the only source of bufferbloat.  While that is common, it
+    misses many other locations where bufferbloat may occur.  This tool reports the effects of all sources of
+    bufferbloat, not just TCP receive buffers.
+
+* Automatic generation of graphs
+
+
+$ bbperf.py --help
+usage: bbperf.py [-h] [-v] [-s] [-c SERVER_IP] [-p SERVER_PORT] [-R] [-t SECONDS] [-u] [-b BANDWIDTH] [-g] [-k]
+
+bbperf: end to end performance and bufferbloat measurement tool
+
+options:
+  -h, --help            show this help message and exit
+  -v, --verbosity       increase output verbosity
+  -s, --server          run in server mode
+  -c SERVER_IP, --client SERVER_IP
+                        run in client mode
+  -p SERVER_PORT, --port SERVER_PORT
+                        server port (default: 5301)
+  -R, --reverse         data flow in download direction (server to client)
+  -t SECONDS, --time SECONDS
+                        duration of run in seconds
+  -u, --udp             run in UDP mode (default: TCP mode)
+  -b BANDWIDTH, --bandwidth BANDWIDTH
+                        n[kmgKMG] | n[kmgKMG]pps
+  -g, --graph           generate graph (requires gnuplot)
+  -k, --keep            keep data file
+
+
+To run a test:
+
+Start the server on one host
+
+    $ bbperf.py -s
+
+Run the client on another host
+
+    $ bbperf.py -c <ip address of server> [additional options as desired]
+
+By default, bbperf will use port 5301 between the client and server.
+
+The first 5 seconds performs a calibration, during which it captures the unloaded latency between endpoints.
+
+Output from bbperf includes the following information:
+
+    sent_time       time when a packet was sent
+    recv_time       time when a packet was received
+    sender_pps      packets per second sent
+    sender_Mbps     bits per second sent
+    receiver_pps    packets per second received
+    receiver_Mbps   bits per second received
+    unloaded_rtt_ms unloaded RTT in milliseconds (determined during calibration)
+    rtt_ms          RTT in milliseconds
+    BDP_bytes       Calculated BDP in bytes
+    buffered_bytes  Actual bytes in flight
+    bloat           Ratio of buffered bytes to BDP
+    pkts_dropped    number of packets dropped (UDP only)
+    drop%           percentage of packets dropped (UDP only)
+
+By default, the client is the sender and the server is the receiver.  That is reversed when
+the "-R" option is specified.
+

bbperf.py

@@ -0,0 +1,80 @@
+#!/usr/bin/python3 -u
+
+# Copyright (c) 2024 Cloudflare, Inc.
+# Licensed under the Apache 2.0 license found in the LICENSE file or at https://www.apache.org/licenses/LICENSE-2.0
+
+import argparse
+
+import client
+import server
+import util
+import const
+
+
+def mainline():
+
+    parser = argparse.ArgumentParser(description="bbperf: end to end performance and bufferbloat measurement tool")
+
+    parser.add_argument("-v", "--verbosity",
+        action="count",
+        default=0,
+        help="increase output verbosity")
+
+    parser.add_argument("-s", "--server",
+        action="store_true",
+        default=False,
+        help="run in server mode")
+
+    parser.add_argument("-c", "--client",
+        metavar="SERVER_IP",
+        default=None,
+        help="run in client mode")
+
+    parser.add_argument("-p", "--port",
+        metavar="SERVER_PORT",
+        type=int,
+        default=const.SERVER_PORT,
+        help="server port (default: 5301)")
+
+    parser.add_argument("-R", "--reverse",
+        action="store_true",
+        default=False,
+        help="data flow in download direction (server to client)")
+
+    parser.add_argument("-t", "--time",
+        metavar="SECONDS",
+        type=int,
+        default=const.DURATION_SEC,
+        help="duration of run in seconds")
+
+    parser.add_argument("-u", "--udp",
+        action="store_true",
+        default=False,
+        help="run in UDP mode (default: TCP mode)")
+
+    parser.add_argument("-b", "--bandwidth",
+        default=None,
+        help="n[kmgKMG] | n[kmgKMG]pps")
+
+    parser.add_argument("-g", "--graph",
+        action="store_true",
+        default=False,
+        help="generate graph (requires gnuplot)")
+
+    parser.add_argument("-k", "--keep",
+        action="store_true",
+        default=False,
+        help="keep data file")
+
+    args = parser.parse_args()
+
+    util.validate_args(args)
+
+    if args.client:
+        client.client_mainline(args)
+    else:
+        server.server_mainline(args)
+
+
+if __name__ == '__main__':
+    mainline()

calibration.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2024 Cloudflare, Inc.
+# Licensed under the Apache 2.0 license found in the LICENSE file or at https://www.apache.org/licenses/LICENSE-2.0
+
+import time
+
+import const
+
+
+calibration_start_time = None
+calibration_end_time = None
+min_rtt_sec = None
+
+
+def start():
+    global calibration_start_time
+    global calibration_end_time
+
+    calibration_start_time = time.time()
+    calibration_end_time = calibration_start_time + const.UNLOADED_DURATION_SEC
+
+def is_calibrated():
+    if calibration_end_time is None:
+        return False
+
+    if time.time() < calibration_end_time:
+        return False
+
+    return True
+
+def update_rtt_sec(new_sample):
+    global min_rtt_sec
+
+    if (min_rtt_sec is None) or (new_sample < min_rtt_sec):
+        min_rtt_sec = new_sample
+
+def get_unloaded_latency_rtt_sec():
+    if min_rtt_sec is None:
+        raise Exception("ERROR: there is no min rtt")
+
+    return min_rtt_sec