Dnevniški zapisi in opazljivost
Na tej strani
Dnevniški zapisi in opazljivost
V produkcijskem okolju moraš točno vedeti, kaj se dogaja s tvojimi klici API-ja: zakasnitev, porabljeni žetoni, napake in stroški. Strukturirani dnevniški zapisi in opazljivost ti zagotavljata ta vpogled. Razlika postane očitna v trenutku, ko uporabnik sporoči: „Pomočnik je od danes zjutraj počasen.” Brez instrumentacije ugibaš. Z njo lahko v tridesetih sekundah vidiš, da se je zakasnitev p95 podvojila po spremembi poziva, ki je potrojila velikost konteksta.
Osnovno strukturirano beleženje
Naj ti pride v navado meriti čas okoli klica, ne znotraj njega. Zabeleži čas pred klicem, ponovno ga odčitaj po njem in izpiši eno samo vrstico, ki opisuje celoten dogodek. JSON ni zgolj za lepši videz: omogoča tvojemu agregatorju filtriranje po status, sledenje duration_ms skozi čas ali iskanje določenega response_id – česar prosto oblikovano besedilo nikoli ne zmore. Blok except ustvari popolnoma enako strukturo, vključno z vrsto napake in sporočilom, nato pa ponovno sproži izjemo. Beleženje ni obravnava napak.
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!")
Upoštevaj, da beležimo prompt_length, ne samega poziva. To je načrtna odločitev, ne spregled: dolžina zadostuje za povezavo z zakasnitvijo, ne da bi izvažal uporabniške podatke v svoj sistem dnevniških zapisov.
Vmesna programska oprema za beleženje
Ponavljanje tega bloka v vsaki funkciji, ki kliče API, zagotavlja, da ga boš nekje pozabil. Bolje je, da oviješ odjemalca enkrat za vselej. Podatkovni razred APIMetrics definira pogodbo o tem, kaj merimo, ObservableClient pa zapolni ta zapis in ga arhivira, ne glede na to, ali klic uspe ali odpove. Metoda rapport nato zgodovino pretvori v neposredno uporabne metrike – stopnjo uspešnosti, povprečno zakasnitev, zakasnitev p95.
Zadnja številka je najpomembnejša. Povprečje 450 ms lahko skrije enega od dvajsetih uporabnikov, ki čaka tri sekunde; p95 to razkrije. Z razvrščanjem trajanj in vzemanjem vrednosti na 95. percentilu opišeš dejansko izkušnjo svojih najbolj prikrajšanih aktivnih uporabnikov.
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
# }
Sledenje klicem s kontekstom
V porazdeljeni arhitekturi klic API-ja nikoli ne obstaja izolirano: sproži ga HTTP zahteva, ki izvira iz uporabnikovega dejanja, včasih pa mu sledita še dva dodatna klica. trace_id je nit, ki povezuje te dogodke. S posredovanjem iz tvoje spletne plasti – tukaj user-123-req-456 – lahko iz ene same pritožbe stranke v dnevniških zapisih rekonstruiraš celotno sejo. Izpišeta se dve vrstici, ena na začetku in ena ob zaključku, kar pomaga tudi pri odkrivanju klicev, ki se nikoli niso vrnili.
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]}...")
Bodi previden pri prompt_preview: teh prvih sto znakov gre neposredno v tvoje dnevniške zapise, takšnih, kot so. Sprejemljivo v razvojnem okolju, odstrani pa jih takoj, ko stečejo realni podatki.
Izvoz v sistem za nadzor
Zgodovina v pomnilniku izgine, ko se proces ponovno zažene. Za nadzor storitve skozi čas moraš metrike izpostaviti zunanjemu orodju. Univerzalni vzorec temelji na dveh družinah: števcih, ki se le povečujejo in iz katerih izpeljemo stopnje, ter histogramih, ki ohranjajo porazdelitev za ekstrakcijo percentil. Ta razred je namerno nevtralen – le povezati moraš get_metrics s končno točko, ki jo bo pregledal Prometheus, ali pa slovar potisniti v 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
Ključne ugotovitve
- Zabeleži vsak klic z: modelom, žetoni, zakasnitvijo, statusom, response_id
- Uporabi strukturirani JSON za dnevnike, ki jih tvoja orodja lahko razčlenijo
- Zberi ključne metrike: stopnjo uspešnosti, zakasnitev p95, porabo žetonov
- Dodaj
trace_idza povezovanje zahtev v porazdeljenih sistemih - Izvozi metrike v svoj sistem za nadzor (Prometheus, Datadog itd.)
- Nikoli ne beleži vsebine poziva v produkcijskem okolju (občutljivi podatki)