NBA_Go/docs/loadtesting.md

Load Testing & Traffic Simulation Guide

The NBA_Go repository includes an advanced, high-performance load testing engine written in Go (test/loadtest.go). It is designed to stress-test the API across edge caches (Cloudflare), reverse proxies (NGINX), the Go Fiber application server, and PostgreSQL database queries under realistic traffic patterns.

---

Why Enhanced Load Testing?

In production, APIs often employ multi-tier caching (Cloudflare Edge with s-maxage + NGINX in-memory cache). A basic load test querying a fixed URL or a small set of pages will hit the edge cache after the first request, returning sub-15ms responses from CDN memory. While this validates CDN delivery, it completely bypasses the Go origin server, connection pool, and database query engine.

The enhanced load tester solves this by introducing:

1. Dynamic Query Variation (-varyParams, -complexity): Randomizes combinations of seasons, teams, sort columns, sort order, page sizes, playoff filters, player IDs, and heavy database relation joins.
2. Cold-Cache Benchmark Mode (-cacheBust): Injects unique high-resolution nonces to guarantee a 100% cache-miss rate when benchmarking origin and database query execution.
3. Cache Telemetry Split: Analyzes CF-Cache-Status (HIT/MISS), Age, and X-Cache response headers, presenting separate latency profiles for Edge Cache Hits vs. Origin / Database Misses.
4. Latency Percentiles: Measures Min, p50 (Median), p75, p90, p95, p99, Max, and Average across all requests.
5. Distributed Client Simulation (-rotateIPs): Injects rotating X-Real-IP and X-Forwarded-For headers to simulate thousands of distinct clients.
6. Benchmark Token Support (-benchmarkKey): Passes the X-Benchmark-Key header to bypass rate limits on origin servers configured with BENCHMARK_KEY.
7. Multi-Endpoint Traffic Generation (-endpointMix): Distributes traffic across /api/playeradvancedstats, /api/playertotals, /api/games, and /api/playershotchart.

---

CLI Flags Reference

Flag	Type	Default	Description
-url	string	http://localhost:5000/api/playeradvancedstats	Target endpoint or base URL to test
-n	int	100	Total number of HTTP requests to send
-c	int	10	Number of concurrent worker goroutines
-varyParams	bool	false	Randomize query parameters (season, team, sortBy, pageSize, isPlayoff, etc.)
-complexity	string	standard	Query complexity level: standard or high (attaches heavy relation preloads for /api/games)
-cacheBust	bool	false	Append unique query nonce (_cb=...) to force 100% cache misses on edge/proxy layers
-benchmarkKey	string	$BENCHMARK_KEY	Token for X-Benchmark-Key header to bypass origin rate limiting
-rotateIPs	bool	false	Rotate synthetic client IPs (X-Real-IP / X-Forwarded-For)
-retryOnRateLimit	bool	false	Retry HTTP 429 responses with exponential backoff (up to 3 retries)
-endpointMix	string	""	Weighted multi-endpoint mix (e.g., playeradvancedstats:40,playertotals:30,games:30)
-pageMix	string	""	Weighted page mix (e.g., 1-3:60,4-10:30,11-20:10)
-timeout	duration	30s	Per-request HTTP timeout
-key	string	""	API key passed in x-api-key header
-log	string	loadtest.log	Output log file destination
-seed	int64	-1	Random seed (-1 uses current timestamp)

---

Usage Recipes

1. Realistic Traffic with Parameter Variance (Recommended)

Simulates realistic user traffic with diverse filter permutations across seasons, teams, and sorting:

go run ./test/loadtest.go \
  -url 'https://nba.turbo-data.com/api/playeradvancedstats' \
  -n 3000 \
  -c 20 \
  -varyParams \
  -complexity high \
  -rotateIPs \
  -benchmarkKey 'your-benchmark-token' \
  -pageMix '1-3:60,4-10:30,11-20:10' \
  -log ./test/results.log

2. Pure Origin / Database Stress Test (100% Cold Cache)

Forces all requests to miss edge and reverse-proxy caches to benchmark raw database query execution:

go run ./test/loadtest.go \
  -url 'https://nba.turbo-data.com/api/playeradvancedstats' \
  -n 1000 \
  -c 15 \
  -varyParams \
  -cacheBust \
  -benchmarkKey 'your-benchmark-token' \
  -log ./test/results.log

3. Multi-Endpoint Traffic Mix

Exercises multiple domains across the application simultaneously according to traffic weights:

go run ./test/loadtest.go \
  -url 'https://nba.turbo-data.com' \
  -endpointMix 'playeradvancedstats:40,playertotals:30,games:30' \
  -varyParams \
  -n 2000 \
  -c 20 \
  -benchmarkKey 'your-benchmark-token' \
  -log ./test/results.log

4. Legacy Execution (Fixed URL with Page Mix)

Runs the traditional page-mix workload:

go run ./test/loadtest.go \
  -url 'https://nba.turbo-data.com/api/playeradvancedstats?page=1&pageSize=40&sortBy=winShares&ascending=false' \
  -n 500 \
  -c 10 \
  -pageMix '1-3:60,4-10:30,11-20:10' \
  -log ./test/results.log

---

Running Unit Tests

Unit tests validate parameter permutations, cache header parsing, percentiles calculation, and endpoint mixing:

go test -v ./test/...