Logging e Osservabilità
In questa pagina
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_idper 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)