Metadata-Version: 2.4
Name: bbperf
Version: 0.0.4
Summary: An end-to-end performance and bufferbloat measurement tool
Project-URL: Homepage, https://github.com/cloudflare/bbperf
Project-URL: Issues, https://github.com/cloudflare/bbperf/issues
Author-email: Mike Freemon <mfreemon@cloudflare.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Requires-Dist: numpy
Description-Content-Type: text/markdown

<p align="center"><strong>bbperf</strong> <em>- An end-to-end performance and bufferbloat measurement tool</em></p>

`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)

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

* The UDP option will automatically adjust the sending rate to just above the goodput rate so that any bufferbloat issues are measured.

### Usage

To run a test:

1. Start the server on one host
```
    $ bbperf.py -s
```

2. Run the client on another host
```
    $ bbperf.py -c <ip address of server> [additional options as desired]
```

`bbperf` will use port 5301 between the client and server (by default).

The first 5 seconds performs a calibration, during which it captures the unloaded latency between endpoints.

The direction of data flow is from the client to the server.  That is reversed when the "-R" option is specified.

```
$ bbperf.py --help
usage: bbperf.py [-h] [-v] [-q] [-s] [-c SERVER_IP] [-p SERVER_PORT] [-R] [-t SECONDS] [-u] [-g] [-k] [-J JSON_FILE]

bbperf: end to end performance and bufferbloat measurement tool

options:
  -h, --help            show this help message and exit
  -v, --verbosity       increase output verbosity (can be repeated)
  -q, --quiet           decrease output verbosity (can be repeated)
  -s, --server          run in server mode
  -c, --client SERVER_IP
                        run in client mode
  -p, --port SERVER_PORT
                        server port (default: 5301)
  -R, --reverse         data flow in download direction (server to client)
  -t, --time SECONDS    duration of run in seconds
  -u, --udp             run in UDP mode (default: TCP mode)
  -g, --graph           generate graph (requires gnuplot)
  -k, --keep            keep data file
  -J, --json-file JSON_FILE
                        JSON output file
```

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)
```

Output to standard out is controlled via the `--verbosity` and `--quiet` options as follows:
```
    -qq           nothing to stdout except errors
    -q            run summary in json format
(neither option)  progress update once per second plus run summary in json format (default)
    -v            progress update once per 0.1 seconds, additional output, and run summary in json format
    -vv           debugging info useful for developers only
```

### Installation

`bbperf` is available via PyPI repository (pypi.org) and can be installed using pip.

```
python3 -m venv bbperf-venv
. bbperf-venv/bin/active
pip install bbperf

bbperf.py [options]
```

In the event python3 is not already installed on the host:

```
apt-get install python3 python3-pip  (Debian/Ubuntu)
dnf install python3 python3-pip      (Fedora/RHEL)
```

---
Copyright (c) 2024 Cloudflare, Inc.<br/>
Licensed under the Apache 2.0 license found in the LICENSE file or at https://www.apache.org/licenses/LICENSE-2.0

