Jurnalizare și Observabilitate
Pe această pagină
Jurnalizare și Observabilitate
În producție, trebuie să știți exact ce se întâmplă cu apelurile API: latență, tokeni consumați, erori și costuri. Jurnalizarea structurată și observabilitatea vă oferă această vizibilitate. Diferența devine clară în momentul în care un utilizator raportează: „Asistentul merge greu de dimineață.“ Fără instrumentare, rămâneți la ghicit. Cu ea, puteți vedea în treizeci de secunde că latența p95 s-a dublat după o modificare a promptului care a triplat dimensiunea contextului.
Jurnalizare Structurată de Bază
Obișnuiți-vă să măsurați în jurul apelului, nu în interiorul lui. Citiți ceasul înainte, citiți-l din nou după și emiteți o singură linie care descrie întregul eveniment. JSON nu este doar pentru aspect: permite agregatorului să filtreze după status, să urmărească duration_ms în timp sau să caute un response_id specific—ceva ce textul liber nu poate face niciodată. Blocul except produce exact aceeași structură, inclusiv tipul excepției și mesajul, apoi re-aruncă eroarea. Jurnalizarea nu înseamnă gestionarea erorilor.
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 apel_cu_jurnalizare(prompt: str, model: str = "gpt-5.6-terra") -> str:
"""Apel API cu jurnalizare structurată completă."""
start = time.monotonic()
request_id = None
try:
response = client.responses.create(
model=model,
input=prompt
)
durata = 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(durata * 1000),
"prompt_length": len(prompt),
}))
return response.output_text
except Exception as e:
durata = 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(durata * 1000),
"prompt_length": len(prompt),
}))
raise
rezultat = apel_cu_jurnalizare("Hello!")
Observați că jurnalizăm prompt_length, nu promptul însuși. Aceasta este o alegere de design, nu o scăpare: lungimea este suficientă pentru corelarea cu latența, fără a exporta datele utilizatorului în sistemul de jurnalizare.
Middleware de Jurnalizare
Repetarea acestui bloc în fiecare funcție care apelează API garantează că îl veți uita undeva. Mai bine înfășurați clientul o dată pentru totdeauna. Clasa de date APIMetrics definește contractul pentru ceea ce măsurăm, iar ObservableClient populează acea înregistrare și o arhivează, indiferent dacă apelul reușește sau eșuează. Metoda raport transformă apoi istoricul în metrici direct acționabile—rata de succes, latența medie, latența p95.
Acel ultim număr contează cel mai mult. O medie de 450 ms poate asculta faptul că unul din douăzeci de utilizatori așteaptă trei secunde; p95 dezvăluie acest lucru. Sortând duratele și luând valoarea de la percentila 95, descrieți experiența reală a utilizatorilor activi cei mai defavorizați.
from dataclasses import dataclass, field
from typing import Optional
import time
import json
@dataclass
class APIMetrics:
"""Metrici colectate pentru fiecare apel."""
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:
"""Client OpenAI cu observabilitate integrată."""
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 raport(self) -> dict:
"""Generează un raport al metricilor colectate."""
if not self.metrics_history:
return {"message": "No calls recorded"}
total_apeluri = len(self.metrics_history)
erori = sum(1 for m in self.metrics_history if m.status == "error")
total_tokeni = sum(m.total_tokens for m in self.metrics_history)
durate = [m.duration_ms for m in self.metrics_history]
return {
"total_apeluri": total_apeluri,
"erori": erori,
"rata_succes": f"{((total_apeluri - erori) / total_apeluri) * 100:.1f}%",
"total_tokeni": total_tokeni,
"latenta_medie_ms": round(sum(durate) / len(durate)),
"latenta_p95_ms": sorted(durate)[int(len(durate) * 0.95)],
}
# Utilizare
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.raport(), indent=2))
# Rezultat:
# {
# "total_apeluri": 3,
# "erori": 0,
# "rata_succes": "100.0%",
# "total_tokeni": 95,
# "latenta_medie_ms": 450,
# "latenta_p95_ms": 520
# }
Urmărirea Apelurilor cu Context
Într-o arhitectură distribuită, un apel API nu există niciodată izolat: este declanșat de o cerere HTTP, care provine ea însăși dintr-o acțiune a utilizatorului și este uneori urmată de încă două apeluri. trace_id este firul care leagă aceste evenimente. Propagându-l din stratul web—aici user-123-req-456—puteți reconstrui o sesiune întreagă în jurnalele dumneavoastră pornind de la o singură plângere a clientului. Sunt emise două linii, una la început și una la finalizare, ceea ce ajută și la identificarea apelurilor care nu s-au întors niciodată.
import uuid
class TracingClient:
"""Client cu urmărire pentru corelarea cererilor."""
def __init__(self):
self.client = OpenAI()
def create_with_trace(self, prompt: str, trace_id: str = None,
**kwargs) -> tuple:
"""Apel cu trace_id pentru corelare."""
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
# Utilizare cu trace_id pentru corelarea în jurnale
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]}...")
Fiți atenți la prompt_preview: acele prime o sută de caractere ajung direct în jurnalele dumneavoastră așa cum sunt. Acceptabil în dezvoltare, eliminați-l imediat ce circulă date reale.
Exportul către un Sistem de Monitorizare
Un istoric în memorie dispare la repornirea procesului. Pentru a monitoriza un serviciu în timp, trebuie să expuneți metricile către un instrument extern. Modelul universal se bazează pe două familii: contoare, care doar cresc și sunt derivate în rate, și histograme, care păstrează o distribuție pentru a extrage percentile. Această clasă este intenționat neutră—trebuie doar să conectați get_metrics la un endpoint pentru ca Prometheus să îl interogheze sau să împingeți dicționarul către Datadog.
# Model pentru export către Prometheus, Datadog, etc.
class MetricsExporter:
"""Exportor de metrici compatibil cu sistemele de monitorizare."""
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()
# Apelați exporter.record_success() sau exporter.record_error()
# după fiecare apel API
Puncte cheie
- Jurnalizați fiecare apel cu: model, tokeni, latență, status, response_id
- Folosiți JSON structurat pentru jurnale pe care instrumentele le pot analiza
- Colectați metrici cheie: rata de succes, latența p95, consumul de tokeni
- Adăugați un
trace_idpentru a corela cererile în sistemele distribuite - Exportați metricile către sistemul de monitorizare (Prometheus, Datadog, etc.)
- Nu jurnalizați niciodată conținutul promptului în producție (date sensibile)