https://github.com/mgumz/speedtest-exporter
A Prometheus exporter for speedtest-go metrics
https://github.com/mgumz/speedtest-exporter
metrics network-analysis network-performance ookla prometheus prometheus-exporter speedtest speedtest-go
Last synced: 5 months ago
JSON representation
A Prometheus exporter for speedtest-go metrics
- Host: GitHub
- URL: https://github.com/mgumz/speedtest-exporter
- Owner: mgumz
- License: bsd-3-clause
- Created: 2025-05-04T11:57:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-08T13:30:53.000Z (12 months ago)
- Last Synced: 2025-08-09T21:51:26.658Z (10 months ago)
- Topics: metrics, network-analysis, network-performance, ookla, prometheus, prometheus-exporter, speedtest, speedtest-go
- Language: Go
- Homepage:
- Size: 86.9 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# speedtest-exporter
[](https://goreportcard.com/report/github.com/mgumz/speedtest-exporter)
**speedtest-exporter** periodically executes [speedtest-go] to given servers and provides the
measured results as [prometheus] metrics on an HTTP endpoint.
Usually, [speedtest-go] is producing the following output:
$> speedtest-go -s 00001
speedtest-go v1.7.10 (git-dev) @showwin
⠸ Retrieving User Information
✓ ISP: 192.0.2.1 (ACME Sponsor) [0.123, 0.456]
✓ Found 1 Specified Public Server(s)
✓ Test Server: [00001] 2.78km Example City by ACME Sponsor
✓ Latency: 13.266299ms Jitter: 1.563479ms Min: 11.066208ms Max: 16.269875ms
✓ Packet Loss Analyzer: Running in background (<= 30 Secs)
✓ Download: 56.17 Mbps (Used: 71.18MB) (Latency: 40ms Jitter: 9ms Min: 16ms Max: 53ms)
✓ Upload: 54.34 Mbps (Used: 71.26MB) (Latency: 46ms Jitter: 30ms Min: 16ms Max: 121ms)
✓ Packet Loss: N/A
`speedtest-exporter` exposes the measured values like this at the `/metrics`
endpoint:
# 1 speedtest jobs defined
# speedtest run speedtest-exporter-cli: 2025-04-13T13:43:46.002883Z -- speedtest-go --json -s 00001
speedtest_runs_total{speedtest_exporter_job="speedtest-exporter-cli",error=""} 1 1744551826002
speedtest_duration_seconds{speedtest_exporter_job="speedtest-exporter-cli"} 23.945700 1744551826002
speedtest_dl_speed{speedtest_exporter_job="speedtest-exporter-cli"} 7120217 1744551826002
speedtest_ul_speed{speedtest_exporter_job="speedtest-exporter-cli"} 6932864 1744551826002
speedtest_jitter{speedtest_exporter_job="speedtest-exporter-cli"} 1477440 1744551826002
speedtest_latency{speedtest_exporter_job="speedtest-exporter-cli"} 14383537 1744551826002
speedtest_max_latency{speedtest_exporter_job="speedtest-exporter-cli"} 18016083 1744551826002
speedtest_min_latency{speedtest_exporter_job="speedtest-exporter-cli"} 12627166 1744551826002
speedtest_test_duration_ping{speedtest_exporter_job="speedtest-exporter-cli"} 2425575666 1744551826002
speedtest_test_duration_download{speedtest_exporter_job="speedtest-exporter-cli"} 10051649083 1744551826002
speedtest_test_duration_upload{speedtest_exporter_job="speedtest-exporter-cli"} 10050837042 1744551826002
speedtest_test_duration_total{speedtest_exporter_job="speedtest-exporter-cli"} 22528061791 1744551826002
When [prometheus] scrapes the data, you can visualise the observed values:
## Usage
Usage: speedtest-exporter [FLAGS] -- [SPEEDTEST-GO-FLAGS]
FLAGS:
-bind
bind address (default ":8080")
-h
show help
-jobs
file describing multiple speedtest-jobs. syntax is given below.
-label
use in prometheus-metrics (default: "speedtest-exporter-cli")
-log-level
either of "debug", "info" (default), "warn", "error"
-speedtest
path to speedtest-go binary (default: "speedtest-go")
-schedule
schedule at which often speedtest-go is launched (default: "@every 24h")
examples:
@every - example "@every 24h"
@hourly - run once per hour
10 * * * * - execute 10 minutes after the full hour
see https://en.wikipedia.org/wiki/Cron
-timeshift
timeshift around the point in time when -schedule would trigger otherwise
(default: "" - no timeshift)
-watch-jobs
periodically watch the file defined via -jobs (default: "")
if it has changed stop previously running speedtest-jobs and apply
all jobs defined in -jobs.
-show-license
show license
-show-version
show version
SPEEDTEST-GO-FLAGS:
see "speedtest-go" for valid flags.
### HTTP Endpoints
* /metrics - metrics in prometheus format
* /health - endpoint to indicate the healthieness
* / - small info page with link to /metrics
### Examples
$> speedtest-exporter -schedule "@every 24h" -- -s 00001
### Jobs-File Syntax
# comment lines start with '#' are ignored
# empty lines are ignored as well
label -- -- speedtest-go-flags
`` - a schedule expression which follows one of
* `* * * * *` - a cron expression, see https://en.wikipedia.org/wiki/Cron
* `@hourly` | `@daily` etc - see https://pkg.go.dev/github.com/robfig/cron/v3#hdr-Predefined_schedules
* `@every ` - execute [speedtest-go] in an interval
Optionally, if the `` has a suffix of ``, the actual
execution of the job is, well, shifted. This is a **very** advisable feature to
use: `speedtest` usually causes a noticeable amount of traffic, not only on
the users side but _mainly_ on the server side as well as the hops in between.
**NOTE**: To minimize the concerted effect a `speedtest` run might cause: use
`timeshifts` to deviate or to delay the actual execution by a random amount!
`` - Different timeshift expressions in the Jobs-File are supported.
* `~` - adds a random delay to the otherwise planned point in time.
Example given: `@every 1h ~10m` will trigger the job
somewhen in the range of xx:00 to xx:10. The effective range
is given as `[]`.
Examples:
# measure each midnight (+ a random timshift of up to 10 minutes) the speed to server 00001
nightly -- @midnight ~10m -- -s 00001
# measure only connectivity every hour, no real up or download
connectivity -- @every 1h -- -s 00001 --no-upload --no-download
# measure first of month
monthly -- 0 * 1 * * -- -s 00001
### Signals
* USR1 - print the currently active schedule of jobs to the logs
## Requirements
Runtime:
* speedtest-go
* a reachable speedtest server (see [here](https://support.ookla.com/hc/en-us/articles/234578528-OoklaServer-Installation-Linux-Unix) to host your own)
Build:
* golang-1.24 and newer
## Building
$> git clone https://github.com/mgumz/speedtest-exporter
$> cd speedtest-exporter
$> make
One-off building and "installation":
$> go install github.com/mgumz/speedtest-exporter/cmd/speedtest-exporter@latest
## OCI Images
OCI images for `linux/amd64` platform are available for recent releases under
https://github.com/mgumz/speedtest-exporter/pkgs/container/speedtest-exporter
Make sure to preserve the ENTRY command to benefit from the default
[krallin/tini](s://github.com/krallin/tini) zombie. In kubernetes, this
translates into omitting the `command` and only specifying `args` for passing
speedtest-exporter
```yaml
containers:
- name: speedtest-prometheus-collector
image: ghcr.io/mgumz/speedtest-exporter:
# Note: We need to override the container entry point which is an
# array ENTRYPOINT ["/sbin/tini", "--", "/usr/bin/speedtest-exporter"]
# Only the fist element end up in the container `command`, and the two
# others end up in the default `args` value
command:
- "/sbin/tini"
- "--"
- "/usr/bin/speedtest-exporter"
- "-schedule"
- "@every 24h"
- "--"
- "-s"
- "00001"
```
## License
see LICENSE file
## Author(s)
* Mathias Gumz
## Related Projects
[speedtest-go]: https://github.com/showwin/speedtest-go
[prometheus]: https://prometheus.io
[speedtest-homeassistant]: https://www.home-assistant.io/integrations/speedtestdotnet