🚄 IPERF3EXPORTER 💨

A iperf3 speedtest exporter for prometheus

It runs the iperf3 command as client. Once as server sends/client receives and once as client sends/server receives. It parses the JSON output and exports them as prometheus metrics.

Installation

via docker

docker run -d --name iperf3exporter ghcr.io/xsteadfastx/iperf3exporter:latest

Notice: Please use a fixed version for productive use!

via package

You can get apt, rpm and apk packages on the release page. They also include an init file.

via archive

For easy testing you can download the tar.gz-archive from the release page, extract it and run it.

Usage

Usage:
  iperf3exporter [flags]

Flags:
  -c, --config string      config file
  -h, --help               help for iperf3exporter
      --listen string      listen string (default "127.0.0.1:9119")
      --log-colors         colorful log output (default true)
      --log-json           JSON log output
      --process-metrics    exporter process metrics (default true)
      --time int           time in seconds to transmit for (default 5)
      --timeout duration   scraping timeout (default 1m0s)
  -v, --version            print version
      --wait duration      time to wait between download and upload runs (default 1s)

Configuration

File

All flags can also be set through a config file. Here is an example:

[exporter] # everything related to the exporter itself
listen = "0.0.0.0:9119" # connection string for the webserver
timeout = "1m" # timeout of the iperf3 command to run
process_metrics = true # export go process metrics

[log]
json = true # enables json log output
colors = false # disable colors. this is only usable if log.json is set to false

[iperf3] # straight up iperf3 command line flag options
time = 10 # this sets the --time flag of iperf3 to 10
wait = "10s" # wait time between download and upload scrape

Environment variables

Its also possible to set this settings through environment variables. The environment prefix is IPERF3EXPORTER.

# this will disable colorful logs
IPERF3EXPORTER_LOG_COLORS=false /usr/local/bin/iperf3exporter

# this sets the iperf3 time flag to 10 seconds
IPERF3EXPORTER_IPERF3_TIME=10 /usr/local/bin/iperf3exporter

Example prometheus config

scrape_configs:
  - job_name: speedtest-myfunnybox
    scrape_interval: 2m # maybe a even higher interval would be useful. not fill the whole traffic just with speedtests ;-)
    scrape_timeout: 1m # a little higher timeout. because the scrape can take a while
    metrics_path: /probe
    static_configs:
      - targets:
          - speedtest.wobcom.de # default port 5201 is used
          - footest.bar.tld:1234 # target with defined port
    relabel_configs:
      # takes the address from the targets and uses it as url parameter key `target`
      - source_labels: [__address__]
        target_label: __param_target

      # takes that address and stores it in the label `instance`
      - source_labels: [__param_target]
        target_label: instance

      # replaces the scrape address with the real hostname:port of the exporter.
      # so it can use the targets for defining the iperf3 servers to use.
      - target_label: __address__
        replacement: 192.168.39.191:9119

In this example it replaces the targets with the real exporter adress and adds a label host that can be used to identify the scrape boxes and not just the iperf3 servers to test against.

You can specify a port for the iperf3 server target. If its not set, it will use the default port 5201.

Exposed metrics

name	type
iperf3_download_sent_bits_per_second	gauge
iperf3_download_sent_seconds	gauge
iperf3_download_sent_bytes	gauge
iperf3_download_sent_retransmits	gauge
iperf3_download_received_bits_per_second	gauge
iperf3_download_received_seconds	gauge
iperf3_download_received_bytes	gauge
iperf3_upload_sent_bits_per_second	gauge
iperf3_upload_sent_seconds	gauge
iperf3_upload_sent_bytes	gauge
iperf3_upload_sent_retransmits	gauge
iperf3_upload_received_bits_per_second	gauge
iperf3_upload_received_seconds	gauge
iperf3_upload_received_bytes	gauge
iperf3_errors	counter