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.

Installing
```
pip install prometheus_speedtest
```
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.5

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.

Docker Network

Create the Docker network that will link prometheus_speedtest and prometheus together.
```
docker network create prometheus_network
```

Start Prometheus Speedtest

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

Start Prometheus

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

Query results
- Visit http://localhost:9090
- 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 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

Running Locally

Python

Ensure packages listed in requirements.txt are installed with pip
```
pip3 install -r requirements.txt
```

Run prometheus_speedtest

python3 -m prometheus_speedtest.prometheus_speedtest

Docker

Building image

docker build -t prometheus_speedtest:latest .

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

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

Maintenance

Deploying to PyPi

Increment version number in version.py
Create PyPi package
```
python3 setup.py sdist
```
Upload package to PyPi

Ensure that Twine has been installed.
```
twine upload dist/*
```

Deploying multi-architecture images to Docker Hub

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

Build and push the new image.

# Ensure you have run 'docker login'
export DOCKER_CLI_EXPERIMENTAL=enabled
docker buildx create --use --name my-builder
docker buildx build --push --platform linux/amd64,linux/arm64,linux/arm/v7 \
    -t jraviles/prometheus_speedtest:latest .
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

moeffju/prometheus_speedtest