Jitterbug: Framework for Jitter-Based Congestion Inference

Welcome to the Jitterbug repository, where you can access the source code and installation instructions for Jitterbug.

Jitterbug is the outcome of research presented in the paper "Jitterbug: A new framework for jitter-based congestion inference", published in the Proceedings of the Passive and Active Measurement Conference (PAM) 2022, held virtually in March 2022.

Table of Contents

1. Installation Guide
   1. Setting Up a Virtual Environment
   2. Cloning Third-Party Dependencies
   3. Installation Process
2. Using Jitterbug
   1. Usage Example
   2. Input File Format
   3. Real-World Data Examples
3. Command-Line Interface
4. Citing Jitterbug
5. Repository Structure

1. Installation Guide

1.1. Setting Up a Virtual Environment

It is recommended to use a Python virtual environment for running Jitterbug. This repository contains a requirements.txt file for installing all necessary Python packages.

Execute the following commands to set up the virtual environment:

$ python3 -m venv .jitterbug
$ source .jitterbug/bin/activate
$ pip3 install ipykernel
$ ipython kernel install --user --name=.jitterbug
$ pip3 install -r requirements.txt

1.2. Cloning Third-Party Dependencies

$ git clone https://github.com/hildensia/bayesian_changepoint_detection.git
$ cd bayesian_changepoint_detection
$ python setup.py install
$ cd ..

1.3. Installation Process

$ python setup.py sdist bdist_wheel build_ext
$ pip install -e .

2. Using Jitterbug

2.1. Usage Example

Ensure the virtual environment is activated before executing Jitterbug:

$ jitterbug -r rtts.csv -i jd -c bcp

Example rtts.csv file is provided in the repository.

2.2. Input File Format

RTT Measurements

Format of rtts.csv:

epoch,values
1512144010.0,63.86
1512144010.0,66.52
...

2.3. Real-World Data Examples

Explore Jitterbug using two Jupyter Notebooks provided in this repository:

1. KS-test Congestion Inference
2. Jitter Dispersion Congestion Inference

3. Command-Line Interface

For detailed command usage, run:

$ jitterbug --help

4. Citing Jitterbug

Please cite Jitterbug using the following reference:

@InProceedings{carisimo2022jitterbug,
  author="Carisimo, Esteban and Mok, Ricky K. P. and Clark, David D. and Claffy, K. C.",
  title="Jitterbug: A New Framework for Jitter-Based Congestion Inference",
  booktitle="Passive and Active Measurement",
  year="2022",
  publisher="Springer International Publishing",
  address="Cham",
  pages="155--179",
  isbn="978-3-030-98785-5"
}

5. Repository Structure

.
├── LICENSE
├── README.md
├── example
│   ├── data
│   │   ├── congestion-inferences
│   │   │   ├── jd_inferences.csv
│   │   │   └── kstest_inferences.csv
│   │   └── congestion-measurements
│   │       ├── mins

.csv
│   │       └── raw.csv
│   ├── jitter-dispersion-example.ipynb
│   └── jitter-kstest-example.ipynb
├── jitterbug
│   ├── __init__.py
│   ├── _jitter.py
│   ├── _jitterbug.py
│   ├── _latency_jump.py
│   ├── bcp.py
│   ├── cong_inference.py
│   ├── filters.py
│   ├── kstest.py
│   ├── preprocessing.py
│   └── signal_energy.py
├── requirements.txt
├── setup.py
└── tools
    └── jitterbug.py