Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Žurnālizācija un novērojamība

Nodarbība 15 no 22 Atjaunota 2026. gada 29. jūlijs Programmētājs
Šajā lapā
  1. Žurnālizācija un novērojamība
  2. Pamata strukturēta žurnālizācija
  3. Žurnālizācijas starpniekprogrammatūra
  4. Izsaukumu izsekošana ar kontekstu
  5. Eksportēšana uz monitoringa sistēmu
  6. Galvenās atziņas

Žurnālizācija un novērojamība

Produkcijas vidē tev ir precīzi jāzina, kas notiek ar taviem API izsaukumiem: latentums, patērētie tokeni, kļūdas un izmaksas. Strukturēta žurnālizācija un novērojamība nodrošina šo redzamību. Atšķirība kļūst acīmredzama brīdī, kad lietotājs ziņo: „Kopš šī rīta asistents darbojas lēni.” Bez instrumentācijas tu esi spiests minēt. Ar to tu trīsdesmit sekundēs vari redzēt, ka p95 latentums ir dubultojies pēc prompta izmaiņām, kas trīskāršoja konteksta lielumu.

Pamata strukturēta žurnālizācija

Ieradies mērīt laiku ap izsaukumu, nevis tā iekšienē. Nolasī pulksteni pirms, nolasī to vēlreiz pēc tam un izvadī vienu rindiņu, kas apraksta visu notikumu. JSON nav tikai skaistumam: tas ļauj tavam agregatoram filtrēt pēc status, izsekot duration_ms laika gaitā vai atrast konkrētu response_id — ko brīvas formas teksts nekad nespēj. Bloks except ģenerē tieši tādu pašu struktūru, ieskaitot izņēmuma tipu un ziņojumu, un pēc tam atkārtoti izraisa kļūdu. Žurnālizācija nav kļūdu apstrāde.

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

Ņem vērā, ka mēs žurnālizējam prompt_length, nevis pašu promptu. Tas ir dizaina lēmums, nevis kļūda: garums ir pietiekams, lai korelētu ar latentumu, neeksportējot lietotāja datus uz tavu žurnālu sistēmu.

Žurnālizācijas starpniekprogrammatūra

Šī bloka atkārtošana katrā funkcijā, kas izsauc API, garantē, ka kaut kur to aizmirsīsi. Labāk ir aptīt klientu vienreiz un uz visiem laikiem. Datu klase APIMetrics definē līgumu par to, ko mēs mērām, un ObservableClient aizpilda šo ierakstu un arhivē to neatkarīgi no tā, vai izsaukums ir veiksmīgs vai ne. Metode rapport pēc tam pārvērš vēsturi tieši izmantojamos rādītājos — veiksmes rādītājs, vidējais latentums, p95 latentums.

Pēdējais skaitlis ir vissvarīgākais. Vidējais rādītājs 450 ms var slēpt to, ka viens no divdesmit lietotājiem gaida trīs sekundes; p95 to atklāj. Sakārtojot ilgumus un paņemot vērtību 95. procentilē, tu apraksti savu visvairāk cietušo aktīvo lietotāju reālo pieredzi.

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

Izsaukumu izsekošana ar kontekstu

Distributētā arhitektūrā API izsaukums nekad nepastāv izolēti: to izraisa HTTP pieprasījums, kas pats izriet no lietotāja darbības, un dažkam tam seko vēl divi izsaukumi. trace_id ir diegs, kas saista šos notikumus kopā. Propagējot to no tava tīmekļa slāņa — šeit user-123-req-456 — tu vari atjaunot visu sesiju savos žurnālos, balstoties uz vienu klienta sūdzību. Tiek izvadītas divas rindiņas: viena sākumā un viena pabeigšanas brīdī, kas arī palīdz noteikt izsaukumus, kas nekad neatgriezās.

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

Uzmanies ar prompt_preview: šie pirmie simts simboli nonāk taviem žurnālos tieši tādi, kādi tie ir. Izstrādes vidē tas ir pieņemami, taču tiklīdz plūst reāli dati, tas ir jānoņem.

Eksportēšana uz monitoringa sistēmu

Atmiņā glabāta vēsture pazūd, procesam restartējoties. Lai uzraudzītu servisu laika gaitā, tev ir jāeksportē metrikas uz ārēju rīku. Universālais modelis balstās uz divām saīmēm: skaitītājiem, kas tikai pieaug un no kuriem tiek atvasināti ātrumi, un histogramām, kas saglabā sadalījumu, lai iegūtu percentiles. Šī klase ir apzināti neitrāla — tev vienkārši ir jāpiesaista get_metrics galapunktam, ko Prometheus var aptaujāt, vai jānosūta vārdnīca uz 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

Galvenās atziņas

  • Žurnālizē katru izsaukumu ar: modeli, tokeniem, latentumu, statusu, response_id
  • Izmanto strukturētu JSON žurnāliem, ko tavi rīki var parsēt
  • Vāc galvenos rādītājus: veiksmes rādītāju, p95 latentumu, tokenu patēriņu
  • Pievieno trace_id, lai korelētu pieprasījumus distributētās sistēmās
  • Eksportē metrikas uz savu monitoringa sistēmu (Prometheus, Datadog u.c.)
  • Nekad nežurnālizē prompta saturu produkcijā (konfidenciāli dati)