Prometheus Speedtest

Instrument Speedtest.net tests from Prometheus. Provides metrics on download_speed, upload_speed, and latency.

Getting Started

These instructions will install and run prometheus_speedtest on your system.

PyPi Package

prometheus_speedtest is provided as a PyPi package.

1. Installing

   pip install prometheus_speedtest

2. Running

   prometheus_speedtest

Usage

Instrument speedtest.net speedtests from Prometheus.
flags:

prometheus_speedtest.py:
  --address: address to listen on
    (default: '0.0.0.0')
  --excludes: speedtest server(s) to exclude - leave empty for no exclusion
    (a comma separated list)
  --port: port to listen on
    (default: '9516')
    (an integer)
  --servers: speedtest server(s) to use - leave empty for auto-selection
    (a comma separated list)
  --[no]version: show version
    (default: 'false')

Running with Docker

prometheus_speedtest is also available as a Docker image on Docker Hub 🐳.

docker run --rm -d --name prometheus_speedtest -p 9516:9516/tcp jraviles/prometheus_speedtest:latest

You can also append extra flags when running with Docker. For example:

$ docker run --rm --name prometheus_speedtest -p 9516:9516/tcp \
    jraviles/prometheus_speedtest:latest --version
prometheus_speedtest v0.9.9

Running with Kubernetes

Since you can run this from a Docker container, you can also run it in Kubernetes.

kubectl apply -f deploy/namespace.yaml
kubectl apply -f deploy/deployment.yaml

The Kubernetes YAML files are pre-configured to work with the kubernetes-pods-slow job that comes with Prometheus, which is configured with 5m scrape times and 30s timeouts. If you need to raise the timeout, you'll need to change that in your Prometheus config map.

Just keep in mind, that if you increase the replica count, then Prometheus will run a speedtest for each pod, every 5m. The same goes for if you are running more than one replica of Prometheus, as each replica independently scrapes targets.

Integrating with Prometheus

prometheus_speedtest is best when paired with Prometheus. Prometheus can be configured to perform Speedtests on an interval and record their results.

Speedtest metrics available to query in Prometheus.

Metric Name	Description
download_speed_bps	Download speed (bit/s)
upload_speed_bps	Upload speed (bit/s)
ping_ms	Latency (ms)
bytes_received	Bytes received during test
bytes_sent	Bytes sent during test

prometheus.yml config

Add this to your Prometheus config to start instrumenting Speedtests and recording their metrics.

global:
  scrape_timeout: 2m

scrape_configs:
- job_name: 'speedtest'
  metrics_path: /probe
  static_configs:
  - targets:
    - localhost:9516

Note if you're running prometheus under Docker, you must link the prometheus container to prometheus_speedtest. See the steps below for how this can be done.

Trying it out

An example Prometheus config has been provided at example/prometheus.yml. We'll start prometheus with this config.

1. Docker Network

   Create the Docker network that will link prometheus_speedtest and prometheus together.

   docker network create prometheus_network

2. Start Prometheus Speedtest

   docker run --rm -d --net prometheus_network -p 9516:9516/tcp \
      --name prometheus_speedtest jraviles/prometheus_speedtest:latest

3. Start Prometheus

   docker run --rm -d --net prometheus_network -p 9516:9516/tcp \
      -v $PWD/example/prometheus.yml:/etc/prometheus/prometheus.yml \
      --name prometheus prom/prometheus:latest

4. Query results

   • Visit http://localhost:9516/probe

   • Wait around 45 seconds for Prometheus to perform a Speedtest

   • Issue a query for download_speed_bps

     You should see something like this.

     

Instrumenting Speedtests with cURL

Once prometheus_speedtest has been started, with either Docker or PyPi, Speedtests can be instrumented with cURL.

$ curl localhost:9516/probe
# HELP download_speed_bps Download speed (bit/s)
# TYPE download_speed_bps gauge
download_speed_bps 88016694.95692767
# HELP upload_speed_bps Upload speed (bit/s)
# TYPE upload_speed_bps gauge
upload_speed_bps 3415613.277989314
# HELP ping_ms Latency (ms)
# TYPE ping_ms gauge
ping_ms 20.928
# HELP bytes_received Bytes received during test
# TYPE bytes_received gauge
bytes_received 111342756.0
# HELP bytes_sent Bytes sent during test
# TYPE bytes_sent gauge
bytes_sent 5242880.0

You can also visit http://localhost:9516/probe in your browser to see the same metrics.

Default Port

Prometheus Speedtest defaults to running on port 9516; this is the allocated port for this exporter in the Prometheus Default Port Allocations Guide.

Getting Started (Development)

These instructions will get you a copy prometheus_speedtest up and running on your local machine for development and testing purposes.

Prerequisites

• Python
• Docker
• Pytest

Running Locally

Python

1. Ensure packages listed in requirements.txt are installed with pip

   pip3 install -r requirements.txt

2. Run prometheus_speedtest

   python3 -m prometheus_speedtest.prometheus_speedtest

Docker

1. Building image

   docker build -t prometheus_speedtest:latest .

2. Running

   docker run --rm -d --name prometheus_speedtest -p 9516:9516/tcp prometheus_speedtest:latest

Perform a Speedtest

curl localhost:9516/probe

Or visit http://localhost:9516/probe

Running Unit Tests

pytest

Contributing

Pull requests are welcome. Please adhere to the Google Python style guide.

Please format your contributions with the yapf formatter and lint your code with pylint. A .pylintrc config has been provided.

yapf -i **/*.py
pylint **/*.py
pytype

Grafana Dashboard Template

User Doğukan Çağatay has created a Grafana dashboard template for prometheus_speedtest. Go check it out on grafana.com.

Maintenance

Deploying to PyPi

1. Increment version number in version.py

2. Create PyPi package

   python3 setup.py sdist

3. Upload package to PyPi

   Ensure that Twine has been installed.

   twine upload dist/*

Deploying multi-architecture images to Docker Hub

1. Ensure that Docker >= 19.03 and docker buildx is installed.

2. Build and push the new image.

   # Ensure you have run 'docker login'
   # https://github.com/docker/buildx/issues/495#issuecomment-754688157
   docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
   docker buildx create --use --name my-builder
   TAG="$(python3 -m prometheus_speedtest.prometheus_speedtest --version \
       | cut -d 'v' -f 2)"
   docker buildx build --push --platform linux/amd64,linux/arm64,linux/arm/v7 \
       -t jraviles/prometheus_speedtest:latest \
       -t jraviles/prometheus_speedtest:${TAG:?} .
   docker buildx rm my-builder

Authors

• Jean-Ralph Aviles

License

This product is licensed under the Apache 2.0 license. See LICENSE file for details.

Acknowledgments

• Matt Martz speedtest-cli
• The Prometheus team https://prometheus.io
• Testing in Python team http://lists.idyll.org/listinfo/testing-in-python
• Benjamin Staffin python-glog