Logging and Observability
Auf dieser Seite
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_idhinzu, 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)