Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Logování a pozorovatelnost

Lekce 15 z 22 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Logování a pozorovatelnost
  2. Základní strukturované logování
  3. Middleware pro logování
  4. Sledování volání s kontextem
  5. Export do monitorovacího systému
  6. Klíčové poznatky

Logování a pozorovatelnost

V produkčním prostředí musíš přesně vědět, co se děje s tvými voláními API: latence, spotřebované tokeny, chyby a náklady. Strukturované logování a pozorovatelnost ti poskytují tuto viditelnost. Rozdíl poznáš hned v okamžiku, kdy uživatel nahlásí: „Asistent je od rána pomalý.“ Bez instrumentace jen hádáš. S ní během třiceti sekund zjistíš, že se latence p95 zdvojnásobila po změně promptu, která ztrojnásobila velikost kontextu.

Základní strukturované logování

Zvykni si měřit čas kolem volání, ne uvnitř něj. Zaznamenej čas před voláním, znovu jej odečti po volání a emituj jediný řádek popisující celou událost. JSON není jen pro parádu: umožňuje tvému agregátoru filtrovat podle status, sledovat duration_ms v čase nebo vyhledat konkrétní response_id – což volný text nikdy nedokáže. Blok except vytvoří přesně stejnou strukturu, včetně typu výjimky a zprávy, a poté výjimku znovu vyhodí. Logování není zpracování chyb.

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:
    """Volání API s úplným strukturovaným logováním."""
    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, nikoliv samotný prompt. Je to designové rozhodnutí, ne opomenutí: délka stačí ke korelaci s latencí, aniž by se uživatelská data exportovala do tvého logovacího systému.

Middleware pro logování

Opakování tohoto bloku v každé funkci, která volá API, garantuje, že na to někde zapomeneš. Lepší je zabalit klienta jednou provždy. Datová třída APIMetrics definuje kontrakt toho, co měříme, a ObservableClient tuto records naplňuje a archivuje, ať už volání uspěje nebo selže. Metoda rapport následně převede historii na přímo akční metriky – míru úspěšnosti, průměrnou latenci, latenci p95.

Poslední číslo je nejdůležitější. Průměr 450 ms může skrývat jednoho z dvaceti uživatelů, který čeká tři sekundy; p95 to odhalí. Seřazením dob trvání a vybráním hodnoty na 95. percentilu popíšeš reálnou zkušenost svých nejhůře obsloužených aktivních uživatelů.

from dataclasses import dataclass, field
from typing import Optional
import time
import json

@dataclass
class APIMetrics:
    """Metriky sbírané pro každé volání."""
    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:
    """Klient OpenAI s vestavěnou pozorovatelností."""

    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:
        """Generuje report nasbíraných metrik."""
        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)],
        }

# Použití
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))
# Výsledek:
# {
#   "total_appels": 3,
#   "erreurs": 0,
#   "taux_succes": "100.0%",
#   "total_tokens": 95,
#   "latence_moyenne_ms": 450,
#   "latence_p95_ms": 520
# }

Sledování volání s kontextem

V distribuované architektuře nikdy neexistuje volání API v izolaci: je spuštěno HTTP požadavkem, který sám vychází z uživatelské akce, a někdy po něm následují další dvě volání. trace_id je vlákno, které tyto události spojuje dohromady. Propagací tohoto ID z tvé webové vrstvy – zde user-123-req-456 – můžeš z jedné stížnosti zákazníka rekonstruovat celou relaci v logách. Emitují se dva řádky, jeden na začátku a jeden při dokončení, což také pomáhá odhalit volání, která se nikdy nevrátila.

import uuid

class TracingClient:
    """Klient se sledováním pro korelaci požadavků."""

    def __init__(self):
        self.client = OpenAI()

    def create_with_trace(self, prompt: str, trace_id: str = None,
                          **kwargs) -> tuple:
        """Volání s trace_id pro korelaci."""
        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

# Použití s trace_id pro korelaci v logách
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]}...")

Dej si pozor na prompt_preview: těchto prvních sto znaků jde přímo do tvých logů tak, jak jsou. Ve vývoji je to přijatelné, ale jakmile potečou reálná data, okamžitě to odstraň.

Export do monitorovacího systému

Historie v paměti zmizí při restartu procesu. Chcete-li službu sledovat v čase, musíte exponovat metriky externímu nástroji. Univerzální vzor spoléhá na dvě rodiny: čítače, které pouze rostou a odvozují se z nich rychlosti, a histogramy, které uchovávají distribuci pro extrakci percentilů. Tato třída je záměrně neutrální – stačí napojit get_metrics na endpoint, který bude Prometheus scrapovat, nebo poslat slovník do Datadog.

# Vzor pro export do Prometheus, Datadog atd.
class MetricsExporter:
    """Exportér metrik kompatibilní s monitorovacími systémy."""

    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()
# Zavolej exporter.record_success() nebo exporter.record_error()
# po každém volání API

Klíčové poznatky

  • Loguj každé volání s: modelem, tokeny, latencí, statusem, response_id
  • Pro logy používej strukturovaný JSON, který tvé nástroje dokážou parsovat
  • Sbírej klíčové metriky: míra úspěšnosti, latence p95, spotřeba tokenů
  • Přidej trace_id pro korelaci požadavků v distribuovaných systémech
  • Exportuj metriky do svého monitorovacího systému (Prometheus, Datadog atd.)
  • Nikdy neloguj obsah promptu v produkci (citlivá data)