Loggning och observerbarhet
På denna sida
Loggning och observerbarhet
I produktion måste du veta exakt vad som händer med dina API-anrop: latens, förbrukade tokens, fel och kostnader. Strukturerad loggning och observerbarhet ger dig den insikten. Skillnaden blir tydlig så fort en användare rapporterar: “Assistenten har varit långsam sedan i morse.” Utan instrumentering får du gissa. Med den kan du på trettio sekunder se att p95-latensen fördubblades efter en promptändring som tredubblade kontextstorleken.
Grundläggande strukturerad loggning
Gör det till en vana att mäta runt anropet, inte inuti det. Läs klockan innan, läs den igen efteråt, och skriv ut en enda rad som beskriver hela händelsen. JSON är inte bara för show: det låter din aggregator filtrera på status, spåra duration_ms över tid eller slå upp ett specifikt response_id – något fritt text aldrig kan göra. except-blocket producerar exakt samma struktur, inklusive undantagstyp och meddelande, och kastar sedan vidare felet. Att logga är inte detsamma som att hantera fel.
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-anrop med fullständig strukturerad loggning."""
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!")
Notera att vi loggar prompt_length, inte själva prompten. Det är ett designval, inte ett förbiseende: längden räcker för att korrelera med latens utan att exportera användardata till ditt loggningssystem.
Loggningsmellanprogram (Middleware)
Att upprepa detta block i varje funktion som anropar API:t garanterar att du kommer glömma det någonstans. Bättre att slå in klienten en gång för alla. Dataklassen APIMetrics definierar kontraktet för vad vi mäter, och ObservableClient fyller i den posten och arkiverar den, oavsett om anropet lyckas eller misslyckas. Metoden rapport omvandlar sedan historiken till direkt användbara måttvärden: framgångsfrekvens, genomsnittlig latens och p95-latens.
Det sista talet är viktigast. Ett genomsnitt på 450 ms kan dölja den ena användaren av tjugo som väntar i tre sekunder; p95 avslöjar det. Genom att sortera varaktigheterna och ta värdet vid den 95:e percentilen beskriver du den verkliga upplevelsen för dina sämst betjänade aktiva användare.
from dataclasses import dataclass, field
from typing import Optional
import time
import json
@dataclass
class APIMetrics:
"""Måttvärden insamlade för varje anrop."""
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-klient med inbyggd observerbarhet."""
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:
"""Generera en rapport över insamlade måttvärden."""
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)],
}
# Användning
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))
# Resultat:
# {
# "total_appels": 3,
# "erreurs": 0,
# "taux_succes": "100.0%",
# "total_tokens": 95,
# "latence_moyenne_ms": 450,
# "latence_p95_ms": 520
# }
Spårning av anrop med kontext
I en distribuerad arkitektur existerar aldrig ett API-anrop i isolation: det utlöses av en HTTP-förfrågan, som i sin tur härrör från en användaråtgärd, och följs ibland av två ytterligare anrop. trace_id är den tråd som binder samman dessa händelser. Genom att propagera den från ditt webblager – här user-123-req-456 – kan du återskapa en hel session i dina loggar utifrån ett enda kundklagomål. Två rader skrivs ut, en vid start och en vid slutförande, vilket också hjälper till att upptäcka anrop som aldrig returnerade.
import uuid
class TracingClient:
"""Klient med spårning för att korrelera förfrågningar."""
def __init__(self):
self.client = OpenAI()
def create_with_trace(self, prompt: str, trace_id: str = None,
**kwargs) -> tuple:
"""Anrop med trace_id för korrelation."""
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
# Användning med trace_id för korrelation i loggar
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]}...")
Var försiktig med prompt_preview: de första hundra tecknen hamnar rakt in i dina loggar som de är. Acceptabelt i utveckling, men ta bort det så snart riktig data börjar flöda.
Export till ett övervakningssystem
En historik i minnet försvinner när processen startas om. För att övervaka en tjänst över tid måste du exponera måttvärden för ett externt verktyg. Det universella mönstret förlitar sig på två familjer: räknare, som bara ökar och omvandlas till frekvenser, och histogram, som behåller en fördelning för att extrahera percentiler. Den här klassen är avsiktligt neutral – du behöver bara koppla get_metrics till en slutpunkt som Prometheus kan skrapa, eller pusha ordlistan till Datadog.
# Mönster för export till Prometheus, Datadog, etc.
class MetricsExporter:
"""Måttvärdesexportör kompatibel med övervakningssystem."""
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()
# Anropa exporter.record_success() eller exporter.record_error()
# efter varje API-anrop
Viktiga punkter
- Logga varje anrop med: modell, tokens, latens, status, response_id
- Använd strukturerad JSON för loggar som dina verktyg kan tolka
- Samla in nyckeltal: framgångsfrekvens, p95-latens, tokenförbrukning
- Lägg till ett
trace_idför att korrelera förfrågningar i distribuerade system - Exportera måttvärden till ditt övervakningssystem (Prometheus, Datadog, etc.)
- Logga aldrig promptinnehåll i produktion (känslig data)