Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Dnevniški zapisi in opazljivost

Lekcija 15 od 22 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Dnevniški zapisi in opazljivost
  2. Osnovno strukturirano beleženje
  3. Vmesna programska oprema za beleženje
  4. Sledenje klicem s kontekstom
  5. Izvoz v sistem za nadzor
  6. Ključne ugotovitve

Dnevniški zapisi in opazljivost

V produkcijskem okolju moraš točno vedeti, kaj se dogaja s tvojimi klici API-ja: zakasnitev, porabljeni žetoni, napake in stroški. Strukturirani dnevniški zapisi in opazljivost ti zagotavljata ta vpogled. Razlika postane očitna v trenutku, ko uporabnik sporoči: „Pomočnik je od danes zjutraj počasen.” Brez instrumentacije ugibaš. Z njo lahko v tridesetih sekundah vidiš, da se je zakasnitev p95 podvojila po spremembi poziva, ki je potrojila velikost konteksta.

Osnovno strukturirano beleženje

Naj ti pride v navado meriti čas okoli klica, ne znotraj njega. Zabeleži čas pred klicem, ponovno ga odčitaj po njem in izpiši eno samo vrstico, ki opisuje celoten dogodek. JSON ni zgolj za lepši videz: omogoča tvojemu agregatorju filtriranje po status, sledenje duration_ms skozi čas ali iskanje določenega response_id – česar prosto oblikovano besedilo nikoli ne zmore. Blok except ustvari popolnoma enako strukturo, vključno z vrsto napake in sporočilom, nato pa ponovno sproži izjemo. Beleženje ni obravnava napak.

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

Upoštevaj, da beležimo prompt_length, ne samega poziva. To je načrtna odločitev, ne spregled: dolžina zadostuje za povezavo z zakasnitvijo, ne da bi izvažal uporabniške podatke v svoj sistem dnevniških zapisov.

Vmesna programska oprema za beleženje

Ponavljanje tega bloka v vsaki funkciji, ki kliče API, zagotavlja, da ga boš nekje pozabil. Bolje je, da oviješ odjemalca enkrat za vselej. Podatkovni razred APIMetrics definira pogodbo o tem, kaj merimo, ObservableClient pa zapolni ta zapis in ga arhivira, ne glede na to, ali klic uspe ali odpove. Metoda rapport nato zgodovino pretvori v neposredno uporabne metrike – stopnjo uspešnosti, povprečno zakasnitev, zakasnitev p95.

Zadnja številka je najpomembnejša. Povprečje 450 ms lahko skrije enega od dvajsetih uporabnikov, ki čaka tri sekunde; p95 to razkrije. Z razvrščanjem trajanj in vzemanjem vrednosti na 95. percentilu opišeš dejansko izkušnjo svojih najbolj prikrajšanih aktivnih uporabnikov.

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

Sledenje klicem s kontekstom

V porazdeljeni arhitekturi klic API-ja nikoli ne obstaja izolirano: sproži ga HTTP zahteva, ki izvira iz uporabnikovega dejanja, včasih pa mu sledita še dva dodatna klica. trace_id je nit, ki povezuje te dogodke. S posredovanjem iz tvoje spletne plasti – tukaj user-123-req-456 – lahko iz ene same pritožbe stranke v dnevniških zapisih rekonstruiraš celotno sejo. Izpišeta se dve vrstici, ena na začetku in ena ob zaključku, kar pomaga tudi pri odkrivanju klicev, ki se nikoli niso vrnili.

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

Bodi previden pri prompt_preview: teh prvih sto znakov gre neposredno v tvoje dnevniške zapise, takšnih, kot so. Sprejemljivo v razvojnem okolju, odstrani pa jih takoj, ko stečejo realni podatki.

Izvoz v sistem za nadzor

Zgodovina v pomnilniku izgine, ko se proces ponovno zažene. Za nadzor storitve skozi čas moraš metrike izpostaviti zunanjemu orodju. Univerzalni vzorec temelji na dveh družinah: števcih, ki se le povečujejo in iz katerih izpeljemo stopnje, ter histogramih, ki ohranjajo porazdelitev za ekstrakcijo percentil. Ta razred je namerno nevtralen – le povezati moraš get_metrics s končno točko, ki jo bo pregledal Prometheus, ali pa slovar potisniti v 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

Ključne ugotovitve

  • Zabeleži vsak klic z: modelom, žetoni, zakasnitvijo, statusom, response_id
  • Uporabi strukturirani JSON za dnevnike, ki jih tvoja orodja lahko razčlenijo
  • Zberi ključne metrike: stopnjo uspešnosti, zakasnitev p95, porabo žetonov
  • Dodaj trace_id za povezovanje zahtev v porazdeljenih sistemih
  • Izvozi metrike v svoj sistem za nadzor (Prometheus, Datadog itd.)
  • Nikoli ne beleži vsebine poziva v produkcijskem okolju (občutljivi podatki)