Errori 5xx in FastAPI: come tracciareli e ridurre il MTTR con contesto full-stack

Errori 5xx in FastAPI: come tracciareli e ridurre il MTTR con contesto full-stack

Introduzione

Gli errori 5xx sono il sintomo più evidente di un problema di affidabilità in un'applicazione FastAPI. Quando un endpoint restituisce un 502 o un 503, il cliente vede solo un messaggio generico, mentre il team di sviluppo deve scavare nei log per capire la radice. In questo articolo mostriamo passo dopo passo come tracciare gli errori 5xx, arricchire i log con informazioni full‑stack e ridurre il MTTR (Mean Time to Recovery) di almeno il 30 %.

Per approfondire, la documentazione di Lescopr descrive la configurazione passo dopo passo.

1. Pianificazione del progetto

1.1 Definizione degli obiettivi

• Obiettivo principale: rilevare ogni risposta 5xx in tempo reale.
• Obiettivo secondario: collegare ogni errore a trace ID, payload, stato del database e metriche di latenza.
• KPI di successo: riduzione del MTTR da 2 ore a < 30 minuti.

1.2 Scelta della stack

1.3 Milestone iniziali

1. Setup ambiente di sviluppo – Docker + Poetry.
2. Implementazione middleware di tracing – Lescopr SDK.
3. Configurazione alert su errori 5xx – Dashboard Lescopr.
4. Test di carico – Locust per generare 5xx.
5. Misurazione MTTR – Confronto pre/post implementazione.

2. Implementazione tecnica

2.1 Preparare l’ambiente

# Creare la cartella del progetto
mkdir fastapi-observability && cd fastapi-observability

# Inizializzare il progetto con Poetry
poetry init --no-interaction
poetry add fastapi uvicorn lescopr-sdk

# Dockerfile di base
cat > Dockerfile <<'EOF'
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN pip install poetry && poetry install --no-dev
CMD ["poetry", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
EOF

2.2 Aggiungere il middleware Lescopr

# main.py
from fastapi import FastAPI, Request
from lescopr import LescoprMiddleware

app = FastAPI()

# Inserire il middleware subito dopo la creazione dell'app
app.add_middleware(
    LescoprMiddleware,
    api_key="YOUR_LESCPOR_API_KEY",
    service_name="fastapi‑order‑service",
    environment="production",
)

@app.get("/orders/{order_id}")
async def get_order(order_id: int, request: Request):
    # Simulazione di un errore 502 sotto carico
    if order_id % 5 == 0:
        raise RuntimeError("Simulated upstream failure")
    return {"order_id": order_id, "status": "processed"}

Il middleware cattura ogni eccezione non gestita, genera un trace ID e invia i dati a Lescopr in tempo reale.

2.3 Arricchire i log con contesto full‑stack

@app.exception_handler(RuntimeError)
async def runtime_error_handler(request: Request, exc: RuntimeError):
    # Recupero del trace ID dal middleware
    trace_id = request.state.lescopr_trace_id
    # Aggiunta di metadati custom
    request.state.lescopr.add_context({
        "order_id": request.path_params.get("order_id"),
        "payload": await request.body(),
        "db_status": "unavailable",
        "trace_id": trace_id,
    })
    # Rilancio per far registrare l'errore
    raise exc

Con questa gestione, ogni errore 5xx comparirà nella dashboard Lescopr con:

• Trace ID
• Payload della request
• Stato del database
• Timestamp e latency

2.4 Configurare gli alert

Accedi alla UI Lescopr → Alerting → New Alert:

1. Condition: response_status >= 500
2. Threshold: > 5 occurrences in 1 minute
3. Channel: Slack, Email, Webhook.

In questo modo il team riceve una notifica immediata non appena il numero di 5xx supera la soglia.

3. Verifica e ottimizzazione

3.1 Test di carico con Locust

poetry add locust
locust -f locustfile.py --headless -u 200 -r 20 --run-time 5m

Il file locustfile.py deve colpire l'endpoint /orders/{order_id} con ID multipli di 5 per forzare gli errori.

3.2 Analisi dei risultati

Come si vede, l'aggiunta del middleware Lescopr ha ridotto sia la frequenza degli errori sia il tempo di recupero.

3.3 Best practice

• Centralizzare i trace ID: propagare l'ID in tutti i microservizi.
• Loggare sempre il payload (escludendo dati sensibili).
• Impostare soglie di alert basate sul traffico reale.
• Revisionare periodicamente le regole di alert per evitare falsi positivi.

4. Prossimi passi

Ora che il progetto è in produzione, puoi:

• Espandere il tracing a database, cache e code.
• Abilitare il tracing distribuito per visualizzare il flusso di una singola richiesta attraverso più servizi.
• Integrare la compliance GDPR usando i filtri di Lescopr per anonimizzare dati personali nei log.

Per approfondire, la documentazione di Lescopr descrive la configurazione passo dopo passo.