Benchmarking Options

This guide covers advanced options for controlling how burl runs benchmarks.

Rate Limiting

Use -q or --qps to limit requests per second:

# Maximum 100 requests per second
burl https://api.example.com -q 100 -c 10 -d 60s

This is useful for:

• Testing at production traffic levels
• Avoiding overwhelming the target server
• Simulating realistic user behavior
• Respecting rate limits

HTTP Version Control

By default, burl uses HTTP/2 when available. You can force a specific version:

Force HTTP/1.1

burl https://api.example.com --http1

Use this when:

• Testing HTTP/1.1 specific behavior
• The server doesn't support HTTP/2
• Comparing protocol performance

Force HTTP/2

burl https://api.example.com --http2

HTTP/3 (Experimental)

burl https://api.example.com --http3

Warmup Requests

The -w or --warmup flag sends requests that aren't counted in statistics:

# 50 warmup requests
burl https://api.example.com -w 50 -d 30s

Why Warmup?

1. Connection Establishment: HTTP connections take time to establish. Warmup ensures connections are ready.
2. JIT Compilation: Many servers use JIT compilation. Initial requests may be slower while code compiles.
3. Cache Warming: First requests may hit cold caches on the server.
4. Realistic Measurements: After warmup, measurements better reflect steady-state performance.

Recommended Warmup

Combining Options

For realistic production testing, combine multiple options:

burl https://api.example.com/users \
  -c 100 \                    # 100 concurrent users
  -d 5m \                     # Run for 5 minutes
  -q 500 \                    # Limit to 500 req/s
  -w 200 \                    # 200 warmup requests
  --http2                     # Force HTTP/2

Understanding Results

After running with these options, pay attention to:

Interpreting Latency Distribution

Latency
  P50:    12.4ms   ← Median - typical response time
  P90:    32.1ms   ← 90th percentile
  P95:    45.2ms   ← 95th percentile
  P99:    89.3ms   ← 99th percentile - tail latency

A large gap between P50 and P99 indicates inconsistent performance:

• Healthy: P99 is 2-3x P50
• Concerning: P99 is 5-10x P50
• Problem: P99 is >10x P50