Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Logimine ja jälgitavus

Õppetund 15 / 22 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Logimine ja jälgitavus
  2. Lihtne struktureeritud logimine
  3. Logimise vahevara (Middleware)
  4. Päringute jälgimine kontekstiga
  5. Eksportimine jälgimissüsteemi
  6. Peamised punktid

Logimine ja jälgitavus

Tootmiskeskkonnas pead täpselt teadma, mis toimub sinu API päringutega: latentsus, tarbitud tokenid, vead ja kulud. Struktureeritud logimine ja jälgitavus annavad sulle selle ülevaate. Erinevus saab selgeks hetkel, kui kasutaja teatab: „Assistent on olnud tänahommikust aeglane.“ Ilma instrumendita jääd sa arvama. Sellega näed kolmekümne sekundiga, et p95 latentsus kahekordistus pärast vihje muutmist, mis kolmekordistas konteksti suurust.

Lihtne struktureeritud logimine

Harjumuseks peaks saama mõõtmine enne ja pärast väljakutset, mitte selle sees. Salvesta kellaaeg enne, loe see uuesti pärast ja väljasta üks rida, mis kirjeldab kogu sündmust. JSON ei ole ainult ilu pärast: see võimaldab sinu agregaatoril filtreerida status järgi, jälgida duration_ms aja jooksul või otsida üles konkreetse response_id – mida vabas vormis tekst kunagi teha ei saa. Plokk except loob täpselt sama struktuuri, kaasates erandi tüübi ja sõnumi, ning viskab seejärel vea uuesti üles. Logimine ei ole veakäsitlus.

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

Pane tähele, et logime prompt_length, mitte vihjet ennast. See on disainivalik, mitte tähelepanematus: pikkus on piisav latentsusega korreleerumiseks, ilma et ekspordiks kasutajaandmeid oma logimissüsteemi.

Logimise vahevara (Middleware)

Selle ploki kordamine igas funktsioonis, mis kutsub API-d, garanteerib, et unustad selle kusagil ära. Parem on mähkida klient üks kord ja igaveseks. Andmeklass APIMetrics määratleb lepingu selle kohta, mida mõõdame, ja ObservableClient täidab selle kirje ja arhiveerib selle, olenemata sellest, kas väljakutse õnnestus või ebaõnnestus. Meetod rapport muudab seejärel ajaloo otse tegutsemiseks sobivateks mõõdikuks – edu määr, keskmine latentsus, p95 latentsus.

Viimane number on kõige olulisem. Keskmine 450 ms võib varjata üht kahekümnest kasutajast, kes ootab kolm sekundit; p95 paljastab selle. Sorteerides kestused ja võttes väärtuse 95. protsentiililt, kirjeldad oma halvimalt teenindatud aktiivsete kasutajate tegelikku kogemust.

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

Päringute jälgimine kontekstiga

Hajutatud arhitektuuris ei eksisteeri API päring kunagi isoleeritult: selle käivitab HTTP päring, mis tuleneb omakorda kasutaja tegevusest, ja mõnikord järgnevad sellele veel kaks päringut. trace_id on niit, mis seob need sündmused kokku. Edastades seda oma veebikihist – siin user-123-req-456 – saad rekonstrueerida terve seansi oma logides ühestainsast kliendi kaebusest. Väljastatakse kaks rida, üks alguses ja üks lõpetamisel, mis aitab tuvastada ka päringuid, mis kunagi ei tagastunud.

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

Ole ettevaatlik prompt_preview-ga: need esimesed sada tähemärki lähevad otse sinu logidesse muutumatul kujul. Arenduses on see vastuvõetav, eemalda see niipea, kui reaalsed andmed voolama hakkavad.

Eksportimine jälgimissüsteemi

Mälus olev ajalugu kaob protsessi taaskäivitamisel. Teenuse jälgimiseks aja jooksul pead mõõdikud avaldama välisele tööriistale. Universaalne muster tugineb kahele perekonnale: loendurid, mis ainult kasvavad ja millest tuletatakse määrasid, ning histogrammid, mis säilitavad jaotuse protsentiilide ekstraheerimiseks. See klass on tahtlikult neutraalne – sul tuleb lihtalt ühendada get_metrics lõpp-punktiga, mida Prometheus saaks skannida, või suruda sõnastik Datadogi.

# 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

Peamised punktid

  • Logi iga väljakutse koos: mudel, tokenid, latentsus, staatus, response_id
  • Kasuta logide jaoks struktureeritud JSON-i, mida sinu tööriistad saavad parsida
  • Kogu võtmemõõdikuid: edu määr, p95 latentsus, tokenite tarbimine
  • Lisa trace_id, et korreleerida päringuid hajutatud süsteemides
  • Ekspordi mõõdikud oma jälgimissüsteemi (Prometheus, Datadog jne)
  • Ära kunagi logi vihje sisu tootmiskeskkonnas (tundlikud andmed)