monitoring/locust/README.md

# Locust Load Testing - Skill Classification API

Questa directory contiene gli script per il load testing della Skill Classification API utilizzando [Locust](https://locust.io/).

## Prerequisiti

Assicurati di avere Python installato e installa Locust:

```bash
pip install locust
```

## Avvio del Test

### 1. Avvia Locust

Dalla directory `monitoring/locust/`, esegui:

```bash
locust -f locustfile.py
```

### 2. Accedi alla Web UI

Apri il browser e vai a: **http://localhost:8089**

### 3. Configura il Test

Nella Web UI, configura i seguenti parametri:

| Parametro | Descrizione | Valore di Default |
|-----------|-------------|-------------------|
| **Host** | URL dell'API da testare | `https://dacrow13-hopcroft-skill-classification.hf.space` |
| **Number of users** | Numero totale di utenti simulati | 5-10 (HF Spaces) / 10-100 (locale) |
| **Spawn rate** | Utenti da creare al secondo | 1-2 |

### 4. Avvia il Test

Clicca su **"Start swarming"** per avviare il test di carico.

## Ambienti di Test

Lo script è preconfigurato per testare l'API deployata su **HuggingFace Spaces**:

| Ambiente | URL | Note |
|----------|-----|------|
| **HuggingFace Spaces** (default) | `https://dacrow13-hopcroft-skill-classification.hf.space` | Produzione |
| Docker locale | `http://localhost:8080` | Sviluppo con Docker |
| Uvicorn locale | `http://localhost:8000` | Sviluppo senza Docker |

Per testare un ambiente diverso, usa il flag `--host`:

```bash
locust -f locustfile.py --host http://localhost:8080
```

## Task Implementati

Lo script simula il comportamento di utenti reali con i seguenti task:

| Task | Endpoint | Metodo | Peso | Descrizione |
|------|----------|--------|------|-------------|
| **Predizione Singola** | `/predict` | POST | 3 | Classifica un singolo issue text. Task principale, eseguito più frequentemente. |
| **Predizione Batch** | `/predict/batch` | POST | 1 | Classifica multipli issue text in una singola richiesta. |
| **Monitoraggio e Storia** | `/predictions`, `/health` | GET | 1 | Visualizza la cronologia delle predizioni e verifica lo stato del sistema. |

### Distribuzione dei Pesi

Con i pesi configurati (3:1:1), la distribuzione approssimativa delle richieste è:
- **60%** - Predizione Singola
- **20%** - Predizione Batch  
- **20%** - Monitoraggio e Storia

### Tempo di Attesa

Ogni utente attende tra **1 e 5 secondi** tra un task e l'altro per simulare un comportamento realistico.

## Metriche Monitorate

Durante il test, Locust fornisce le seguenti metriche in tempo reale:

- **RPS (Requests Per Second)**: Numero di richieste al secondo
- **Response Time**: Tempo medio/mediano/percentili di risposta
- **Failure Rate**: Percentuale di richieste fallite
- **Active Users**: Numero di utenti attualmente attivi

## Opzioni Avanzate

### Esecuzione Headless (senza UI)

```bash
# Test su HuggingFace Spaces (default)
locust -f locustfile.py --headless -u 5 -r 1 -t 2m

# Test su Docker locale
locust -f locustfile.py --headless -u 50 -r 5 -t 5m --host http://localhost:8080
```

| Opzione | Descrizione |
|---------|-------------|
| `--headless` | Esegui senza Web UI |
| `-u 5` | 5 utenti simulati |
| `-r 1` | 1 utente creato al secondo |
| `-t 2m` | Durata del test: 2 minuti |
| `--host` | URL dell'API (override) |

### Esportazione Risultati

```bash
locust -f locustfile.py --headless -u 5 -r 1 -t 2m --csv=results
```

Questo creerà file CSV con i risultati del test.

## Struttura File

```
monitoring/locust/
├── locustfile.py   # Script principale di load testing
└── README.md       # Questa documentazione
```

## Note Importanti

- **HuggingFace Spaces**: Usa un numero ridotto di utenti (5-10) per non sovraccaricare il servizio gratuito
- **Latenza**: I test su HF Spaces avranno latenze maggiori rispetto ai test locali
- **Cold Start**: Il primo request potrebbe essere lento se lo Space è in sleep mode