Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Logging e Osservabilità

Lezione 15 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Logging e Osservabilità
  2. Logging Strutturato di Base
  3. Middleware di Logging
  4. Tracciamento delle Chiamate con Contesto
  5. Esportazione verso un Sistema di Monitoraggio
  6. Punti chiave

Logging e Osservabilità

In produzione, devi sapere esattamente cosa succede alle tue chiamate API: latenza, token consumati, errori e costi. Il logging strutturato e l’osservabilità ti offrono questa visibilità. La differenza diventa chiara nel momento in cui un utente segnala: «L’assistente è lento da stamattina». Senza strumentazione, sei costretto a indovinare. Con essa, puoi vedere in trenta secondi che la latenza p95 è raddoppiata dopo una modifica al prompt che ha triplicato la dimensione del contesto.

Logging Strutturato di Base

Prendi l’abitudine di misurare attorno alla chiamata, non al suo interno. Registra l’orologio prima, leggilo di nuovo dopo ed emetti una singola riga che descriva l’intero evento. JSON non serve solo per estetica: permette al tuo aggregatore di filtrare per status, tracciare duration_ms nel tempo o cercare uno specifico response_id, cosa che il testo libero non potrà mai fare. Il blocco except produce esattamente la stessa struttura, includendo il tipo e il messaggio dell’eccezione, per poi rilanciarla. Fare logging non significa gestire l’errore.

import logging
import json
import time
from openai import OpenAI

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s"
)
logger = logging.getLogger("openai_api")

client = OpenAI()

def appel_avec_logging(prompt: str, model: str = "gpt-5.6-terra") -> str:
    """Chiamata API con logging strutturato completo."""
    start = time.monotonic()
    request_id = None

    try:
        response = client.responses.create(
            model=model,
            input=prompt
        )

        duree = time.monotonic() - start

        logger.info(json.dumps({
            "event": "api_call",
            "status": "success",
            "model": response.model,
            "response_id": response.id,
            "input_tokens": response.usage.input_tokens,
            "output_tokens": response.usage.output_tokens,
            "total_tokens": response.usage.total_tokens,
            "duration_ms": round(duree * 1000),
            "prompt_length": len(prompt),
        }))

        return response.output_text

    except Exception as e:
        duree = time.monotonic() - start

        logger.error(json.dumps({
            "event": "api_call",
            "status": "error",
            "error_type": type(e).__name__,
            "error_message": str(e),
            "model": model,
            "duration_ms": round(duree * 1000),
            "prompt_length": len(prompt),
        }))
        raise

resultat = appel_avec_logging("Hello!")

Nota che registriamo prompt_length, non il prompt stesso. È una scelta progettuale, non una svista: la lunghezza è sufficiente per correlare con la latenza, senza esportare dati utente nel tuo sistema di logging.

Middleware di Logging

Ripetere questo blocco in ogni funzione che chiama l’API garantisce che prima o poi lo dimenticherai da qualche parte. Meglio incapsulare il client una volta per tutte. La dataclass APIMetrics definisce il contratto su ciò che misuriamo, mentre ObservableClient popola quel record e lo archivia, sia che la chiamata abbia successo o fallisca. Il metodo rapport trasforma quindi la cronologia in metriche direttamente azionabili: tasso di successo, latenza media, latenza p95.

Quell’ultimo numero è il più importante. Una media di 450 ms può nascondere quell’utente su venti che aspetta tre secondi; il p95 lo rivela. Ordinando le durate e prendendo il valore al 95° percentile, descrivi l’esperienza reale dei tuoi utenti attivi meno serviti.

from dataclasses import dataclass, field
from typing import Optional
import time
import json

@dataclass
class APIMetrics:
    """Metriche raccolte per ogni chiamata."""
    model: str = ""
    input_tokens: int = 0
    output_tokens: int = 0
    total_tokens: int = 0
    duration_ms: int = 0
    status: str = "unknown"
    error: Optional[str] = None
    response_id: Optional[str] = None

class ObservableClient:
    """Client OpenAI con osservabilità integrata."""

    def __init__(self):
        self.client = OpenAI()
        self.metrics_history: list[APIMetrics] = []

    def create(self, model: str, input: str, **kwargs) -> object:
        start = time.monotonic()
        metrics = APIMetrics(model=model)

        try:
            response = self.client.responses.create(
                model=model,
                input=input,
                **kwargs
            )

            metrics.status = "success"
            metrics.response_id = response.id
            metrics.input_tokens = response.usage.input_tokens
            metrics.output_tokens = response.usage.output_tokens
            metrics.total_tokens = response.usage.total_tokens
            metrics.duration_ms = round((time.monotonic() - start) * 1000)

            self.metrics_history.append(metrics)
            return response

        except Exception as e:
            metrics.status = "error"
            metrics.error = str(e)
            metrics.duration_ms = round((time.monotonic() - start) * 1000)
            self.metrics_history.append(metrics)
            raise

    def rapport(self) -> dict:
        """Genera un report delle metriche raccolte."""
        if not self.metrics_history:
            return {"message": "No calls recorded"}

        total_calls = len(self.metrics_history)
        erreurs = sum(1 for m in self.metrics_history if m.status == "error")
        total_tokens = sum(m.total_tokens for m in self.metrics_history)
        durees = [m.duration_ms for m in self.metrics_history]

        return {
            "total_appels": total_calls,
            "erreurs": erreurs,
            "taux_succes": f"{((total_calls - erreurs) / total_calls) * 100:.1f}%",
            "total_tokens": total_tokens,
            "latence_moyenne_ms": round(sum(durees) / len(durees)),
            "latence_p95_ms": sorted(durees)[int(len(durees) * 0.95)],
        }

# Utilizzo
obs_client = ObservableClient()

obs_client.create("gpt-5.6-terra", "Hello!")
obs_client.create("gpt-5.6-terra", "How are you?")
obs_client.create("gpt-5.6-terra", "Thanks!")

print(json.dumps(obs_client.rapport(), indent=2))
# Risultato:
# {
#   "total_appels": 3,
#   "erreurs": 0,
#   "taux_succes": "100.0%",
#   "total_tokens": 95,
#   "latence_moyenne_ms": 450,
#   "latence_p95_ms": 520
# }

Tracciamento delle Chiamate con Contesto

In un’architettura distribuita, una chiamata API non esiste mai in isolamento: è attivata da una richiesta HTTP, a sua volta derivante da un’azione utente, e talvolta seguita da altre due chiamate. Il trace_id è il filo che lega questi eventi insieme. Propagandolo dal tuo livello web – qui user-123-req-456 – puoi ricostruire un’intera sessione nei tuoi log partendo da un singolo reclamo del cliente. Vengono emesse due righe, una all’inizio e una al completamento, il che aiuta anche a individuare le chiamate che non hanno mai restituito una risposta.

import uuid

class TracingClient:
    """Client con tracciamento per correlare le richieste."""

    def __init__(self):
        self.client = OpenAI()

    def create_with_trace(self, prompt: str, trace_id: str = None,
                          **kwargs) -> tuple:
        """Chiamata con trace_id per correlazione."""
        if trace_id is None:
            trace_id = str(uuid.uuid4())[:8]

        start = time.monotonic()

        logger.info(json.dumps({
            "event": "api_request_start",
            "trace_id": trace_id,
            "prompt_preview": prompt[:100],
        }))

        response = self.client.responses.create(
            model=kwargs.get("model", "gpt-5.6-terra"),
            input=prompt,
            **{k: v for k, v in kwargs.items() if k != "model"}
        )

        duration = time.monotonic() - start

        logger.info(json.dumps({
            "event": "api_request_complete",
            "trace_id": trace_id,
            "response_id": response.id,
            "tokens": response.usage.total_tokens,
            "duration_ms": round(duration * 1000),
        }))

        return response, trace_id

# Utilizzo con trace_id per correlare nei log
tracing = TracingClient()
response, trace = tracing.create_with_trace(
    "Summarize logging best practices.",
    trace_id="user-123-req-456"
)
print(f"Trace: {trace} | Response: {response.output_text[:80]}...")

Fai attenzione a prompt_preview: quei primi cento caratteri finiscono dritti nei tuoi log così come sono. Accettabile in sviluppo, rimuovilo non appena iniziano a fluire dati reali.

Esportazione verso un Sistema di Monitoraggio

Una cronologia in memoria scompare quando il processo si riavvia. Per monitorare un servizio nel tempo, devi esporre le metriche a uno strumento esterno. Il pattern universale si basa su due famiglie: i contatori, che aumentano solo e vengono derivati in tassi, e gli istogrammi, che mantengono una distribuzione per estrarre i percentili. Questa classe è intenzionalmente neutrale: devi solo collegare get_metrics a un endpoint affinché Prometheus possa effettuare lo scraping, oppure inviare il dizionario a Datadog.

# Pattern per l'esportazione verso Prometheus, Datadog, ecc.
class MetricsExporter:
    """Esportatore di metriche compatibile con i sistemi di monitoraggio."""

    def __init__(self):
        self.counters = {
            "api_calls_total": 0,
            "api_errors_total": 0,
            "tokens_consumed_total": 0,
        }
        self.histograms = {
            "api_latency_ms": [],
        }

    def record_success(self, tokens: int, latency_ms: int):
        self.counters["api_calls_total"] += 1
        self.counters["tokens_consumed_total"] += tokens
        self.histograms["api_latency_ms"].append(latency_ms)

    def record_error(self):
        self.counters["api_calls_total"] += 1
        self.counters["api_errors_total"] += 1

    def get_metrics(self) -> dict:
        latencies = self.histograms["api_latency_ms"]
        return {
            **self.counters,
            "latency_avg_ms": round(sum(latencies) / max(len(latencies), 1)),
            "error_rate": self.counters["api_errors_total"] /
                         max(self.counters["api_calls_total"], 1),
        }

exporter = MetricsExporter()
# Chiama exporter.record_success() o exporter.record_error()
# dopo ogni chiamata API

Punti chiave

  • Registra ogni chiamata con: modello, token, latenza, stato, response_id
  • Usa JSON strutturato per log che i tuoi strumenti possano analizzare
  • Raccogli le metriche chiave: tasso di successo, latenza p95, consumo di token
  • Aggiungi un trace_id per correlare le richieste nei sistemi distribuiti
  • Esporta le metriche nel tuo sistema di monitoraggio (Prometheus, Datadog, ecc.)
  • Non registrare mai il contenuto del prompt in produzione (dati sensibili)