Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Logovanie a pozorovateľnosť

Lekcia 15 z 22 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Logovanie a pozorovateľnosť
  2. Základné štruktúrované logovanie
  3. Logovací middleware
  4. Sledovanie volaní s kontextom
  5. Export do monitorovacieho systému
  6. Kľúčové poznatky

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