jittermon

Jittermon is a network monitoring tool specifically focused on ping & jitter. It can be run standalone, providing monitoring of packet loss, ping, and jitter or with a remote peer allowing independent monitoring of upstream and downstream jitter. It uses Loki, Grafana, and Prometheus for storing and visualizing data.

Author's Notes

Unfortunately, I don't have any plans to maintain this project in any serious capacity aside from yearly dependabot PRs. If you would like to take this project further, please feel free to fork or copy it.

Follow the getting started section below to begin. Advanced readers may also want to check out the contributing file for more technical details.

Background Story (click to expand)

A year ago I was experiencing strange internet issues that were hard to identify in a meaningful way to my ISP. The best information I had was that I was seeing elevated packet loss, ping, & jitter, and that during such events on a VoIP call I could hear others but they couldn't hear me. At the time I was also using PingPlotter (which heavily inspired this project and I recommend you check out) but it couldn't explain the issue fully.

Oddly enough, while playing Deadlock with their network graphs enabled I noticed something peculiar about my issue that PingPlotter wasn't able to see: it was primarily my upstream connection that was experiencing problems. So I set out to measure and observe my upstream and downstream jitter similar to the Deadlock network graphs by creating this tool.

I spent a lot of time going back and forth on the complexity of the application and its design, flip-flopping on topics such as an extensible library, in-house visualization tools, executable binary, and other implementation details. However, I have to move on from the project and wanted it in a usable open source state so I tightened things up to just this very simple tool you run in Docker.

Getting Started

1. Clone the repo or download and extract the source code from the latest version here.
2. Ensure you have the following requirements installed:
   1. docker (if you aren't sure how to install, use the Download Docker Desktop button)
   2. docker compose (skip this step if you installed docker desktop in the previous step)
   3. flyctl (only if you plan to follow the advanced getting started guide below).
3. Follow either the Standalone (basic, free) or With Remote Peer (advanced, may incur costs) section below to get started.

Note

Attention Windows Users: After installing docker desktop above you'll likely have to restart your machine. You may also have to run wsl --install or wsl --update in a command prompt window after restarting. For running the commands below you'll need to open a command prompt window in the same folder where you cloned or extracted the source code which is explained here.

Standalone

Monitor your packet loss, ping, and jitter (basic).

1. Build docker image.

   docker build -t jittermon .

2. Run the app.

   docker compose up -d

3. View metrics in your browser at http://localhost:3000/d/aec2tnhcwbuo0b
   (username: admin, password: demo).
4. Stop the app.

   docker compose down

With Remote Peer

Monitor your packet loss, ping, jitter, upstream jitter, and downstream jitter (advanced).

For our remote peer we're using fly.io because it is cheap and easy. Before proceeding, review their pricing details here to make sure you're comfortable with any costs you may incur. When this project started they had free allowances but that doesn't seem to be the case anymore as stated here.

1. Review fly.toml, you'll want to update primary_region to your own region.
2. Deploy to fly

   fly launch --ha=false
   # when executing the above follow these choices for the prompts:
   # ? Would you like to copy its configuration to the new app?
   #   Yes
   # ? Do you want to tweak these settings before proceeding?
   #   No
   # ? Create .dockerignore from 1 .gitignore files?
   #   No
   # ? Would you like to allocate dedicated ipv4 and ipv6 addresses now?
   #   Yes

3. Set the remote peer's send address to your IP address. Make sure you've port forwarded and replace YOURIPHERE with your public IPv4 address (on Windows you will likely also have to open the port in Windows Defender).

   fly secrets set JITTERMON_PTP_SEND_ADDRS=YOURIPHERE:8081
   # e.g.
   # fly secrets set JITTERMON_PTP_SEND_ADDRS=123.123.123.123:8081

4. Save the IP address of your fly app from step 2 above to .env (replace FLYADDRESS with the actual IPv4 address).

   echo JITTERMON_PTP_SEND_ADDRS=FLYADDRESS:8080 > .env
   # e.g.
   # echo JITTERMON_PTP_SEND_ADDRS=123.123.123.123:8080 > .env

5. Build docker image.

   docker build -t jittermon .

6. Run the app.

   docker compose up -d

7. View metrics in your browser at http://localhost:3000/d/aec2tnhcwbuo0b
   (username: admin, password: demo).
8. Stop the app.

   docker compose down