{"id":13582543,"url":"https://github.com/edgard/iperf3_exporter","last_synced_at":"2025-04-06T14:31:01.228Z","repository":{"id":34809133,"uuid":"183559938","full_name":"edgard/iperf3_exporter","owner":"edgard","description":"Simple server that probes iPerf3 endpoints and exports results via HTTP for Prometheus consumption","archived":false,"fork":false,"pushed_at":"2025-03-19T01:38:17.000Z","size":101,"stargazers_count":70,"open_issues_count":0,"forks_count":29,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-19T02:35:03.138Z","etag":null,"topics":["go","iperf3","iperf3-exporter","metrics","prometheus","prometheus-exporter"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edgard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-26T05:00:18.000Z","updated_at":"2025-03-19T01:38:21.000Z","dependencies_parsed_at":"2024-06-20T01:40:05.257Z","dependency_job_id":"b0fc8bb4-238f-4394-b99f-5dbdd04f198d","html_url":"https://github.com/edgard/iperf3_exporter","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgard%2Fiperf3_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgard%2Fiperf3_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgard%2Fiperf3_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgard%2Fiperf3_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edgard","download_url":"https://codeload.github.com/edgard/iperf3_exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247495781,"owners_count":20948107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","iperf3","iperf3-exporter","metrics","prometheus","prometheus-exporter"],"created_at":"2024-08-01T15:02:49.092Z","updated_at":"2025-04-06T14:31:01.222Z","avatar_url":"https://github.com/edgard.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# iPerf3 Exporter\n\nA Prometheus exporter for iPerf3 network performance metrics.\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/edgard/iperf3_exporter)](https://goreportcard.com/report/github.com/edgard/iperf3_exporter)\n[![Docker Pulls](https://img.shields.io/docker/pulls/ghcr.io/edgard/iperf3_exporter.svg)](https://github.com/users/edgard/packages/container/package/iperf3_exporter)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/edgard/iperf3_exporter/blob/master/LICENSE)\n\n## ⚠️ IMPORTANT: Docker Image Name Change\n\n**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.**\n\nThe iPerf3 exporter allows iPerf3 probing of endpoints for Prometheus monitoring, enabling you to measure network performance metrics like bandwidth, jitter, and packet loss.\n\n## Features\n\n- Measure network bandwidth between hosts\n- Monitor network performance over time\n- Support for both TCP and UDP tests\n- Configurable test parameters (duration, bitrate, etc.)\n- TLS support for secure communication\n- Basic authentication for access control\n- Health and readiness endpoints for monitoring\n- Prometheus metrics for exporter itself\n\n## Installation\n\n### From Binaries\n\nDownload the most suitable binary for your platform from [the releases tab](https://github.com/edgard/iperf3_exporter/releases).\n\n```bash\n# Download (replace VERSION and PLATFORM with appropriate values)\ncurl -L -o iperf3_exporter https://github.com/edgard/iperf3_exporter/releases/download/VERSION/iperf3_exporter-VERSION.PLATFORM\n\n# Make executable\nchmod +x iperf3_exporter\n\n# Run\n./iperf3_exporter \u003cflags\u003e\n```\n\n*Note: [iperf3](https://iperf.fr/) binary should also be installed and accessible from the path.*\n\n### Using Docker\n\n```bash\ndocker run --rm -d -p 9579:9579 --name iperf3_exporter ghcr.io/edgard/iperf3_exporter:latest\n```\n\nThe Docker images are available for multiple architectures (amd64, arm64) and are published to GitHub Container Registry.\n\n### Building from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/edgard/iperf3_exporter.git\ncd iperf3_exporter\n\n# Build\ngo build -o iperf3_exporter ./cmd/iperf3_exporter\n\n# Run\n./iperf3_exporter\n```\n\n## Usage\n\n### Starting the Exporter\n\n```bash\n./iperf3_exporter [flags]\n```\n\n### Configuration\n\niPerf3 exporter is configured via command-line flags:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--web.listen-address` | Addresses on which to expose metrics and web interface (repeatable) | `:9579` |\n| `--web.telemetry-path` | Path under which to expose metrics | `/metrics` |\n| `--web.probe-path` | Path under which to expose the probe endpoint | `/probe` |\n| `--iperf3.timeout` | iperf3 run timeout | `30s` |\n| `--web.config.file` | Path to configuration file that can enable TLS or authentication | |\n| `--web.systemd-socket` | Use systemd socket activation listeners instead of port listeners (Linux only) | `false` |\n| `--log.level` | Only log messages with the given severity or above | `info` |\n| `--log.format` | Output format of log messages | `logfmt` |\n\n#### Web Configuration File\n\nThe exporter supports a configuration file for TLS and authentication settings. This file is specified with the `--web.config.file` flag.\n\nExample configuration file:\n\n```yaml\ntls_server_config:\n  cert_file: server.crt\n  key_file: server.key\n\nbasic_auth_users:\n  username: password\n```\n\nFor more details on the web configuration file format, see the [exporter-toolkit documentation](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md).\n\nTo view all available command-line flags, run:\n\n```bash\n./iperf3_exporter -h\n```\n\nThe timeout of each probe is automatically determined from the `scrape_timeout` in the [Prometheus config](https://prometheus.io/docs/operating/configuration/#configuration-file).\nThis can be also be limited by the `iperf3.timeout` command-line flag. If neither is specified, it defaults to 30 seconds.\n\n### Probe Parameters\n\nWhen making requests to the `/probe` endpoint, the following parameters can be used:\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `target` | Target host to probe (required) | - |\n| `port` | Port that the target iperf3 server is listening on | 5201 |\n| `reverse_mode` | Run iperf3 in reverse mode (server sends, client receives) | false |\n| `udp_mode` | Run iperf3 in UDP mode instead of TCP | false |\n| `bitrate` | Target bitrate in bits/sec (format: #[KMG][/#]). For UDP mode, iperf3 defaults to 1 Mbit/sec if not specified. | - |\n| `period` | Duration of the iperf3 test | 5s |\n\n### Checking the Results\n\nVisit [http://localhost:9579](http://localhost:9579) to see the exporter's web interface.\n\n## Prometheus Configuration\n\nThe iPerf3 exporter needs to be passed the target as a parameter, this can be done with relabelling.\n\nExample config:\n```yml\nscrape_configs:\n  - job_name: 'iperf3'\n    metrics_path: /probe\n    static_configs:\n      - targets:\n        - foo.server\n        - bar.server\n    params:\n      port: ['5201']\n      # Optional: enable reverse mode\n      # reverse_mode: ['true']\n      # Optional: enable UDP mode\n      # udp_mode: ['true']\n      # Optional: set bitrate limit\n      # bitrate: ['100M']\n      # Optional: set test period\n      # period: ['10s']\n    relabel_configs:\n      - source_labels: [__address__]\n        target_label: __param_target\n      - source_labels: [__param_target]\n        target_label: instance\n      - target_label: __address__\n        replacement: 127.0.0.1:9579  # The iPerf3 exporter's real hostname:port.\n```\n\n### Available Metrics\n\nThe exporter provides the following metrics:\n\n| Metric | Description | Labels |\n|--------|-------------|--------|\n| `iperf3_up` | Was the last iperf3 probe successful (1 for success, 0 for failure) | `target`, `port` |\n| `iperf3_sent_seconds` | Total seconds spent sending packets | `target`, `port` |\n| `iperf3_sent_bytes` | Total sent bytes for the last test run | `target`, `port` |\n| `iperf3_received_seconds` | Total seconds spent receiving packets | `target`, `port` |\n| `iperf3_received_bytes` | Total received bytes for the last test run | `target`, `port` |\n| `iperf3_retransmits` | Total retransmits for the last test run (TCP mode only, omitted in UDP) | `target`, `port` |\n| `iperf3_sent_packets` | Total sent packets for the last UDP test run (UDP mode only) | `target`, `port` |\n| `iperf3_sent_jitter_ms` | Jitter in milliseconds for sent packets (UDP mode only) | `target`, `port` |\n| `iperf3_lost_packets` | Total lost packets for the last UDP test run (UDP mode only) | `target`, `port` |\n| `iperf3_lost_percent` | Percentage of packets lost for the last UDP test run (UDP mode only) | `target`, `port` |\n\nAdditionally, the exporter provides metrics about itself:\n\n| Metric | Description |\n|--------|-------------|\n| `iperf3_exporter_duration_seconds` | Duration of collections by the iperf3 exporter |\n| `iperf3_exporter_errors_total` | Errors raised by the iperf3 exporter |\n\n### Querying the Bandwidth\n\nYou can use the following Prometheus queries to calculate bandwidth in Mbits/sec:\n\n#### Receiver Bandwidth (Download Speed)\n```\nrate(iperf3_received_bytes{instance=\"target\"}[1m]) * 8 / 1000000\n```\n\n#### Sender Bandwidth (Upload Speed)\n```\nrate(iperf3_sent_bytes{instance=\"target\"}[1m]) * 8 / 1000000\n```\n\nThese 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).\n\n## Contributing\n\nContributions to the iperf3_exporter are welcome!\n\nThis project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. When contributing, please format your commit messages according to this standard:\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e\n\n[optional body]\n\n[optional footer(s)]\n```\n\nExamples:\n- `feat: add support for UDP tests`\n- `fix: correct metric label in collector`\n- `docs: update installation instructions`\n- `refactor(collector): simplify error handling`\n\n### Development Prerequisites\n\n- Go 1.24 or higher\n- iperf3 installed on your system\n\n### Project Structure\n\n```\n.\n├── cmd/\n│   └── iperf3_exporter/     # Main application entry point\n├── internal/\n│   ├── collector/           # Prometheus collector implementation\n│   ├── config/              # Configuration handling\n│   ├── iperf/               # iperf3 command execution and result parsing\n│   └── server/              # HTTP server implementation\n├── tests/\n│   └── e2e/                 # End-to-end tests\n├── .github/\n│   └── workflows/           # GitHub Actions workflows\n├── .goreleaser.yml          # GoReleaser configuration\n├── Dockerfile               # Multi-arch Docker build configuration\n├── go.mod                   # Go module definition\n└── README.md                # This file\n```\n\n### Building and Testing\n\nThe project uses a Makefile to streamline development tasks:\n\n```bash\n# Build the binary\nmake build\n\n# Run all tests\nmake test\n\n# Complete development workflow (run mod, generate, lint, vet, tests and build)\nmake all\n\n# Tidy and download dependencies\nmake mod\n\n# Run linting\nmake lint\n\n# Run go vet\nmake vet\n\n# Generate code (if any generators are configured)\nmake generate\n\n# Build Docker image for local development\nmake docker\n\n# See all available commands\nmake help\n```\n\nYou can also use standard Go commands directly:\n\n```bash\n# Build manually\ngo build -o iperf3_exporter ./cmd/iperf3_exporter\n\n# Run tests\ngo test ./...\n```\n\n## License\n\nThis project is released under Apache License 2.0, see [LICENSE](https://github.com/edgard/iperf3_exporter/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgard%2Fiperf3_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedgard%2Fiperf3_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgard%2Fiperf3_exporter/lists"}