A Prometheus exporter for iPerf3 network performance metrics.

The Docker image has moved to GitHub Container Registry (ghcr.io) and the name has changed from iperf3-exporter to iperf3_exporter following GitHub's naming standards. If you were using the old image name, please update your references.

The iPerf3 exporter allows iPerf3 probing of endpoints for Prometheus monitoring, enabling you to measure network performance metrics like bandwidth, jitter, and packet loss.

• Measure network bandwidth between hosts
• Monitor network performance over time
• Support for both TCP and UDP tests
• Configurable test parameters (duration, bitrate, etc.)
• TLS support for secure communication
• Basic authentication for access control
• Health and readiness endpoints for monitoring
• Prometheus metrics for exporter itself

Download the most suitable binary for your platform from the releases tab.

# Download (replace VERSION and PLATFORM with appropriate values)
curl -L -o iperf3_exporter https://github.com/edgard/iperf3_exporter/releases/download/VERSION/iperf3_exporter-VERSION.PLATFORM

# Make executable
chmod +x iperf3_exporter

# Run
./iperf3_exporter <flags>

Note: iperf3 binary should also be installed and accessible from the path.

docker run --rm -d -p 9579:9579 --name iperf3_exporter ghcr.io/edgard/iperf3_exporter:latest

The Docker images are available for multiple architectures (amd64, arm64) and are published to GitHub Container Registry.

# Clone repository
git clone https://github.com/edgard/iperf3_exporter.git
cd iperf3_exporter

# Build
go build -o iperf3_exporter ./cmd/iperf3_exporter

# Run
./iperf3_exporter

./iperf3_exporter [flags]

iPerf3 exporter is configured via command-line flags:

The exporter supports a configuration file for TLS and authentication settings. This file is specified with the --web.config.file flag.

Example configuration file:

tls_server_config:
  cert_file: server.crt
  key_file: server.key

basic_auth_users:
  username: password

For more details on the web configuration file format, see the exporter-toolkit documentation.

To view all available command-line flags, run:

./iperf3_exporter -h

The timeout of each probe is automatically determined from the scrape_timeout in the Prometheus config. This can be also be limited by the iperf3.timeout command-line flag. If neither is specified, it defaults to 30 seconds.

When making requests to the /probe endpoint, the following parameters can be used:

Visit http://localhost:9579 to see the exporter's web interface.

The iPerf3 exporter needs to be passed the target as a parameter, this can be done with relabelling.

Example config:

scrape_configs:
  - job_name: 'iperf3'
    metrics_path: /probe
    static_configs:
      - targets:
        - foo.server
        - bar.server
    params:
      port: ['5201']
      # Optional: enable reverse mode
      # reverse_mode: ['true']
      # Optional: set bitrate limit
      # bitrate: ['100M']
      # Optional: set test period
      # period: ['10s']
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9579  # The iPerf3 exporter's real hostname:port.

The exporter provides the following metrics:

Additionally, the exporter provides metrics about itself:

You can use the following Prometheus queries to calculate bandwidth in Mbits/sec:

rate(iperf3_received_bytes{instance="target"}[1m]) * 8 / 1000000

rate(iperf3_sent_bytes{instance="target"}[1m]) * 8 / 1000000

These queries use the rate() function to calculate the per-second rate from the counter metrics, then convert from bytes to bits (multiply by 8) and from bits to megabits (divide by 1,000,000).

Contributions to the iperf3_exporter are welcome!

This project follows the Conventional Commits specification. When contributing, please format your commit messages according to this standard:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Examples:

• feat: add support for UDP tests
• fix: correct metric label in collector
• docs: update installation instructions
• refactor(collector): simplify error handling

• Go 1.24 or higher
• iperf3 installed on your system

.
├── cmd/
│   └── iperf3_exporter/     # Main application entry point
├── internal/
│   ├── collector/           # Prometheus collector implementation
│   ├── config/              # Configuration handling
│   ├── iperf/               # iperf3 command execution and result parsing
│   └── server/              # HTTP server implementation
├── tests/
│   └── e2e/                 # End-to-end tests
├── .github/
│   └── workflows/           # GitHub Actions workflows
├── .goreleaser.yml          # GoReleaser configuration
├── Dockerfile               # Multi-arch Docker build configuration
├── go.mod                   # Go module definition
└── README.md                # This file

The project uses a Makefile to streamline development tasks:

# Build the binary
make build

# Run all tests
make test

# Complete development workflow (run mod, generate, lint, vet, tests and build)
make all

# Tidy and download dependencies
make mod

# Run linting
make lint

# Run go vet
make vet

# Generate code (if any generators are configured)
make generate

# Build Docker image for local development
make docker

# See all available commands
make help

You can also use standard Go commands directly:

# Build manually
go build -o iperf3_exporter ./cmd/iperf3_exporter

# Run tests
go test ./...

This project is released under Apache License 2.0, see LICENSE.