Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Journalisation et observabilité

Paskaita 15 iš 22 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Journalisation et observabilité
  2. Journalisation structurée de base
  3. Middleware de journalisation
  4. Traçage des appels avec contexte
  5. Exportation vers un système de surveillance
  6. Svarbiausi punktai

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_id pour 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)