Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Lokitus ja havainnoitavuus

Oppitunti 15 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Lokitus ja havainnoitavuus
  2. Perusmuotoinen strukturoitu lokitus
  3. Lokituksen välityskerroin (Middleware)
  4. Kutsujen jäljitys kontekstin avulla
  5. Vienti valvontajärjestelmään
  6. Keskeiset asiat

Lokitus ja havainnoitavuus

Tuotantoympäristössä sinun on tiedettävä tarkasti, mitä API-kutsuillesi tapahtuu: viiveet, kulutetut tokenit, virheet ja kustannukset. Strukturoitu lokitus ja havainnoitavuus tarjoavat tämän näkyvyyden. Ero käy selväksi heti, kun käyttäjä ilmoittaa: “Avustaja on ollut hidas aamusta lähtien.” Ilman instrumentointia joudut arvailemaan. Sen kanssa näet kolmessakymmenessä sekunnissa, että p95-viive kaksinkertaistui kehotteen muutoksen jälkeen, joka kolminkertaisti kontekstin koon.

Perusmuotoinen strukturoitu lokitus

Tee tavaksi mitata aika kutsun ympärillä, ei sen sisällä. Lue kello ennen kutsua, lue se uudelleen jälkeen ja tulosta yksi rivi, joka kuvaa koko tapahtumaa. JSON ei ole vain show’ta varten: sen ansiosta aggregaattorisi voi suodattaa kentän status perusteella, seurata arvoa duration_ms ajan myötä tai hakea tietyn response_id:n – jotain, mitä vapaa muotoinen teksti ei koskaan pysty tekemään. except-lohko tuottaa täsmälleen saman rakenteen, mukaan lukien poikkeustyypin ja viestin, ja heittää poikkeuksen uudelleen. Lokitus ei ole virheenkäsittelyä.

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-kutsu täydellisellä strukturoidulla lokituksella."""
    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!")

Huomaa, että lokitamme prompt_length:n emmekä itse kehote tekstiä. Tämä on suunnitteluratkaisu, ei unohdus: pituus riittää korreloimaan viiveen kanssa ilman, että viet käyttäjädataa lokijärjestelmääsi.

Lokituksen välityskerroin (Middleware)

Tämän lohkon toistaminen jokaisessa funktiossa, joka kutsuu API:a, takaa, että unohdat sen jossain vaiheessa. Parempi on kääriä asiakasohjelma kerralla pysyvästi. APIMetrics-dataclass määrittelee sopimuksen sille, mitä mittaamme, ja ObservableClient täyttää tämän tietueen ja arkistoi sen riippumatta siitä, onnistuuko kutsu vai epäonnistuuko se. rapport-metodi muuttaa historian sitten suoraan toimintakelpoisiksi mittareiksi: onnistumisprosentti, keskimääräinen viive ja p95-viive.

Viimeinen luku on tärkein. 450 ms:n keskiarvo voi piilottaa sen, että yksi käyttäjä kahdestakymmenestä odottaa kolme sekuntia; p95 paljastaa tämän. Lajittelemalla viiveet ja ottamalla arvon 95. persentiilistä kuvaat pahimmin palveltujen aktiivisten käyttäjiesi todellista kokemusta.

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

@dataclass
class APIMetrics:
    """Jokaiselle kutsulle kerätyt mittarit."""
    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-asiakasohjelma sisäänrakennetulla havainnoitavuudella."""

    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:
        """Generoi raportti kerätyistä mittareista."""
        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)],
        }

# Käyttö
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))
# Tulos:
# {
#   "total_appels": 3,
#   "erreurs": 0,
#   "taux_succes": "100.0%",
#   "total_tokens": 95,
#   "latence_moyenne_ms": 450,
#   "latence_p95_ms": 520
# }

Kutsujen jäljitys kontekstin avulla

Hajautetussa arkkitehtuurissa API-kutsu ei ole koskaan erillinen: sen laukaisee HTTP-pyyntö, joka itse johtuu käyttäjän toiminnasta, ja sitä seuraa joskus kaksi muuta kutsua. trace_id on lanka, joka sitoo nämä tapahtumat yhteen. Välittämällä sen verkkokerroksestasi – tässä tapauksessa user-123-req-456 – voit rekonstruoida koko istunnon lokeistasi yhden asiakasvalituksen perusteella. Kaksi riviä emittoituu, yksi alussa ja yksi lopussa, mikä auttaa myös havaitsemaan kutsut, jotka eivät koskaan palautuneet.

import uuid

class TracingClient:
    """Asiakasohjelma pyyntöjen korrelaatiota varten tarkoitetulla jäljityksellä."""

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

    def create_with_trace(self, prompt: str, trace_id: str = None,
                          **kwargs) -> tuple:
        """Kutsu trace_id:llä korrelaatiota varten."""
        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

# Käyttö trace_id:n kanssa korrelointia varten lokeissa
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]}...")

Varo prompt_preview:tä: nuo ensimmäiset sata merkkiä menevät sellaisinaan suoraan lokeihisi. Hyväksyttävää kehitysvaiheessa, mutta poista se heti, kun todellista dataa alkaa virrata.

Vienti valvontajärjestelmään

Muistissa oleva historia katoaa, kun prosessi käynnistyy uudelleen. Palvelun seuraamiseksi ajan myötä sinun on vietävä mittarit ulkoiseen työkaluun. Yleinen malli nojaa kahteen perheeseen: laskureihin, jotka vain kasvavat ja joista johdetaan nopeuksia, sekä histogrammeihin, jotka säilyttävät jakauman persentiilien poimimiseksi. Tämä luokka on tarkoituksellisen neutraali – sinun tarvitsee vain kytkeä get_metrics päätepisteeksi, jonka Prometheus voi hakea, tai työntää sanakirja Datadogiin.

# Malli vientiin Prometheusiin, Datadogiin jne.
class MetricsExporter:
    "Valvontajärjestelmien kanssa yhteensopiva mittarien viejä."

    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()
# Kutsu exporter.record_success() tai exporter.record_error()
# jokaisen API-kutsun jälkeen

Keskeiset asiat

  • Lokita jokainen kutsu sisältäen: malli, tokenit, viive, tila, response_id
  • Käytä strukturoitua JSON-muotoa lokeille, jotka työkalusi voivat jäsentää
  • Kerää keskeiset mittarit: onnistumisprosentti, p95-viive, tokenien kulutus
  • Lisää trace_id pyyntöjen korreloimiseksi hajautetuissa järjestelmissä
  • Vie mittarit valvontajärjestelmääsi (Prometheus, Datadog jne.)
  • Älä koskaan lokita kehotteen sisältöä tuotannossa (arkaluonteinen data)