jraviles/prometheus_speedtest repository overview

⁠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
   

   Copy

2. Running

   prometheus_speedtest
   

   Copy

⁠Usage

Instrument speedtest.net speedtests from Prometheus.
flags:

prometheus_speedtest.py:
  --address: address to listen on
    (default: '0.0.0.0')
  --port: port to listen on
    (default: '9516')
    (an integer)
  --[no]version: show version
    (default: 'false')

⁠Running with Docker

prometheus_speedtest is also available as a Docker⁠ image on Docker Hub⁠ :whale:.

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

⁠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.

⁠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
   

   Copy

2. Start Prometheus Speedtest

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

   Copy

3. 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
   

   Copy

4. 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

• Python⁠
• Docker⁠
• Pytest⁠

⁠Running Locally

⁠Python

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

   pip install -r requirements.txt
   

   Copy

2. Run prometheus_speedtest

   python -m prometheus_speedtest.prometheus_speedtest
   

   Copy

⁠Docker

1. Building image

   docker build -t prometheus_speedtest:latest .
   

   Copy

2. Running

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

   Copy

⁠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

⁠Maintenance

⁠Deploying to PyPi

1. Increment version number in version.txt⁠

2. Create PyPi package

   python3 setup.py sdist
   

   Copy

3. Upload package to PyPi

   Ensure that Twine⁠ has been installed.

   twine upload dist/*
   

   Copy

⁠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'
   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 .
   

   Copy

⁠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⁠