Salt la conținutul principal
Română— Alege o limbă
Meniu

Jurnalizare și Observabilitate

Lecția 15 din 22 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Jurnalizare și Observabilitate
  2. Jurnalizare Structurată de Bază
  3. Middleware de Jurnalizare
  4. Urmărirea Apelurilor cu Context
  5. Exportul către un Sistem de Monitorizare
  6. Puncte cheie

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_id pentru 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)