Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Logging en observeerbaarheid

Les 15 van 22 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Logging en observeerbaarheid
  2. Basis van gestructureerde logging
  3. Logging-middleware
  4. Aanroepen traceren met context
  5. Exporteren naar een monitoringsysteem
  6. Belangrijkste punten

Logging en observeerbaarheid

In productieomgevingen moet u precies weten wat er gebeurt met uw API-aanroepen: latentie, verbruikte tokens, fouten en kosten. Gestructureerde logging en observeerbaarheid bieden u dat inzicht. Het verschil wordt duidelijk zodra een gebruiker meldt: “De assistent is sinds vanochtend traag.” Zonder instrumentatie blijft u gissen. Met instrumentatie ziet u binnen dertig seconden dat de p95-latentie is verdubbeld na een wijziging in de prompt die de contextgrootte heeft verdrievoudigd.

Basis van gestructureerde logging

Maak er een gewoonte van om metingen rondom de aanroep te doen, niet erin. Lees de klok vooraf, lees hem opnieuw na afloop, en genereer één regel die het volledige evenement beschrijft. JSON is niet alleen voor de show: het stelt uw aggregator in staat om te filteren op status, duration_ms in de tijd te volgen, of een specifieke response_id op te zoeken—iets wat vrije tekst nooit kan. Het except-blok produceert exact dezelfde structuur, inclusief het type uitzondering en het bericht, en werpt de fout vervolgens opnieuw. Logging is geen foutafhandeling.

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:
    """API call with full structured logging."""
    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!")

Merk op dat we prompt_length loggen, niet de prompt zelf. Dat is een bewuste ontwerppeiling, geen vergetelheid: de lengte volstaat om correlatie met latentie mogelijk te maken, zonder gebruikersgegevens naar uw logsysteem te exporteren.

Logging-middleware

Het herhalen van dit blok in elke functie die de API aanroept, garandeert dat u het ergens zult vergeten. Het is beter om de client eenmalig te wrappen. De APIMetrics-dataclass definieert het contract voor wat we meten, en ObservableClient vult dat record in en archiveert het, ongeacht of de aanroep slaagt of mislukt. De rapport-methode zet de geschiedenis vervolgens om in direct bruikbare statistieken: succespercentage, gemiddelde latentie en p95-latentie.

Dat laatste getal is het belangrijkst. Een gemiddelde van 450 ms kan de één op de twintig gebruikers verbergen die drie seconden wacht; p95 laat dit zien. Door de duur te sorteren en de waarde op het 95e percentiel te nemen, beschrijft u de daadwerkelijke ervaring van uw slechtst bediende actieve gebruikers.

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

@dataclass
class APIMetrics:
    """Metrics collected for each call."""
    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:
    """OpenAI client with built-in observability."""

    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:
        """Generate a report of collected metrics."""
        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)],
        }

# Usage
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))
# Result:
# {
#   "total_appels": 3,
#   "erreurs": 0,
#   "taux_succes": "100.0%",
#   "total_tokens": 95,
#   "latence_moyenne_ms": 450,
#   "latence_p95_ms": 520
# }

Aanroepen traceren met context

In een gedistribueerde architectuur bestaat een API-aanroep nooit op zichzelf: deze wordt geactiveerd door een HTTP-verzoek, dat weer voortkomt uit een gebruikersactie, en soms gevolgd wordt door nog twee aanroepen. De trace_id is de rode draad die deze gebeurtenissen met elkaar verbindt. Door deze door te geven vanuit uw weblaag—hier user-123-req-456—kunt u een volledige sessie reconstrueren in uw logs op basis van een enkele klacht van een klant. Er worden twee regels gegenereerd, één bij de start en één bij voltooiing, wat ook helpt om aanroepen op te sporen die nooit een antwoord terugstuurden.

import uuid

class TracingClient:
    """Client with tracing to correlate requests."""

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

    def create_with_trace(self, prompt: str, trace_id: str = None,
                          **kwargs) -> tuple:
        """Call with trace_id for correlation."""
        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

# Usage with trace_id to correlate in logs
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]}...")

Pas op met prompt_preview: die eerste honderd tekens gaan letterlijk zo uw logs in. Acceptabel tijdens ontwikkeling, maar verwijder dit zodra er echte data stroomt.

Exporteren naar een monitoringsysteem

Een geschiedenis in het geheugen verdwijnt wanneer het proces herstart. Om een service in de tijd te monitoren, moet u statistieken beschikbaar stellen aan een externe tool. Het universele patroon vertrouwt op twee families: tellers (counters), die alleen toenemen en worden omgezet in rates, en histogrammen, die een verdeling behouden om percentielen te extraheren. Deze klasse is bewust neutraal gehouden—u hoeft get_metrics alleen maar aan een endpoint te koppelen zodat Prometheus deze kan ophalen, of de dictionary naar Datadog te pushen.

# Pattern for exporting to Prometheus, Datadog, etc.
class MetricsExporter:
    """Metrics exporter compatible with monitoring systems."""

    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()
# Call exporter.record_success() or exporter.record_error()
# after each API call

Belangrijkste punten

  • Log elke aanroep met: model, tokens, latentie, status, response_id
  • Gebruik gestructureerde JSON voor logs die uw tools kunnen parseren
  • Verzamel kernstatistieken: succespercentage, p95-latentie, tokenverbruik
  • Voeg een trace_id toe om verzoeken in gedistribueerde systemen te correleren
  • Exporteer statistieken naar uw monitoringsysteem (Prometheus, Datadog, enz.)
  • Log nooit de inhoud van prompts in productie (gevoelige gegevens)