# Prometheus Speedtest
Instrument [Speedtest.net](http://speedtest.net) tests from
[Prometheus](https://prometheus.io). Provides metrics on download\_speed,
upload\_speed, and latency.
[](https://travis-ci.com/jeanralphaviles/prometheus_speedtest/branches)
[](https://pypi.python.org/pypi/prometheus_speedtest/)
[](https://hub.docker.com/r/jraviles/prometheus_speedtest)
[](https://pypi.python.org/pypi/prometheus_speedtest/)
[](https://pypi.python.org/pypi/prometheus_speedtest/)
[](https://pypi.python.org/pypi/prometheus_speedtest/)
## Getting Started
These instructions will install and run `prometheus_speedtest` on your system.
### PyPi Package
`prometheus_speedtest` is provided as a
[PyPi package](https://pypi.org/project/prometheus_speedtest).
1. Installing
```shell
pip install prometheus_speedtest
```
1. Running
```shell
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](http://docker.com) image
on [Docker Hub](https://hub.docker.com/r/jraviles/prometheus_speedtest)
:whale:.
```shell
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:
```shell
$ 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.
```shell
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](https://prometheus.io). 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](https://prometheus.io/docs/prometheus/latest/configuration/configuration)
to start instrumenting Speedtests and recording their metrics.
```yaml
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](https://prometheus.io/docs/prometheus/latest/configuration/configuration)
has been provided at
[example/prometheus.yml](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/example/prometheus.yml).
We'll start `prometheus` with this config.
1. Docker Network
Create the [Docker network](https://docs.docker.com/network) that will link
`prometheus_speedtest` and `prometheus` together.
```shell
docker network create prometheus_network
```
1. Start Prometheus Speedtest
```shell
docker run --rm -d --net prometheus_network -p 9516:9516/tcp \
--name prometheus_speedtest jraviles/prometheus_speedtest:latest
```
1. Start Prometheus
```shell
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
```
1. 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](https://curl.haxx.se).
```shell
$ 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](https://github.com/prometheus/prometheus/wiki/Default-port-allocations).
## 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](https://www.python.org)
* [Docker](https://www.docker.com)
* [Pytest](https://pytest.org)
### Running Locally
#### Python
1. Ensure packages listed in
[requirements.txt](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/requirements.txt)
are installed with `pip`
```python
pip3 install -r requirements.txt
```
1. Run `prometheus_speedtest`
```python
python3 -m prometheus_speedtest.prometheus_speedtest
```
#### Docker
1. Building image
```shell
docker build -t prometheus_speedtest:latest .
```
1. Running
```shell
docker run --rm -d --name prometheus_speedtest -p 9516:9516/tcp prometheus_speedtest:latest
```
### Perform a Speedtest
```shell
curl localhost:9516/probe
```
Or visit <http://localhost:9516/probe>
### Running Unit Tests
```shell
pytest
```
### Contributing
Pull requests are welcome. Please adhere to the
[Google Python style guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
Please format your contributions with the
[yapf](https://github.com/google/yapf) formatter and lint your code with
[pylint](https://www.pylint.org). A
[.pylintrc](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/.pylintrc)
config has been provided.
```shell
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](https://grafana.com/grafana/dashboards/11229).
## Maintenance
### Deploying to PyPi
1. Increment version number in
[version.py](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/prometheus_speedtest/version.py)
1. Create PyPi package
```shell
python3 setup.py sdist
```
1. Upload package to PyPi
Ensure that [Twine](https://github.com/pypa/twine) has been installed.
```shell
twine upload dist/*
```
### Deploying multi-architecture images to Docker Hub
1. Ensure that Docker >= 19.03 and
[docker buildx](https://docs.docker.com/buildx/working-with-buildx/) is
installed.
1. Build and push the new image.
```shell
# 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](LICENSE)
file for details.
## Acknowledgments
* Matt Martz [speedtest-cli](https://github.com/sivel/speedtest-cli)
* The Prometheus team <https://prometheus.io>
* Testing in Python team <http://lists.idyll.org/listinfo/testing-in-python>
* Benjamin Staffin [python-glog](https://github.com/benley/python-glog)
Raw data
{
"_id": null,
"home_page": "https://github.com/jeanralphaviles/prometheus_speedtest",
"name": "prometheus-speedtest",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "prometheus,monitoring,speedtest,speedtest.net",
"author": "Jean-Ralph Aviles",
"author_email": "jeanralph.aviles+pypi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4a/9f/60a3c4a17abec9e0629520eabd148255cb45e5dfc62bfec5326b5a5cdfda/prometheus_speedtest-0.9.14.tar.gz",
"platform": null,
"description": "# Prometheus Speedtest\n\nInstrument [Speedtest.net](http://speedtest.net) tests from\n[Prometheus](https://prometheus.io). Provides metrics on download\\_speed,\nupload\\_speed, and latency.\n\n[](https://travis-ci.com/jeanralphaviles/prometheus_speedtest/branches)\n[](https://pypi.python.org/pypi/prometheus_speedtest/)\n[](https://hub.docker.com/r/jraviles/prometheus_speedtest)\n[](https://pypi.python.org/pypi/prometheus_speedtest/)\n[](https://pypi.python.org/pypi/prometheus_speedtest/)\n[](https://pypi.python.org/pypi/prometheus_speedtest/)\n\n\n\n## Getting Started\n\nThese instructions will install and run `prometheus_speedtest` on your system.\n\n### PyPi Package\n\n`prometheus_speedtest` is provided as a\n[PyPi package](https://pypi.org/project/prometheus_speedtest).\n\n1. Installing\n\n ```shell\n pip install prometheus_speedtest\n ```\n\n1. Running\n\n ```shell\n prometheus_speedtest\n ```\n\n#### Usage\n\n```\nInstrument speedtest.net speedtests from Prometheus.\nflags:\n\nprometheus_speedtest.py:\n --address: address to listen on\n (default: '0.0.0.0')\n --excludes: speedtest server(s) to exclude - leave empty for no exclusion\n (a comma separated list)\n --port: port to listen on\n (default: '9516')\n (an integer)\n --servers: speedtest server(s) to use - leave empty for auto-selection\n (a comma separated list)\n --[no]version: show version\n (default: 'false')\n```\n\n### Running with Docker\n\n`prometheus_speedtest` is also available as a [Docker](http://docker.com) image\non [Docker Hub](https://hub.docker.com/r/jraviles/prometheus_speedtest)\n:whale:.\n\n```shell\ndocker run --rm -d --name prometheus_speedtest -p 9516:9516/tcp jraviles/prometheus_speedtest:latest\n```\n\nYou can also append extra flags when running with Docker. For example:\n\n```shell\n$ docker run --rm --name prometheus_speedtest -p 9516:9516/tcp \\\n jraviles/prometheus_speedtest:latest --version\nprometheus_speedtest v0.9.9\n```\n\n### Running with Kubernetes\n\nSince you can run this from a Docker container, you can also run it in Kubernetes.\n\n```shell\nkubectl apply -f deploy/namespace.yaml\nkubectl apply -f deploy/deployment.yaml\n```\n\nThe Kubernetes YAML files are pre-configured to work with the\n`kubernetes-pods-slow` job that comes with Prometheus, which is configured with\n5m scrape times and 30s timeouts. If you need to raise the timeout, you'll\nneed to change that in your Prometheus config map.\n\nJust keep in mind, that if you increase the replica count, then Prometheus will\nrun a speedtest for each pod, every 5m. The same goes for if you are running\nmore than one replica of Prometheus, as each replica independently scrapes\ntargets.\n\n### Integrating with Prometheus\n\n`prometheus_speedtest` is best when paired with\n[Prometheus](https://prometheus.io). Prometheus can be configured to perform\nSpeedtests on an interval and record their results.\n\nSpeedtest metrics available to query in Prometheus.\n\n| Metric Name | Description |\n|---------------------- |---------------------------- |\n| download\\_speed\\_bps | Download speed (bit/s) |\n| upload\\_speed\\_bps | Upload speed (bit/s) |\n| ping\\_ms | Latency (ms) |\n| bytes\\_received | Bytes received during test |\n| bytes\\_sent | Bytes sent during test |\n\n#### prometheus.yml config\n\nAdd this to your\n[Prometheus config](https://prometheus.io/docs/prometheus/latest/configuration/configuration)\nto start instrumenting Speedtests and recording their metrics.\n\n```yaml\nglobal:\n scrape_timeout: 2m\n\nscrape_configs:\n- job_name: 'speedtest'\n metrics_path: /probe\n static_configs:\n - targets:\n - localhost:9516\n```\n\nNote if you're running `prometheus` under Docker, you must link the\n`prometheus` container to `prometheus_speedtest`. See the steps below for how\nthis can be done.\n\n#### Trying it out\n\nAn example\n[Prometheus config](https://prometheus.io/docs/prometheus/latest/configuration/configuration)\nhas been provided at\n[example/prometheus.yml](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/example/prometheus.yml).\nWe'll start `prometheus` with this config.\n\n1. Docker Network\n\n Create the [Docker network](https://docs.docker.com/network) that will link\n `prometheus_speedtest` and `prometheus` together.\n\n ```shell\n docker network create prometheus_network\n ```\n\n1. Start Prometheus Speedtest\n\n ```shell\n docker run --rm -d --net prometheus_network -p 9516:9516/tcp \\\n --name prometheus_speedtest jraviles/prometheus_speedtest:latest\n ```\n\n1. Start Prometheus\n\n ```shell\n docker run --rm -d --net prometheus_network -p 9516:9516/tcp \\\n -v $PWD/example/prometheus.yml:/etc/prometheus/prometheus.yml \\\n --name prometheus prom/prometheus:latest\n ```\n\n1. Query results\n\n * Visit <http://localhost:9516/probe>\n\n * Wait around **45 seconds** for Prometheus to perform a Speedtest\n\n * Issue a query for **download\\_speed\\_bps**\n\n You should see something like this.\n\n \n\n### Instrumenting Speedtests with cURL\n\nOnce `prometheus_speedtest` has been started, with either Docker or PyPi,\nSpeedtests can be instrumented with [cURL](https://curl.haxx.se).\n\n```shell\n$ curl localhost:9516/probe\n# HELP download_speed_bps Download speed (bit/s)\n# TYPE download_speed_bps gauge\ndownload_speed_bps 88016694.95692767\n# HELP upload_speed_bps Upload speed (bit/s)\n# TYPE upload_speed_bps gauge\nupload_speed_bps 3415613.277989314\n# HELP ping_ms Latency (ms)\n# TYPE ping_ms gauge\nping_ms 20.928\n# HELP bytes_received Bytes received during test\n# TYPE bytes_received gauge\nbytes_received 111342756.0\n# HELP bytes_sent Bytes sent during test\n# TYPE bytes_sent gauge\nbytes_sent 5242880.0\n```\n\nYou can also visit <http://localhost:9516/probe> in your browser to see the same\nmetrics.\n\n### Default Port\n\nPrometheus Speedtest defaults to running on port 9516; this is the allocated\nport for this exporter in the\n[Prometheus Default Port Allocations Guide](https://github.com/prometheus/prometheus/wiki/Default-port-allocations).\n\n## Getting Started (Development)\n\nThese instructions will get you a copy `prometheus_speedtest` up and running on\nyour local machine for development and testing purposes.\n\n### Prerequisites\n\n* [Python](https://www.python.org)\n* [Docker](https://www.docker.com)\n* [Pytest](https://pytest.org)\n\n### Running Locally\n\n#### Python\n\n1. Ensure packages listed in\n [requirements.txt](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/requirements.txt)\n are installed with `pip`\n\n ```python\n pip3 install -r requirements.txt\n ```\n\n1. Run `prometheus_speedtest`\n\n ```python\n python3 -m prometheus_speedtest.prometheus_speedtest\n ```\n\n#### Docker\n\n1. Building image\n\n ```shell\n docker build -t prometheus_speedtest:latest .\n ```\n\n1. Running\n\n ```shell\n docker run --rm -d --name prometheus_speedtest -p 9516:9516/tcp prometheus_speedtest:latest\n ```\n\n### Perform a Speedtest\n\n```shell\ncurl localhost:9516/probe\n```\n\nOr visit <http://localhost:9516/probe>\n\n### Running Unit Tests\n\n```shell\npytest\n```\n\n### Contributing\n\nPull requests are welcome. Please adhere to the\n[Google Python style guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).\n\nPlease format your contributions with the\n[yapf](https://github.com/google/yapf) formatter and lint your code with\n[pylint](https://www.pylint.org). A\n[.pylintrc](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/.pylintrc)\nconfig has been provided.\n\n```shell\nyapf -i **/*.py\npylint **/*.py\npytype\n```\n\n## Grafana Dashboard Template\n\nUser Do\u011fukan \u00c7a\u011fatay has created a Grafana dashboard template for\nprometheus_speedtest. Go check it out on\n[grafana.com](https://grafana.com/grafana/dashboards/11229).\n\n## Maintenance\n\n### Deploying to PyPi\n\n1. Increment version number in\n [version.py](https://github.com/jeanralphaviles/prometheus_speedtest/blob/master/prometheus_speedtest/version.py)\n\n1. Create PyPi package\n\n ```shell\n python3 setup.py sdist\n ```\n\n1. Upload package to PyPi\n\n Ensure that [Twine](https://github.com/pypa/twine) has been installed.\n\n ```shell\n twine upload dist/*\n ```\n\n### Deploying multi-architecture images to Docker Hub\n\n1. Ensure that Docker >= 19.03 and\n [docker buildx](https://docs.docker.com/buildx/working-with-buildx/) is\n installed.\n\n1. Build and push the new image.\n\n ```shell\n # Ensure you have run 'docker login'\n export DOCKER_CLI_EXPERIMENTAL=enabled\n # https://github.com/docker/buildx/issues/495#issuecomment-754688157\n docker run --rm --privileged multiarch/qemu-user-static --reset -p yes\n docker buildx create --use --name my-builder\n TAG=\"$(python3 -m prometheus_speedtest.prometheus_speedtest --version \\\n | cut -d 'v' -f 2)\"\n docker buildx build --push --platform linux/amd64,linux/arm64,linux/arm/v7 \\\n -t jraviles/prometheus_speedtest:latest \\\n -t jraviles/prometheus_speedtest:${TAG:?} .\n docker buildx rm my-builder\n ```\n\n## Authors\n\n* Jean-Ralph Aviles\n\n## License\n\nThis product is licensed under the Apache 2.0 license. See [LICENSE](LICENSE)\nfile for details.\n\n## Acknowledgments\n\n* Matt Martz [speedtest-cli](https://github.com/sivel/speedtest-cli)\n* The Prometheus team <https://prometheus.io>\n* Testing in Python team <http://lists.idyll.org/listinfo/testing-in-python>\n* Benjamin Staffin [python-glog](https://github.com/benley/python-glog)\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Performs speedtest-cli tests and pushes metrics to Prometheus Pushgateway",
"version": "0.9.14",
"split_keywords": [
"prometheus",
"monitoring",
"speedtest",
"speedtest.net"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "7339d144f29432143081f4243f085bad",
"sha256": "65f89384b584d24bb6bdf7db0156829efdd946a3392b9b504e20a2172a43d1d2"
},
"downloads": -1,
"filename": "prometheus_speedtest-0.9.14.tar.gz",
"has_sig": false,
"md5_digest": "7339d144f29432143081f4243f085bad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19751,
"upload_time": "2022-12-30T14:03:25",
"upload_time_iso_8601": "2022-12-30T14:03:25.584494Z",
"url": "https://files.pythonhosted.org/packages/4a/9f/60a3c4a17abec9e0629520eabd148255cb45e5dfc62bfec5326b5a5cdfda/prometheus_speedtest-0.9.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-30 14:03:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jeanralphaviles",
"github_project": "prometheus_speedtest",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "absl-py",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "prometheus_client",
"specs": [
[
"==",
"0.15.0"
]
]
},
{
"name": "speedtest-cli",
"specs": [
[
"==",
"2.1.3"
]
]
}
],
"lcname": "prometheus-speedtest"
}
JSON
