Logovanie a pozorovateľnosť
Na tejto strane
Logovanie a pozorovateľnosť
V produkčnom prostredí musíš presne vedieť, čo sa deje s tvojimi volaniami API: latencia, spotreba tokenov, chyby a náklady. Štruktúrované logovanie a pozorovateľnosť ti poskytujú túto viditeľnosť. Rozdiel je zrejmý v momente, keď používateľ nahlási: „Asistent je od rána pomalý.“ Bez inštrumentácie len hádaš. S ňou môžeš do tridsiatich sekúnd zistiť, že latencia p95 sa zdvojnásobila po zmene promptu, ktorá strojnásobila veľkosť kontextu.
Základné štruktúrované logovanie
Zvykni si merať čas okolo volania, nie vnútri neho. Odčítaj hodiny pred volaním, znova po ňom a emituj jeden riadok popisujúci celú udalosť. JSON nie je len na okrasu: umožňuje tvojemu agregátoru filtrovať podľa status, sledovať duration_ms v čase alebo vyhľadať konkrétne response_id – čo voľný text nikdy nedokáže. Blok except vytvorí presne rovnakú štruktúru vrátane typu výnimky a správy, a následne výnimku znova vyhodí. Logovanie nie je riešenie chýb.
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!")
Všimni si, že logujeme prompt_length, nie samotný prompt. Je to dizajnové rozhodnutie, nie prehliadnutie: dĺžka stačí na koreláciu s latenciou, bez exportu používateľských dát do tvojho logovacieho systému.
Logovací middleware
Opakovanie tohto bloku v každej funkcii, ktorá volá API, garantuje, že na to niekde zabudneš. Lepšie je zabaliť klienta raz a navždy. Dátová trieda APIMetrics definuje kontrakt toho, čo meriame, a ObservableClient túto records naplní a archivuje, či už volanie uspeje alebo zlyhá. Metóda rapport následne premení históriu na priamo akčné metriky – mieru úspešnosti, priemernú latenciu, latenciu p95.
Posledné číslo je najdôležitejšie. Priemer 450 ms môže skryť jedného z dvadsiatich používateľov, ktorý čaká tri sekundy; p95 to odhalí. Zoradením dĺžok trvania a vybratím hodnoty na 95. percentile popisuješ skutočnú skúsenosť svojich najhoršie obsluhovaných aktívnych používateľov.
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
# }
Sledovanie volaní s kontextom
V distribuovanej architektúre volanie API nikdy neexistuje izolovane: je spustené HTTP požiadavkou, ktorá sama vyplýva z akcie používateľa, a niekedy po nej nasledujú ďalšie dve volania. trace_id je niť, ktorá spája tieto udalosti dokopy. Propagáciou z tvojej webovej vrstvy – tu user-123-req-456 – môžeš z jednej sťažnosti zákazníka rekonštruovať celú reláciu v tvojich logoch. Emitujú sa dva riadky, jeden na začiatku a jeden pri dokončení, čo tiež pomáha odhaliť volania, ktoré sa nikdy nevrátili.
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]}...")
Daj si pozor na prompt_preview: tých prvých sto znakov ide priamo do tvojich logov tak, ako sú. Prijateľné vo vývoji, ale odstráň to hneď, ako potečú reálne dáta.
Export do monitorovacieho systému
História v pamäti zmizne po reštarte procesu. Ak chceš monitorovať službu v čase, musíš exponovať metriky externému nástroju. Univerzálny vzor sa spolieha na dve rodiny: čítače (counters), ktoré len rastú a odvodzujú sa z nich sadzby, a histogramy, ktoré uchovávajú distribúciu na extrakciu percentilov. Táto trieda je zámerne neutrálna – stačí napojiť get_metrics na endpoint pre Prometheus na scrapovanie, alebo poslať slovník do Datadog.
# 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
Kľúčové poznatky
- Loguj každé volanie s: modelom, tokenmi, latenciou, statusom, response_id
- Používaj štruktúrovaný JSON pre logy, ktoré tvoje nástroje dokážu parsovať
- Zbieraj kľúčové metriky: miera úspešnosti, latencia p95, spotreba tokenov
- Pridaj
trace_idna koreláciu požiadaviek v distribuovaných systémoch - Exportuj metriky do svojho monitorovacieho systému (Prometheus, Datadog atď.)
- Nikdy neloguj obsah promptu v produkcii (citlivé dáta)