Lokitus ja havainnoitavuus
Tällä sivulla
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_idpyyntöjen korreloimiseksi hajautetuissa järjestelmissä - Vie mittarit valvontajärjestelmääsi (Prometheus, Datadog jne.)
- Älä koskaan lokita kehotteen sisältöä tuotannossa (arkaluonteinen data)