virag/http-loadgen

By virag

•Updated about 1 year ago

HTTP benchmarking and workload simulation tool

Image

251

Overview Tags

virag/http-loadgen repository overview

⁠http-loadgen

Latest Release License

http-loadgen is a high-throughput, configurable HTTP benchmarking and workload simulation tool.
Use it to load test any read/write API — including permission systems like Ory Keto⁠.

⁠🚀 Quick Start

./scripts/run.sh

This runs the default benchmark defined in config/config.yaml.

⁠📊 Benchmark Matrix

To run multiple configurations and generate a report:

./scripts/run.sh --benchmark

Results are written to:

benchmark_results.csv

⁠🧪 Example: Test Ory Keto

Use this config:

# api/keto.yaml
api:
  write_api: http://localhost:4467
  read_api: http://localhost:4466

requests:
  write:
    method: PUT
    url: "{{ .WriteAPI }}/admin/relation-tuples"
    headers:
      Content-Type: application/json
    body: |
      {
        "namespace": "documents",
        "object": "{{ .object }}",
        "relation": "viewer",
        "subject_id": "user:{{ .subject }}"
      }

  read:
    method: POST
    url: "{{ .ReadAPI }}/relation-tuples/check"
    headers:
      Content-Type: application/json
    body: |
      {
        "namespace": "documents",
        "object": "{{ .object }}",
        "relation": "viewer",
        "subject_id": "user:{{ .subject }}"
      }

And run:

./http-loadgen --workload-config=./config/config.yaml --log-file=run.log

⁠📁 Folder Layout

api/              # API-specific configurations (e.g., Keto)
config/           # Loadgen settings: concurrency, retries, durations
scripts/          # run.sh and benchmark automation
internal/         # Core logic: request engine, metrics, generator
cmd/              # CLI entrypoint (main.go)

⁠🔧 CLI Flags

Flag	Description
`--duration-sec`	Duration to run the test
`--concurrency`	Number of concurrent workers
`--checks-per-second`	Max read requests per second
`--read-ratio`	Read to write ratio (e.g., 100 = 100:1)
`--workload-config`	Path to YAML config file
`--log-file`	Where to write logs
`--verbose`	Enable detailed logging
`--max-retries`	Retry attempts per request
`--retry-delay`	Delay between retries (ms)
`--request-timeout`	Timeout per HTTP request (sec)
`--max-open-conns`	Max HTTP connections
`--max-idle-conns`	Max idle connections
`--serve-metrics`	Keep Prometheus metrics server alive
`--dry-run`	Run logic without making real HTTP calls

⁠📦 Build

make build

⁠🍎 macOS Gatekeeper (Quarantine) Fix

When downloading the macOS binary (http-loadgen_darwin_arm64 or http-loadgen_darwin_amd64), macOS may block it with this error:


"http-loadgen" cannot be opened because the developer cannot be verified.

To fix it:

xattr -d com.apple.quarantine ./http-loadgen_darwin_arm64
chmod +x ./http-loadgen_darwin_arm64
./http-loadgen_darwin_arm64 --help

Alternatively, allow the app manually via:

 System Settings → Privacy & Security → Allow Anyway

⁠🐳 Docker Usage

Build the image locally:

docker build -t http-loadgen:latest .

⁠🚀 Run with built-in config (zero setup)

docker run --rm virag/http-loadgen:latest \
  --workload-config=/app/config/config.yaml \
  --log-file=/app/run.log

✅ This works out of the box because the default config is baked into the image at /app/config/config.yaml.

⁠⚙️ Override config from local machine

docker run --rm \
  -v $(pwd)/config:/app/config \
  virag/http-loadgen:latest \
  --workload-config=/app/config/custom.yaml \
  --log-file=/app/run.log

✅ This mounts your local config/ folder into the container, replacing the default.

⁠🧪 Use dry-run mode to test

docker run --rm virag/http-loadgen:latest \
  --workload-config=/app/config/config.yaml \
  --dry-run

⁠📈 Live Metrics

Run with:

--serve-metrics

Then scrape:

http://localhost:2112/metrics

Prometheus-compatible metrics include:

retry_attempts_total
retry_success_total
permission_check_total
retry_duration_seconds

⁠💡 Why Benchmark APIs Instead of the DB?

This tool mimics real-world client behavior — it:

Hits live HTTP endpoints
Tests retry logic, latency, and concurrency
Measures API performance under real query pressure

Not just the raw DB underneath.

⁠📖 References

Tag summary

Recent tags

Content type

Image

Digest

sha256:ac8657f85…

Size

11.8 MB

Last updated

about 1 year ago

docker pull virag/http-loadgen