prometheus-speedtest 0.9.14

Description:

prometheusspeedtest 0.9.14

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
:whale:.
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.


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 9516:9516/tcp \
-v $PWD/example/prometheus.yml:/etc/prometheus/prometheus.yml \
--name prometheus prom/prometheus:latest



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


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


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