Регистриране и наблюдаемост
На тази страница
Регистриране и наблюдаемост
В производствена среда трябва да знаете точно какво се случва с вашите API повиквания: латентност, използвани токени, грешки и разходи. Структурираното регистриране и наблюдаемостта Ви осигуряват тази видимост. Разликата става очевидна в момента, в който потребител съобщи: „Асистентът работи бавно от тази сутрин.“ Без инструментиране, Вие сте принудени да гадаєте. С него можете да видите за тридесет секунди, че латентността p95 се е удвоила след промяна в подкана, която е утроила размера на контекста.
Основно структурирано регистриране
Направете си навик да измервате около повикването, а не вътре в него. Запишете часовника преди, прочетете го отново след това и изведете един ред, описващ цялото събитие. JSON не е просто за показ: той позволява на Вашия агрегатор да филтрира по status, да проследява duration_ms във времето или да търси конкретен response_id – нещо, което свободният текст никога не може да направи. Блокът except генерира точно същата структура, включително типа и съобщението за изключението, след което повторно задейства грешката. Регистрирането не е обработка на грешки.
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!")
Обърнете внимание, че регистрираме prompt_length, а не самата подкана. Това е дизайнерско решение, а не пропуск: дължината е достатъчна за корелация с латентността, без да се изнасят потребителски данни във Вашата система за регистриране.
Междинен софтуер за регистриране
Повтарянето на този блок във всяка функция, която извиква API, гарантира, че някъде ще го пропуснете. По-добре е да обгърнете клиента веднъж завинаги. Класът данни APIMetrics дефинира договора за това какво измерваме, а ObservableClient попълва този запис и го архивира, независимо дали повикването е успешно или не. Методът rapport след това превръща историята в директно приложими метрики – процент на успех, средна латентност, латентност p95.
Последното число е най-важното. Средна стойност от 450 ms може да скрие единия от двадесетте потребители, чакащи три секунди; p95 разкрива това. Чрез сортиране на продължителностите и вземане на стойността на 95-тия перцентил, Вие описвате реалното преживяване на най-зле обслужваните си активни потребители.
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
# }
Проследяване на повиквания с контекст
В разпределена архитектура едно API повикване никога не съществува в изолация: то се задейства от HTTP заявка, която сама по себе си произтича от потребителско действие и понякога е последвана от още две повиквания. trace_id е нишката, която свързва тези събития заедно. Чрез предаването му от Вашия уеб слой – тук user-123-req-456 – можете да реконструирате цяла сесия във Вашите регистри въз основа на една единствена жалба от клиент. Извеждат се два реда: един в началото и един при завършване, което също помага да се открият повиквания, които никога не са върнали отговор.
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]}...")
Бъдете внимателни с prompt_preview: тези първи сто знака отиват директно във Вашите регистри такива, каквито са. Приемливо е в разработка, но го премахнете веднага щом започне потокът от реални данни.
Експортиране към система за мониторинг
Историята в паметта изчезва, когато процесът се рестартира. За да наблюдавате услуга във времето, трябва да изложите метриките към външен инструмент. Универсалният шаблон разчита на две семейства: броячи, които само нарастват и се превръщат в скорости, и хистограми, които запазват разпределение, за да извлекат перцентили. Този клас е умишлено неутрален – трябва само да свържете get_metrics с крайна точка, която Prometheus да сканира, или да изпратите речника към 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
Ключови изводи
- Регистрирайте всяко повикване с: модел, токени, латентност, статус, response_id
- Използвайте структуриран JSON за регистри, които Вашите инструменти могат да анализират
- Събирайте ключови метрики: процент на успех, латентност p95, консумация на токени
- Добавете
trace_id, за да корелирате заявките в разпределени системи - Експортирайте метриките към Вашата система за мониторинг (Prometheus, Datadog и др.)
- Никога не регистрирайте съдържанието на подканите в производствена среда (чувствителни данни)