Logimine ja jälgitavus
Sellel lehel
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)