# Performance Monitoring Quick Start

Get started with performance monitoring and profiling in 5 minutes.

## Quick Start Options

### Option 1: Basic Benchmarking
```bash
# Run benchmarks
make benchmark

# View results in Grafana
open http://localhost:3001
```

### Option 2: CPU Profiling
```bash
# Generate CPU profile
make profile-load-norate

# View interactive profile
go tool pprof -http=:8080 cpu_load.out
```

### Option 3: Full Monitoring Stack
```bash
# Start monitoring services
make monitoring-performance

# Run benchmarks with metrics collection
make benchmark

# View in Grafana dashboard
open http://localhost:3001
```

## Prerequisites

- Docker and Docker Compose
- Go 1.21 or later
- Redis (for load tests)
- GitHub repository (for CI/CD integration)

## 1. Setup & Installation

### Start Monitoring Stack (Optional)

For full metrics visualization:

```bash
make monitoring-performance
```

This starts:
- **Grafana**: http://localhost:3001 (admin/admin)
- **Pushgateway**: http://localhost:9091
- **Loki**: http://localhost:3100

### Start Redis (Required for Load Tests)

```bash
docker run -d -p 6379:6379 redis:alpine
```

## 2. Performance Testing

### Benchmarks

```bash
# Run benchmarks locally
make benchmark

# Or run with detailed output
go test -bench=. -benchmem ./tests/benchmarks/...
```

### Load Testing

```bash
# Run load test suite
make load-test
```

## 3. CPU Profiling

### HTTP Load Test Profiling

```bash
# CPU profile MediumLoad HTTP test (with rate limiting)
make profile-load

# CPU profile MediumLoad HTTP test (no rate limiting - recommended)
make profile-load-norate
```

**Analyze Results:**
```bash
# View interactive profile (web UI)
go tool pprof -http=:8081 cpu_load.out

# View interactive profile (terminal)
go tool pprof cpu_load.out

# Generate flame graph
go tool pprof -raw cpu_load.out | go-flamegraph.pl > cpu_flame.svg

# View top functions
go tool pprof -top cpu_load.out
```

Web UI: http://localhost:8080

### WebSocket Queue Profiling

```bash
# CPU profile WebSocket → Redis queue → worker path
make profile-ws-queue
```

**Analyze Results:**
```bash
# View interactive profile (web UI)
go tool pprof -http=:8082 cpu_ws.out

# View interactive profile (terminal)
go tool pprof cpu_ws.out
```

### Profiling Tips

- Use `profile-load-norate` for cleaner CPU profiles (no rate limiting delays)
- Profiles run for 60 seconds by default
- Requires Redis running on localhost:6379
- Results show throughput, latency, and error rate metrics

## 4. Results & Visualization

### Grafana Dashboard

Open: http://localhost:3001 (admin/admin)

Navigate to the **Performance Dashboard** to see:
- Real-time benchmark results
- Historical trends
- Performance comparisons

### Key Metrics

- `benchmark_time_per_op` - Execution time
- `benchmark_memory_per_op` - Memory usage
- `benchmark_allocs_per_op` - Allocation count

## 5. CI/CD Integration

### Setup GitHub Integration

Add GitHub secret:
```
PROMETHEUS_PUSHGATEWAY_URL=http://your-pushgateway:9091
```

Now benchmarks run automatically on:
- Every push to main/develop
- Pull requests
- Daily schedule

### Verify Integration

1. Push code to trigger workflow
2. Check Pushgateway: http://localhost:9091/metrics
3. View metrics in Grafana

## 6. Troubleshooting

### Monitoring Stack Issues

**No metrics in Grafana?**
```bash
# Check services
docker ps --filter "name=monitoring"

# Check Pushgateway
curl http://localhost:9091/metrics
```

**Workflow failing?**
- Verify GitHub secret configuration
- Check workflow logs in GitHub Actions

### Profiling Issues

**Flag error like "flag provided but not defined: -test.paniconexit0"**
```bash
# This should be fixed now, but if it persists:
go test ./tests/load -run TestLoadProfile_Medium -count=1 -cpuprofile cpu_load.out -v -args -profile-norate
```

**Redis not available?**
```bash
# Start Redis for profiling tests
docker run -d -p 6379:6379 redis:alpine

# Check profile file generated
ls -la cpu_load.out
```

**Port conflicts?**
```bash
# Check if ports are in use
lsof -i :3001  # Grafana
lsof -i :8080  # pprof web UI
lsof -i :6379  # Redis
```

## 7. Advanced Usage

### Performance Regression Detection
```bash
# Create baseline
make detect-regressions

# Analyze current performance
go test -bench=. -benchmem ./tests/benchmarks/... | tee current.json
```

### Custom Benchmarks
```bash
# Run specific benchmark
go test -bench=BenchmarkName -benchmem ./tests/benchmarks/...

# Run with race detection
go test -race -bench=. ./tests/benchmarks/...
```

## 8. Further Reading

- [Full Documentation](performance-monitoring.md)
- [Dashboard Customization](performance-monitoring.md#grafana-dashboard)
- [Alert Configuration](performance-monitoring.md#alerting)
- [Architecture Guide](architecture.md)
- [Testing Guide](testing.md)

---

*Ready in 5 minutes!*