Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Logging and Observability

Lektion 15 von 22 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Logging and Observability
  2. Basic Structured Logging
  3. Logging Middleware
  4. Tracing Calls with Context
  5. Exporting to a Monitoring System
  6. Key Takeaways

Logging and Observability

In der Produktion müssen Sie genau wissen, was mit Ihren API-Aufrufen passiert: Latenz, verbrauchte Tokens, Fehler und Kosten. Strukturiertes Logging und Observability bieten Ihnen diese Transparenz. Der Unterschied zeigt sich sofort, wenn ein Nutzer meldet: „Der Assistent ist seit diesem Morgen langsam.” Ohne Instrumentierung sind Sie auf Vermutungen angewiesen. Mit ihr können Sie in dreißig Sekunden erkennen, dass die p95-Latenz sich verdoppelt hat, nachdem eine Prompt-Änderung die Kontextgröße verdreifacht hat.

Basic Structured Logging

Machen Sie es zur Gewohnheit, rund um den Aufruf zu messen, nicht innerhalb. Notieren Sie die Uhrzeit vor dem Aufruf, lesen Sie sie danach erneut aus und emittieren Sie eine einzelne Zeile, die das gesamte Ereignis beschreibt. JSON ist nicht nur zur Schau: Es ermöglicht Ihrem Aggregator, nach status zu filtern, duration_ms im Zeitverlauf zu verfolgen oder eine bestimmte response_id aufzufinden – etwas, das freier Text niemals leisten kann. Der except-Block erzeugt die exakt gleiche Struktur, einschließlich des Fehlertyps und der Fehlermeldung, und wirft den Fehler danach erneut. Logging ist nicht das Behandeln von Fehlern.

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!")

Beachten Sie, dass wir prompt_length protokollieren, nicht den Prompt selbst. Das ist eine Designentscheidung, kein oversight: Die Länge reicht aus, um mit der Latenz korreliert zu werden, ohne Benutzerdaten in Ihr Logging-System zu exportieren.

Logging Middleware

Diesen Block in jeder Funktion zu wiederholen, die die API aufruft, garantiert, dass Sie ihn an einer Stelle vergessen werden. Besser ist es, den Client einmal und für alle zu umschließen. Die APIMetrics-Dataclass definiert den Vertrag für das, was wir messen, und ObservableClient füllt diesen Datensatz und archiviert ihn, unabhängig davon, ob der Aufruf erfolgreich war oder nicht. Die rapport-Methode verwandelt die Historie dann in direkt umsetzbare Metriken – Erfolgsquote, durchschnittliche Latenz, p95-Latenz.

Diese letzte Zahl ist am wichtigsten. Ein Durchschnitt von 450 ms kann die einen von zwanzig Nutzern verbergen, die drei Sekunden warten; p95 enthüllt dies. Indem Sie Längen sortieren und den Wert am 95. Perzentil nehmen, beschreiben Sie die tatsächliche Erfahrung Ihrer am schlechtesten bedienten aktiven Nutzer.

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
# }

Tracing Calls with Context

In einer verteilten Architektur existiert ein API-Aufruf nie isoliert: Er wird durch eine HTTP-Anfrage ausgelöst, die ihrerseits auf eine Benutzeraktion zurückzuführen ist, und wird manchmal von zwei weiteren Aufrufen gefolgt. Die trace_id ist der Faden, der diese Ereignisse zusammenbindet. Indem Sie sie von Ihrer Web-Schicht – hier user-123-req-456 – weitergeben, können Sie in Ihren Protokollen eine gesamte Sitzung aus einer einzigen Kundenbeschwerde rekonstruieren. Zwei Zeilen werden emittiert, eine am Start und eine bei Abschluss, was auch dazu beiträgt, Aufrufe zu identifizieren, die nie zurückgekehrt sind.

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]}...")

Seien Sie vorsichtig mit prompt_preview: Diese ersten hundert Zeichen landen unverändert direkt in Ihren Protokollen. In der Entwicklung akzeptabel, entfernen Sie es so schnell wie möglich, sobald echte Daten fließen.

Exporting to a Monitoring System

Eine Historie im Arbeitsspeicher verschwindet, wenn der Prozess neu gestartet wird. Um einen Dienst über die Zeit zu überwachen, müssen Sie Metriken einem externen Tool zur Verfügung stellen. Das universelle Muster stützt sich auf zwei Familien: Counter, die nur zunehmen und in Raten abgeleitet werden, und Histogramme, die eine Verteilung beibehalten, um Perzentile zu extrahieren. Diese Klasse ist absichtlich neutral – Sie müssen lediglich get_metrics an einen Endpunkt für Prometheus koppeln, um ihn abzugreifen, oder das Wörterbuch an Datadog senden.

# 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

Key Takeaways

  • Protokollieren Sie jeden Aufruf mit: Modell, Tokens, Latenz, Status, response_id
  • Verwenden Sie strukturiertes JSON für Logs, die Ihre Tools parsen können
  • Sammeln Sie Schlüsselmetriken: Erfolgsquote, p95-Latenz, Tokenverbrauch
  • Fügen Sie eine trace_id hinzu, um Aufrufe in verteilten Systemen zu korrelieren
  • Exportieren Sie Metriken in Ihr Überwachungssystem (Prometheus, Datadog usw.)
  • Protokollieren Sie niemals Prompt-Inhalte in der Produktion (sensible Daten)