Journalisation et observabilité
Šiame puslapyje
Journalisation et observabilité
En production, tu dois savoir exactement ce qui se passe avec tes appels API : latence, jetons consommés, erreurs et coûts. La journalisation structurée et l’observabilité t’offrent cette visibilité. La différence devient évidente dès qu’un utilisateur signale : « L’assistant est lent depuis ce matin. » Sans instrumentation, tu en es réduit à deviner. Avec elle, tu peux voir en trente secondes que la latence p95 a doublé après une modification du prompt qui a triplé la taille du contexte.
Journalisation structurée de base
Prends l’habitude de mesurer autour de l’appel, pas à l’intérieur. Enregistre l’heure avant, relis-la après, et émets une seule ligne décrivant l’événement entier. JSON n’est pas là pour faire joli : il permet à ton agrégateur de filtrer par status, de suivre duration_ms dans le temps, ou de rechercher un response_id spécifique, ce que du texte libre ne pourra jamais faire. Le bloc except produit exactement la même structure, incluant le type et le message de l’exception, puis relance l’erreur. Journaliser n’est pas gérer.
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:
"""Appel API avec journalisation structurée complète."""
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!")
Remarque que nous journalisons prompt_length, et non le prompt lui-même. C’est un choix de conception, pas un oubli : la longueur suffit pour corréler avec la latence, sans exporter les données utilisateur vers ton système de journalisation.
Middleware de journalisation
Répéter ce bloc dans chaque fonction qui appelle l’API garantit que tu l’oublieras quelque part. Il vaut mieux envelopper le client une fois pour toutes. La dataclass APIMetrics définit le contrat de ce que nous mesurons, et ObservableClient remplit cet enregistrement et l’archive, que l’appel réussisse ou échoue. La méthode rapport transforme ensuite l’historique en métriques directement actionnables : taux de réussite, latence moyenne, latence p95.
Ce dernier nombre est le plus important. Une moyenne de 450 ms peut cacher un utilisateur sur vingt qui attend trois secondes ; p95 le révèle. En triant les durées et en prenant la valeur au 95e percentile, tu décris l’expérience réelle de tes utilisateurs actifs les moins bien servis.
from dataclasses import dataclass, field
from typing import Optional
import time
import json
@dataclass
class APIMetrics:
"""Métriques collectées pour chaque appel."""
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 avec observabilité intégrée."""
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:
"""Génère un rapport des métriques collectées."""
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)],
}
# Utilisation
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))
# Résultat :
# {
# "total_appels": 3,
# "erreurs": 0,
# "taux_succes": "100.0%",
# "total_tokens": 95,
# "latence_moyenne_ms": 450,
# "latence_p95_ms": 520
# }
Traçage des appels avec contexte
Dans une architecture distribuée, un appel API n’existe jamais isolément : il est déclenché par une requête HTTP, elle-même issue d’une action utilisateur, et parfois suivi de deux autres appels. Le trace_id est le fil qui relie ces événements. En le propageant depuis ta couche web — ici user-123-req-456 — tu peux reconstruire une session entière dans tes journaux à partir d’une seule plainte client. Deux lignes sont émises, une au début et une à la fin, ce qui aide aussi à repérer les appels qui ne sont jamais revenus.
import uuid
class TracingClient:
"""Client avec traçage pour corréler les requêtes."""
def __init__(self):
self.client = OpenAI()
def create_with_trace(self, prompt: str, trace_id: str = None,
**kwargs) -> tuple:
"""Appel avec trace_id pour corrélation."""
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
# Utilisation avec trace_id pour corrélation dans les journaux
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]}...")
Fais attention avec prompt_preview : ces cent premiers caractères vont directement dans tes journaux tels quels. Acceptable en développement, supprime-le dès que des données réelles circulent.
Exportation vers un système de surveillance
Un historique en mémoire disparaît lorsque le processus redémarre. Pour surveiller un service dans le temps, tu dois exposer les métriques à un outil externe. Le modèle universel repose sur deux familles : les compteurs, qui ne font qu’augmenter et sont dérivés en taux, et les histogrammes, qui conservent une distribution pour extraire des percentiles. Cette classe est volontairement neutre — il te suffit de connecter get_metrics à un point de terminaison pour que Prometheus puisse le scruter, ou d’envoyer le dictionnaire à Datadog.
# Modèle pour l'exportation vers Prometheus, Datadog, etc.
class MetricsExporter:
"""Exportateur de métriques compatible avec les systèmes de surveillance."""
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()
# Appeler exporter.record_success() ou exporter.record_error()
# après chaque appel API
Svarbiausi punktai
- Journalise chaque appel avec : modèle, jetons, latence, statut, response_id
- Utilise du JSON structuré pour des journaux analysables par tes outils
- Collecte les métriques clés : taux de réussite, latence p95, consommation de jetons
- Ajoute un
trace_idpour corréler les requêtes dans les systèmes distribués - Exporte les métriques vers ton système de surveillance (Prometheus, Datadog, etc.)
- Ne journalise jamais le contenu des prompts en production (données sensibles)