Registro y observabilidad
En esta página
Registro y observabilidad
En producción, necesitas saber exactamente qué ocurre con tus llamadas a la API: latencia, tokens consumidos, errores y costes. El registro estructurado y la observabilidad te proporcionan esa visibilidad. La diferencia se hace evidente en el momento en que un usuario informa: «El asistente va lento desde esta mañana». Sin instrumentación, te quedas especulando. Con ella, puedes ver en treinta segundos que la latencia p95 se ha duplicado tras un cambio en el prompt que triplicó el tamaño del contexto.
Registro estructurado básico
Acostúmbrate a medir alrededor de la llamada, no dentro de ella. Lee el reloj antes, léelo de nuevo después y emite una única línea que describa todo el evento. JSON no es solo para quedar bien: permite que tu agregador filtre por status, rastree duration_ms a lo largo del tiempo o busque un response_id específico, algo que el texto libre nunca podrá hacer. El bloque except genera exactamente la misma estructura, incluyendo el tipo y el mensaje de la excepción, y luego vuelve a lanzarla. Registrar no es gestionar.
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:
"""Llamada a la API con registro estructurado completo."""
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!")
Fíjate en que registramos prompt_length, no el prompt en sí. Es una decisión de diseño, no un descuido: la longitud basta para correlacionar con la latencia, sin exportar datos de usuario a tu sistema de registro.
Middleware de registro
Repetir este bloque en cada función que llame a la API garantiza que lo olvidarás en algún sitio. Es mejor envolver el cliente de una vez por todas. La clase de datos APIMetrics define el contrato de lo que medimos, y ObservableClient rellena ese registro y lo archiva, tanto si la llamada tiene éxito como si falla. El método rapport convierte entonces el historial en métricas directamente accionables: tasa de éxito, latencia media, latencia p95.
Ese último número es el más importante. Una media de 450 ms puede ocultar al uno de cada veinte usuarios que espera tres segundos; p95 lo revela. Al ordenar las duraciones y tomar el valor en el percentil 95, describes la experiencia real de tus usuarios activos peor atendidos.
from dataclasses import dataclass, field
from typing import Optional
import time
import json
@dataclass
class APIMetrics:
"""Métricas recogidas para cada llamada."""
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:
"""Cliente de OpenAI con observabilidad integrada."""
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:
"""Genera un informe de las métricas recogidas."""
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)],
}
# Uso
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))
# Resultado:
# {
# "total_appels": 3,
# "erreurs": 0,
# "taux_succes": "100.0%",
# "total_tokens": 95,
# "latence_moyenne_ms": 450,
# "latence_p95_ms": 520
# }
Trazado de llamadas con contexto
En una arquitectura distribuida, una llamada a la API nunca existe de forma aislada: la desencadena una petición HTTP, que a su vez proviene de una acción de usuario, y a veces va seguida de dos llamadas más. El trace_id es el hilo que une estos eventos. Al propagarlo desde tu capa web —aquí user-123-req-456— puedes reconstruir una sesión entera en tus registros a partir de una única queja de cliente. Se emiten dos líneas, una al inicio y otra al finalizar, lo que también ayuda a detectar llamadas que nunca respondieron.
import uuid
class TracingClient:
"""Cliente con trazado para correlacionar peticiones."""
def __init__(self):
self.client = OpenAI()
def create_with_trace(self, prompt: str, trace_id: str = None,
**kwargs) -> tuple:
"""Llamada con trace_id para correlación."""
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
# Uso con trace_id para correlacionar en los registros
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]}...")
Ten cuidado con prompt_preview: esos cien primeros caracteres van directos a tus registros tal cual. Es aceptable en desarrollo, pero elimínalo en cuanto empiece a fluir datos reales.
Exportación a un sistema de monitorización
Un historial en memoria desaparece al reiniciar el proceso. Para monitorizar un servicio a lo largo del tiempo, necesitas exponer métricas a una herramienta externa. El patrón universal se basa en dos familias: contadores, que solo aumentan y se derivan en tasas, e histogramas, que conservan una distribución para extraer percentiles. Esta clase es intencionadamente neutra: solo tienes que conectar get_metrics a un endpoint para que Prometheus lo sondee, o empujar el diccionario a Datadog.
# Patrón para exportar a Prometheus, Datadog, etc.
class MetricsExporter:
"""Exportador de métricas compatible con sistemas de monitorización."""
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()
# Llama a exporter.record_success() o exporter.record_error()
# después de cada llamada a la API
Puntos clave
- Registra cada llamada con: modelo, tokens, latencia, estado, response_id
- Usa JSON estructurado para que tus herramientas puedan analizar los registros
- Recoge métricas clave: tasa de éxito, latencia p95, consumo de tokens
- Añade un
trace_idpara correlacionar peticiones en sistemas distribuidos - Exporta métricas a tu sistema de monitorización (Prometheus, Datadog, etc.)
- Nunca registres el contenido del prompt en producción (datos sensibles)