SpeedBench

A network performance testing tool that measures download speeds, connection timings, and network metrics using aria2c.

Features

• Download Speed Testing: Measure download speeds with configurable iterations
• Connection Metrics: Track DNS lookup, TCP connection, and SSL handshake timings
• Statistical Analysis: Calculate percentiles (P50, P95, P99), standard deviation, and aggregate metrics
• StatsD Export: Export metrics to StatsD for monitoring and visualization
• Grafana Dashboard: Pre-configured dashboard for visualizing network performance
• Multiple Deployment Options: Docker, Kubernetes, systemd, and more

Quick Start

Using Docker

docker run --rm ghcr.io/anonc0der/speedbench:latest \
  --url https://example.com/test-file.bin \
  --times 5 \
  --source "my-server" \
  --target "cdn-1"

Using the Binary

# Build locally
make build-local

# Run
./bin/speedbench --url https://example.com/test-file.bin --times 5

Installation

Prerequisites

• Go 1.25.4 or later (for building from source)
• aria2c (automatically included in Docker image)
• Docker (optional, for containerized usage)

Docker Image

The official Docker image is available on GitHub Container Registry:

docker pull ghcr.io/anonc0der/speedbench:latest

Building from Source

# Clone the repository
git clone https://github.com/AnonC0DER/SpeedBench.git
cd SpeedBench

# Build locally
make build-local

# Or build Docker image
make build

Usage

Command Line Options

| Option | Description | Default | |--------|-------------|---------| | --url | Download URL (required) | - | | --target | Target name for metrics | unknown | | --source | Source name for metrics | unknown | | --times | Number of iterations to run | 3 | | --sleep | Seconds to sleep after completion | 300 | | --delay | Seconds to delay between iterations | 0 | | --log-type | Log type: file or console | console | | --split | Number of splits per download | 5 | | --max-connections | Max connections per server | 1 | | --log-file | Output log file path | output/aria2c_logs.txt | | --metrics-file | Output metrics file | output/metrics.statsd | | --statsd-host | StatsD host (optional) | - | | --statsd-port | StatsD port | 8125 | | --statsd-protocol | StatsD protocol: tcp or udp | udp |

Examples

Basic Usage

./bin/speedbench --url https://example.com/test-file.bin

With StatsD Export

./bin/speedbench \
  --url https://example.com/test-file.bin \
  --times 10 \
  --delay 5 \
  --source "datacenter-1" \
  --target "cdn-1" \
  --statsd-host statsd.example.com \
  --statsd-port 8125

Save Metrics to File

./bin/speedbench \
  --url https://example.com/test-file.bin \
  --times 5 \
  --metrics-file /tmp/speedbench-metrics.statsd

Deployment Examples

See the examples directory for deployment configurations:

• Kubernetes: CronJob examples for scheduled network testing
• Docker Compose: Simple docker-compose setup
• systemd: Service file for Linux systems
• Shell Scripts: Simple bash scripts for automation

Metrics

SpeedBench exports the following metrics to StatsD:

Aggregate Metrics

• speedbench.total_iterations: Total number of test iterations
• speedbench.successful_downloads: Number of successful downloads
• speedbench.failed_downloads: Number of failed downloads
• speedbench.success_rate: Success rate percentage
• speedbench.speed.avg/min/max/p50/p95/p99/stddev: Download speed statistics
• speedbench.duration.avg/min/max: Download duration statistics
• speedbench.bytes_downloaded: Total bytes downloaded
• speedbench.connection.dns_lookup.avg_ms/min_ms/max_ms: DNS lookup timing
• speedbench.connection.connect.avg_ms/min_ms/max_ms: TCP connection timing
• speedbench.connection.ssl_handshake.avg_ms/min_ms/max_ms: SSL handshake timing
• speedbench.connection.total.avg_ms/min_ms/max_ms: Total connection timing

Per-Iteration Metrics

• speedbench.iteration.speed: Speed for each iteration
• speedbench.iteration.duration: Duration for each iteration
• speedbench.iteration.bytes: Bytes downloaded per iteration
• speedbench.iteration.connection.*: Connection timings per iteration

Monitoring

StatsD Exporter Configuration

The monitoring/statsd_exporter.yml file contains mappings for converting StatsD metrics to Prometheus format. Use this with statsd_exporter to expose metrics to Prometheus.

Grafana Dashboard

Import the dashboard from monitoring/dashboard.json into your Grafana instance to visualize network performance metrics.

The dashboard includes:

• Success rate gauges
• Speed statistics (avg, min, max, percentiles)
• Connection timing breakdowns
• Download duration trends
• Success vs failure rates

Development

Setup

# Install dependencies
go mod download

# Install pre-commit hooks
pip install pre-commit
pre-commit install

Code Quality

The project uses pre-commit hooks that automatically:

• Format code with go fmt
• Run static analysis with go vet
• Clean up dependencies with go mod tidy
• Check for trailing whitespace and other issues

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with aria2c for download functionality
• Uses StatsD for metrics export
• Compatible with Prometheus via statsd_exporter