Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Naplózás és megfigyelhetőség

15. lecke 22 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Naplózás és megfigyelhetőség
  2. Alapvető strukturált naplózás
  3. Naplózási middleware
  4. Hívások nyomkövetése kontextussal
  5. Exportálás egy monitorozó rendszerbe
  6. Főbb megállapítások

Naplózás és megfigyelhetőség

Éles környezetben pontosan tudnod kell, mi történik az API-hívásaiddal: késleltetés, felhasznált tokenek, hibák és költségek. A strukturált naplózás és a megfigyelhetőség biztosítja ezt az átláthatóságot. A különbség akkor válik nyilvánvalóvá, amikor egy felhasználó azt jelenti: „A segéd lassú ma reggel óta.“ Instrumentálás nélkül csak találgatsz. Ezzel szemben harminc másodperc alatt láthatod, hogy a p95 késleltetés megduplázódott egy prompt-módosítás után, amely megháromszorozta a kontextus méretét.

Alapvető strukturált naplózás

Szoktasd rá magad, hogy a hívás körülményeit méred, nem pedig magát a hívást. Jegyezd fel az időt előtte, olvasd be újra utána, és bocsáss ki egyetlen sort, amely leírja az egész eseményt. A JSON nem csak dísznek van: lehetővé teszi, hogy az aggregátorod szűrjön a status alapján, nyomon kövesse a duration_ms értéket az időben, vagy kikeresen egy adott response_id-t – valamit, amit a szabad szöveg sosem tudna megtenni. Az except blokk pontosan ugyanazt a struktúrát állítja elő, beleértve a kivétel típusát és üzenetét, majd újra dobja a hibát. A naplózás nem egyenlő a hibakezeléssel.

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!")

Figyeld meg, hogy a prompt_length-et naplózzuk, nem magát a promptot. Ez tervezési döntés, nem figyelmetlenség: a hosszúság elegendő a késleltetéssel való korrelációhoz anélkül, hogy felhasználói adatokat exportálnál a naplózási rendszeredbe.

Naplózási middleware

Ha minden egyes API-t hívó függvényben megismétled ezt a blokkot, garantált, hogy valahol elfelejted. Jobb, ha egyszer és mindenkorra becsomagolod a klienst. Az APIMetrics adatosztály (dataclass) definiálja a mérési szerződést, az ObservableClient pedig kitölti ezt a rekordot és archiválja azt, függetlenül attól, hogy a hívás sikeres volt-e vagy sem. A rapport módszer ezután közvetlenül hasznosítható metrikákká alakítja az előzményeket: sikerarány, átlagos késleltetés, p95 késleltetés.

Ez utóbbi szám a legfontosabb. A 450 ms-os átlag elrejtheti azt az egy felhasználót a húszból, aki három másodpercet vár; a p95 ezt felfedi. A időtartamok rendezésével és a 95. percentilisnél lévő érték kiválasztásával leírod a legrosszabbul kiszolgált aktív felhasználóid valós élményét.

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
# }

Hívások nyomkövetése kontextussal

Elosztott architektúrában egy API-hívás sosem létezik elszigetelten: egy HTTP-kérés indítja el, amely maga is egy felhasználói cselekvésből származik, és néha két további hívás követi. A trace_id az a szál, amely összeköti ezeket az eseményeket. Azzal, hogy továbbítod ezt a webes rétegedből – itt például user-123-req-456 –, egyetlen ügyfélpanasz alapján rekonstruálhatsz egy teljes munkamenetet a naplóidban. Két sor kerül kiírásra, egy az elején és egy a befejezéskor, ami segít azoknak a hívásoknak a felderítésében is, amelyek sosem tértek vissza.

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]}...")

Légy óvatos a prompt_preview-vel: ez az első száz karakter változatlanul kerül a naplóidba. Fejlesztés során elfogadható, de amint éles adatok áramlanak, azonnal távolítsd el.

Exportálás egy monitorozó rendszerbe

A memóriában tárolt előzmények a folyamat újraindításakor eltűnnek. Ahhoz, hogy egy szolgáltatást időben nyomon követhess, ki kell tenned a metrikákat egy külső eszköz számára. Az egyetemes minta két családra támaszkodik: a számlálókra (counters), amelyek csak növekednek, és amelyekből ráták számíthatók, valamint a hisztogramokra, amelyek megőrzik az eloszlást a percentilisek kinyeréséhez. Ez az osztály szándékosan semleges – csak annyit kell tenned, hogy összekötöd a get_metrics metódust egy végponttal, amit a Prometheus leolvas, vagy elküldöd a szótárat a Datadognak.

# 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

Főbb megállapítások

  • Naplózz minden hívást a következőkkel: modell, tokenek, késleltetés, státusz, response_id
  • Használj strukturált JSON-t a naplókhoz, hogy az eszközeid parseolni tudják őket
  • Gyűjtsd a kulcsfontosságú metrikákat: sikerarány, p95 késleltetés, tokenfogyasztás
  • Adj hozzá egy trace_id-t a kérések korrelálásához elosztott rendszerekben
  • Exportáld a metrikákat a monitorozó rendszeredbe (Prometheus, Datadog stb.)
  • Soha ne naplózd a prompt tartalmát éles környezetben (érzékeny adatok)