Introduzione

Il monitoraggio è fondamentale per garantire l'affidabilità di un servizio web. Quando si sviluppa con FastAPI, una delle sfide più comuni è ottenere metriche e tracing senza introdurre complessità eccessiva. Questa guida è pensata per chi parte da zero: spiegheremo i concetti di base, installeremo le dipendenze necessarie e configureremo un flusso di dati completo verso un backend di osservabilità. Alla fine avrai un'app FastAPI che esporta metriche, trace e log in modo automatico.

1. Concetti di base

1.1 Cos'è FastAPI?

FastAPI è un framework web Python basato su Starlette e Pydantic. Offre performance pari a Node.js o Go grazie al supporto nativo per ASGI e type hints. È ideale per microservizi e API REST.

1.2 Cos'è OpenTelemetry?

OpenTelemetry è una collezione open‑source di API, SDK e strumenti per la telemetria (tracing, metriche, log). Permette di standardizzare il modo in cui le applicazioni esportano dati verso sistemi di osservabilità come Prometheus, Jaeger o Zipkin.

1.3 Perché combinarli?

Unendo FastAPI e OpenTelemetry ottieni:

Visibilità end‑to‑end delle richieste HTTP.
Metriche operative (latency, throughput, error rate).
Tracciamento distribuito per identificare colli di bottiglia.
Log correlati per un debugging più rapido.

2. Preparazione dell'ambiente

2.1 Requisiti di sistema

Python 3.9 o superiore.
Un ambiente virtuale (venv o conda).
Accesso a un backend di osservabilità (es. Prometheus + Grafana, Jaeger, o un servizio SaaS).

2.2 Creazione del progetto

mkdir fastapi-otel-demo
cd fastapi-otel-demo
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn

2.3 Installazione delle dipendenze OpenTelemetry

pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-instrumentation-fastapi
pip install opentelemetry-exporter-prometheus
pip install opentelemetry-exporter-jaeger

3. Integrazione passo passo

3.1 Struttura minima dell’app FastAPI

# app.py
from fastapi import FastAPI

app = FastAPI()

@app.get('/')
async def root():
    return {'message': 'Ciao, mondo!'}

3.2 Instrumentazione automatica

OpenTelemetry fornisce un instrumentation package per FastAPI. Basta importarlo e chiamare instrument_app.

# app.py (continua)
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

FastAPIInstrumentor().instrument_app(app)

3.3 Configurazione del Tracer Provider

# tracing.py
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.jaeger.thrift import JaegerExporter

trace.set_tracer_provider(TracerProvider())
jaeger_exporter = JaegerExporter(
    agent_host_name='localhost',
    agent_port=6831,
)
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(jaeger_exporter)
)

Importa tracing nel tuo app.py prima di avviare l’app.

# app.py (top)
import tracing  # noqa: F401

3.4 Configurazione delle Metriche Prometheus

# metrics.py
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from prometheus_client import start_http_server

metrics.set_meter_provider(MeterProvider())
reader = PrometheusMetricReader()
metrics.get_meter_provider().start_pipeline(
    meter=metrics.get_meter(__name__),
    exporter=reader,
    interval=5,
)
# Avvia il server Prometheus su porta 8000
start_http_server(8000)

Aggiungi l’import in app.py.

import metrics  # noqa: F401

3.5 Avvio dell’applicazione

uvicorn app:app --host 0.0.0.0 --port 8080

A questo punto:

Le richieste HTTP sono tracciate e inviate a Jaeger (visibili su http://localhost:16686).
Le metriche sono esposte su http://localhost:8000/metrics per Prometheus.

4. Verifica e debugging

4.1 Controllo dei trace

Apri Jaeger UI e verifica che le chiamate a / compaiano come spans con attributi come http.method, http.status_code e http.route.

4.2 Controllo delle metriche

Nel browser, visita http://localhost:8000/metrics. Dovresti vedere metriche come http_server_requests_seconds_count e http_server_requests_seconds_sum.

4.3 Risoluzione dei problemi comuni

Exporter non raggiungibile: verifica host e porta dell’agente Jaeger.
Metriche duplicate: assicurati di non chiamare FastAPIInstrumentor().instrument_app(app) più di una volta.
Conflitti di middleware: se usi altri middleware ASGI, posiziona l’instrumentazione prima di aggiungerli.

5. Best practice per la produzione

Campionamento: usa ParentBasedSampler o TraceIdRatioBasedSampler per limitare il volume di trace.
Protezione dei dati: filtra informazioni sensibili prima di esportarle.
Gestione delle chiavi: utilizza variabili d’ambiente per configurare endpoint e credenziali.
Integrazione con Lescopr: Lescopr supporta nativamente OpenTelemetry, consentendo di aggregare metriche, trace e log in un’unica dashboard SLA‑compliant.

6. Checklist rapida

Python ≥ 3.9 installato.
Virtual environment attivo.
Dipendenze FastAPI e OpenTelemetry installate.
Tracer configurato con Jaeger (o altro exporter).
Metric exporter Prometheus avviato.
Applicazione avviata con uvicorn.
Trace verificati in Jaeger UI.
Metriche visibili su /metrics.

Conclusione

Configurare il monitoraggio di FastAPI con OpenTelemetry è più semplice di quanto si pensi: pochi comandi, poche righe di codice e una visibilità immediata. L’integrazione è modulare, quindi puoi aggiungere o rimuovere esportatori a seconda delle esigenze.

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