Przejdź do głównej treści
Polski— Wybierz język
Menu

Rejestrowanie zdarzeń i obserwowalność

Lekcja 15 z 22 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Rejestrowanie zdarzeń i obserwowalność
  2. Podstawowe ustrukturyzowane rejestrowanie zdarzeń
  3. Middleware do rejestrowania zdarzeń
  4. Śledzenie wywołań z kontekstem
  5. Eksportowanie do systemu monitorowania
  6. Kluczowe wnioski

Rejestrowanie zdarzeń i obserwowalność

W środowisku produkcyjnym musisz wiedzieć dokładnie, co dzieje się z Twoimi wywołaniami API: opóźnienia, zużyte tokeny, błędy i koszty. Ustrukturyzowane rejestrowanie zdarzeń (logging) i obserwowalność zapewniają Ci tę widoczność. Różnica staje się oczywista w momencie, gdy użytkownik zgłasza: „Asystent działa wolno od rana“. Bez instrumentacji możesz tylko zgadywać. Dzięki niej w trzydzieści sekund zobaczysz, że latencja p95 podwoiła się po zmianie promptu, która potroiła rozmiar kontekstu.

Podstawowe ustrukturyzowane rejestrowanie zdarzeń

Wyrób sobie nawyk mierzenia czasu wokół wywołania, a nie w jego trakcie. Zapisz czas przed, odczytaj go ponownie po i wyemituj pojedynczą linię opisującą całe zdarzenie. JSON nie jest tylko dla pokazówki: pozwala agregatorowi filtrować po status, śledzić duration_ms w czasie lub wyszukać konkretny response_id – czego nie zrobi nigdy swobodny tekst. Blok except generuje dokładnie taką samą strukturę, łącznie z typem wyjątku i komunikatem, a następnie ponownie go zgłasza. Rejestrowanie to nie obsługa błędów.

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 wywolanie_z_logowaniem(prompt: str, model: str = "gpt-5.6-terra") -> str:
    """Wywołanie API z pełnym ustrukturyzowanym logowaniem."""
    start = time.monotonic()
    request_id = None

    try:
        response = client.responses.create(
            model=model,
            input=prompt
        )

        czas_trwania = 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(czas_trwania * 1000),
            "prompt_length": len(prompt),
        }))

        return response.output_text

    except Exception as e:
        czas_trwania = 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(czas_trwania * 1000),
            "prompt_length": len(prompt),
        }))
        raise

wynik = wywolanie_z_logowaniem("Hello!")

Zauważ, że logujemy prompt_length, a nie sam prompt. To wybór projektowy, a nie przeoczenie: długość wystarcza do skorelowania z latencją, bez eksportowania danych użytkownika do systemu logów.

Middleware do rejestrowania zdarzeń

Powtarzanie tego bloku w każdej funkcji wywołującej API gwarantuje, że kiedyś o nim zapomnisz. Lepiej jest raz na zawsze opakować klienta. Klasa danych APIMetrics definiuje kontrakt tego, co mierzymy, a ObservableClient wypełnia ten rekord i archiwizuje go, niezależnie od tego, czy wywołanie zakończy się sukcesem, czy porażką. Metoda raport przekształca następnie historię w metryki gotowe do natychmiastowego działania – wskaźnik sukcesu, średnią latencję, latencję p95.

Ta ostatnia liczba ma największe znaczenie. Średnia 450 ms może ukrywać fakt, że jeden na dwudziestu użytkowników czeka trzy sekundy; p95 to ujawnia. Sortując czasy trwania i pobierając wartość z 95. percentyla, opisujesz rzeczywiste doświadczenie Twoich najgorzej obsługiwanych aktywnych użytkowników.

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

@dataclass
class APIMetrics:
    """Metryki zbierane dla każdego wywołania."""
    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 z wbudowaną obserwowalnością."""

    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 raport(self) -> dict:
        """Generuje raport zebranych metryk."""
        if not self.metrics_history:
            return {"message": "No calls recorded"}

        total_calls = len(self.metrics_history)
        bledy = sum(1 for m in self.metrics_history if m.status == "error")
        total_tokens = sum(m.total_tokens for m in self.metrics_history)
        czasy_trwania = [m.duration_ms for m in self.metrics_history]

        return {
            "total_appels": total_calls,
            "erreurs": bledy,
            "taux_succes": f"{((total_calls - bledy) / total_calls) * 100:.1f}%",
            "total_tokens": total_tokens,
            "latence_moyenne_ms": round(sum(czasy_trwania) / len(czasy_trwania)),
            "latence_p95_ms": sorted(czasy_trwania)[int(len(czasy_trwania) * 0.95)],
        }

# Użycie
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))
# Wynik:
# {
#   "total_appels": 3,
#   "erreurs": 0,
#   "taux_succes": "100.0%",
#   "total_tokens": 95,
#   "latence_moyenne_ms": 450,
#   "latence_p95_ms": 520
# }

Śledzenie wywołań z kontekstem

W architekturze rozproszonej wywołanie API nigdy nie istnieje w izolacji: jest wyzwalane przez żądanie HTTP, które samo wynika z akcji użytkownika, a czasem jest followed przez dwa kolejne wywołania. trace_id to nić łącząca te zdarzenia. Propagując je z warstwy internetowej – tutaj user-123-req-456 – możesz zrekonstruować całą sesję w swoich logach na podstawie jednej skargi klienta. Emitowane są dwie linie: jedna na początku i jedna po zakończeniu, co pomaga również wykryć wywołania, które nigdy nie zwróciły wyniku.

import uuid

class TracingClient:
    """Klient ze śledzeniem do korelowania żądań."""

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

    def create_with_trace(self, prompt: str, trace_id: str = None,
                          **kwargs) -> tuple:
        """Wywołanie z trace_id do korelacji."""
        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

# Użycie z trace_id do korelacji w logach
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]}...")

Uważaj na prompt_preview: te pierwsze sto znaków trafiają prosto do Twoich logów tak, jak są. Akceptowalne w fazie rozwoju, usuń to natychmiast, gdy zaczną płynąć prawdziwe dane.

Eksportowanie do systemu monitorowania

Historia przechowywana w pamięci znika po restarcie procesu. Aby monitorować usługę w czasie, musisz udostępnić metryki zewnętrznemu narzędziu. Uniwersalny wzorzec opiera się na dwóch rodzinach: licznikach (counters), które tylko rosną i są przekształcane w stawki, oraz histogramach, które przechowują rozkład, aby wydobyć percentyle. Ta klasa jest celowo neutralna – wystarczy podpiąć get_metrics pod endpoint, aby Prometheus mógł go odpytywać, lub wypchnąć słownik do Datadog.

# Wzorzec eksportu do Prometheus, Datadog itp.
class MetricsExporter:
    """Eksporter metryk kompatybilny z systemami monitorowania."""

    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()
# Wywołaj exporter.record_success() lub exporter.record_error()
# po każdym wywołaniu API

Kluczowe wnioski

  • Loguj każde wywołanie zawierające: model, tokeny, latencję, status, response_id
  • Używaj ustrukturyzowanego JSON dla logów, które Twoje narzędzia mogą parsować
  • Zbieraj kluczowe metryki: wskaźnik sukcesu, latencja p95, zużycie tokenów
  • Dodaj trace_id, aby skorelować żądania w systemach rozproszonych
  • Eksportuj metryki do swojego systemu monitorowania (Prometheus, Datadog itp.)
  • Nigdy nie loguj treści promptu w środowisku produkcyjnym (dane wrażliwe)