loadr/README.md

# Loadr

A lightweight REST load testing tool with flexible request patterns, token auth, and detailed performance metrics output.

## Stack
- Core: Pure Golang
- Output: Console + CSV/TXT reporting
- Pattern support: Sequential and probabilistic request patterns
- Transport: Standard Go HTTP client

## Requirements
- Golang 1.23.x or higher

## Installation

```bash
go build
```

## Quick Start

```bash
# Simple pattern: 5 POST requests at 20 req/sec
./loadr -rate=20 -max=100 -url=http://api.example.com -pattern=5p

# Mixed pattern: 1 POST followed by 5 GETs, repeating
./loadr -rate=20 -max=100 -url=http://api.example.com -pattern=1p5g

# Probabilistic pattern: 20% POSTs, 80% GETs
./loadr -rate=20 -max=100 -url=http://api.example.com -pattern=20%p80%g

# With auth and request body
./loadr -rate=20 -max=100 -url=http://api.example.com -pattern=2p3g -json=./data.json -token=YourBearerToken
```

## Request Patterns

The `-pattern` flag supports three types of request patterns:

### Simple Patterns
- `5p` : 5 POST requests
- `3g` : 3 GET requests
- Default is `1g` if no pattern specified

### Sequential Patterns
- `1p5g` : 1 POST followed by 5 GETs, repeating
- `2p3g` : 2 POSTs followed by 3 GETs
- `3g2p` : 3 GETs followed by 2 POSTs

### Probabilistic Patterns
- `20%p80%g` : Random selection with 20% POST and 80% GET probability
- Percentages must sum to 100

## Command Line Flags

```bash
-rate     Number of requests per second (default: 10)
-max      Maximum number of requests to send (default: 50)
-url      Target URL (default: "https://example.com")
-pattern  Request pattern (e.g., "5p", "1p5g", "20%p80%g")
-json     Path to JSON file for request body
-token    Bearer token for authorization
-v        Print version information
```

## Performance Metrics

Loadr generates two types of reports:

### Summary Report (.reports/summary_[timestamp].txt)
- Total requests sent/received
- Average, maximum, and minimum latency
- Requests/sec (target and actual)
- Latency percentiles (p50, p95, p99)
- Pattern information

### Detailed CSV (.reports/detailed_metrics_[timestamp].csv)
- Per-request timestamps
- Individual request latencies
- Status codes
- Request types

## Technical Details

### Rate Limiting
Loadr uses a time-based approach to approximate the target requests per second:

1. Calculates ideal interval between requests: `interval = 1second / requestsPerSecond`
2. Tracks next scheduled request time
3. Uses sleep to maintain timing between requests
4. Launches requests asynchronously to maintain timing accuracy

### Request Execution
- Uses a global HTTP client for connection reuse
- Requests are executed concurrently using goroutines
- Metrics are updated synchronously using mutex protection

### Metrics Collection
- Real-time tracking of request latencies
- Thread-safe counters for requests and responses
- Calculates percentiles from stored request durations
- Support for detailed CSV export for external analysis

Note: The actual request rate may vary slightly from the target rate due to system load and network conditions. The detailed CSV output can be used to analyze the actual timing distribution.