Observabilidad de APIs LLM: métricas, trazas, logs y coste

La observabilidad de la API LLM es la práctica de convertir cada llamada al modelo en suficiente evidencia estructurada para responder cuatro preguntas de producción:

1. ¿La solicitud se completó correctamente?
2. ¿Cuánto esperó el usuario?
3. ¿Qué consumió y cuánto costó la solicitud?
4. ¿Por qué el sistema eligió ese modelo, reintento o fallback?

La monitorización HTTP ordinaria es necesaria, pero no suficiente. Un 200 OK aún puede contener JSON inválido, una respuesta vacía, una respuesta rechazada, una llamada a herramienta rota o una salida que incumpla el contrato de la aplicación. Una solicitud también puede completarse correctamente tras tres intentos y costar silenciosamente cuatro veces más de lo esperado.

El objetivo práctico no es registrar cada prompt. Es crear un contrato de telemetría pequeño y coherente que conecte los resultados de la aplicación con el modelo, proveedor, ruta, latencia, uso de tokens, reintentos y coste, sin exponer datos del usuario.

Esta guía muestra cómo construir ese contrato con métricas, trazas, registros estructurados, objetivos de nivel de servicio, paneles y alertas.

Qué debe explicar la observabilidad de la API LLM

Un sistema de observabilidad útil permite a un ingeniero de guardia pasar rápidamente de un síntoma a una causa.

La primera regla de diseño es simple: mide el contrato de la aplicación, no solo el contrato de transporte.

Las cinco capas de telemetría

La monitorización de la API LLM se vuelve más sencilla cuando separas cinco capas en lugar de forzar cada señal en un solo panel.

1. Métricas de solicitudes

Las métricas muestran tendencias y alimentan las alertas. Registra contadores e histogramas para:

• Conteo de solicitudes
• Latencia de extremo a extremo
• Tiempo hasta el primer token para respuestas en streaming
• Latencia del proveedor o de la llamada al modelo
• Solicitudes correctas, fallidas, canceladas y agotadas por tiempo
• Respuestas HTTP 429 y 5xx
• Intentos de reintento y fallback
• Tokens de entrada, salida y cacheados
• Coste estimado y conciliado

Las métricas deben tener etiquetas acotadas. Las buenas etiquetas incluyen provider, model, route, environment, status y error_type. Evita etiquetas de alta cardinalidad como IDs de usuario, IDs de solicitud, texto del prompt o URLs completas.

2. Trazas distribuidas

Una traza explica el recorrido de una solicitud a través de tu API, cola, capa de recuperación, llamadas a herramientas, gateway y proveedor del modelo.

Una jerarquía práctica de trazas se ve así:

POST /support/reply
├── retrieve_customer_context
├── llm.route
│   ├── llm.attempt provider_a/model_primary
│   └── llm.attempt provider_b/model_fallback
├── validate_structured_output
└── persist_draft

Cada intento de modelo debe ser su propio span. Si se prueban dos proveedores, la traza debe mostrar dos intentos en lugar de ocultarlos ambos dentro de un span opaco llm.call.

Las convenciones semánticas de IA generativa de OpenTelemetry proporcionan un vocabulario compartido útil para spans, métricas y eventos de IA generativa. Trata la versión de la convención como parte de tu esquema de telemetría para que puedas migrar de forma deliberada cuando evolucionen los atributos.

3. Logs estructurados

Los logs capturan decisiones discretas y contexto de diagnóstico que serían demasiado costosos o demasiado detallados como etiquetas de métricas.

Los eventos útiles incluyen:

• llm.request.started
• llm.route.selected
• llm.retry.scheduled
• llm.fallback.selected
• llm.response.validated
• llm.request.completed
• llm.request.failed

Cada evento debe incluir los mismos campos de correlación: request_id, trace_id, route, model, provider, prompt_version y attempt.

4. Señales de calidad y contrato

La calidad no puede inferirse a partir de los códigos de estado. Añade validadores deterministas siempre que sea posible:

• JSON analizado correctamente
• Los campos de esquema requeridos existen
• El nombre de la herramienta y los argumentos están permitidos
• La lista de citas está presente cuando se requiere
• La longitud de salida está dentro de los límites del producto
• Se reconoce el estado de rechazo o de seguridad
• Las comprobaciones de reglas de negocio se superan

Para tareas subjetivas, adjunta más adelante resultados de evaluación muestreados. Mantén la telemetría de solicitudes en línea y la evaluación fuera de línea unidas mediante un request o sample ID estable.

Antes de reemplazar un modelo de producción, utiliza un flujo de trabajo de evaluación de modelos de IA repetible en lugar de confiar solo en la latencia agregada y el precio por token.

5. Coste y resultados de negocio

Los recuentos de tokens son señales de uso, no resultados de negocio. Conecta el uso del modelo con la unidad que le importa a tu producto:

• Coste por respuesta de soporte aceptada
• Coste por tarea de programación completada
• Coste por imagen de producto generada aprobada por un revisor
• Coste por lead cualificado enriquecido
• Coste por extracción estructurada exitosa

La fórmula más útil es:

coste efectivo por tarea aceptada = coste total del modelo / tareas aceptadas

Esto expone los falsos ahorros. Un modelo más barato que provoque más reintentos, fallos de validación o retrabajo humano puede aumentar el coste efectivo.

Un contrato mínimo de telemetría para cada llamada al modelo

Empieza con un esquema de eventos versionado. Los nombres exactos de los campos pueden seguir tu stack de observabilidad, pero los conceptos deben permanecer estables.

{
  "schema_version": "llm-observability.v1",
  "timestamp": "2026-07-30T09:00:00Z",
  "request_id": "req_internal_01",
  "trace_id": "7c4b...",
  "environment": "production",
  "feature": "support_reply",
  "route": "support-default",
  "provider": "provider-a",
  "model": "model-primary",
  "prompt_version": "support-reply-v12",
  "attempt": 1,
  "stream": true,
  "status": "success",
  "http_status": 200,
  "latency_ms": 1840,
  "time_to_first_token_ms": 410,
  "input_tokens": 1640,
  "output_tokens": 284,
  "cached_input_tokens": 900,
  "estimated_cost_usd": 0.0068,
  "validator": "passed",
  "fallback_reason": null,
  "provider_request_id": "redacted-or-scoped-value"
}

No conviertas los prompts y respuestas en bruto en campos obligatorios. Guárdalos solo cuando exista una necesidad definida, una política de retención aprobada, controles de acceso adecuados y una vía de redacción segura.

Métricas que deben estar en el primer panel

No empieces con 40 paneles. Crea un único panel operativo que responda si los usuarios están recibiendo resultados válidos dentro del presupuesto de latencia y coste.

Tráfico y éxito

• Solicitudes por minuto
• Tasa de éxito de transporte
• Tasa de éxito validado
• Tasa de cancelación
• Tasa de tiempo de espera agotado
• Relación de amplificación de reintentos
• Tasa de fallback

Tasa de éxito validado debería ser la señal principal de disponibilidad:

tasa de éxito validado = solicitudes que superan el contrato de la aplicación / solicitudes elegibles

Esto es más estricto y más útil que respuestas 2xx / solicitudes.

Latencia

Haz seguimiento de distribuciones en lugar de promedios:

• Latencia p50, p95 y p99 de extremo a extremo
• Latencia p50, p95 y p99 de la llamada al proveedor
• Tiempo hasta el primer token p50 y p95
• Espera en cola p95
• Ejecución de herramientas p95
• Duración de validación p95

Separa las rutas con streaming y sin streaming. Una solicitud con streaming puede parecer receptiva con un buen tiempo hasta el primer token incluso cuando el tiempo total de finalización es largo.

Fiabilidad

• Tasa de 429 por proveedor y modelo
• Tasa de 5xx por proveedor y modelo
• Tasa de error de red
• Tasa de respuestas mal formadas o con esquema no válido
• Tasa de fallo de llamadas a herramientas
• Estado abierto del circuit breaker
• Tasa de agotamiento del presupuesto de reintentos

Si los límites de tasa son una causa frecuente, usa una estrategia de reintento para LLM limitada para RPM y TPM en lugar de reintentos descoordinados en cada worker de la aplicación.

Uso y coste

• Tokens de entrada y salida por función
• Tokens por tarea aceptada
• Coste estimado por solicitud
• Coste por tarea aceptada
• Coste de reintentos
• Delta de coste de fallback
• Gasto diario frente al presupuesto
• Estimación de coste frente a la factura del proveedor o la exportación de uso

Mantén tanto estimated_cost como reconciled_cost. El primero permite la supervisión casi en tiempo real; el segundo corrige las estimaciones después de que llegan los datos de facturación autorizados.

Cómo rastrear los reintentos y el enrutamiento de reserva

Los reintentos y las reservas son donde normalmente falla la supervisión básica. Si todos los intentos comparten un solo campo de estado, una solicitud costosa y degradada puede parecer saludable.

Registra estos campos para cada intento:

Un playbook de enrutamiento de reserva para APIs LLM de producción debe definir la política de decisión. La observabilidad debería demostrar después que el enrutador la siguió.

Patrón de instrumentación en TypeScript

El siguiente ejemplo mantiene la telemetría independiente de un SDK de modelo específico. Registra un span padre de ruta y un span hijo para cada intento.

import { context, SpanStatusCode, trace } from "@opentelemetry/api";

const tracer = trace.getTracer("ai-gateway");

type ModelAttempt = {
  provider: string;
  model: string;
  reason: "primary" | "retry" | "fallback";
};

export async function runModelRoute(
  attempts: ModelAttempt[],
  callModel: (attempt: ModelAttempt) => Promise<{
    text: string;
    usage?: { inputTokens?: number; outputTokens?: number };
    providerRequestId?: string;
  }>,
) {
  return tracer.startActiveSpan("llm.route", async (routeSpan) => {
    routeSpan.setAttribute("app.llm.route", "support-default");
    routeSpan.setAttribute("app.llm.attempt_limit", attempts.length);

    try {
      for (const [index, attempt] of attempts.entries()) {
        const result = await tracer.startActiveSpan(
          "llm.attempt",
          { attributes: {
            "gen_ai.system": attempt.provider,
            "gen_ai.request.model": attempt.model,
            "app.llm.attempt": index + 1,
            "app.llm.reason": attempt.reason,
          } },
          context.active(),
          async (attemptSpan) => {
            const startedAt = performance.now();

            try {
              const response = await callModel(attempt);
              const valid = response.text.trim().length > 0;

              attemptSpan.setAttribute("app.llm.validated", valid);
              attemptSpan.setAttribute(
                "gen_ai.usage.input_tokens",
                response.usage?.inputTokens ?? 0,
              );
              attemptSpan.setAttribute(
                "gen_ai.usage.output_tokens",
                response.usage?.outputTokens ?? 0,
              );
              attemptSpan.setAttribute(
                "app.llm.latency_ms",
                performance.now() - startedAt,
              );

              if (!valid) {
                throw new Error("response_validation_failed");
              }

              attemptSpan.setStatus({ code: SpanStatusCode.OK });
              return response;
            } catch (error) {
              attemptSpan.recordException(error as Error);
              attemptSpan.setStatus({
                code: SpanStatusCode.ERROR,
                message: (error as Error).message,
              });
              return null;
            } finally {
              attemptSpan.end();
            }
          },
        );

        if (result) {
          routeSpan.setAttribute("app.llm.selected_attempt", index + 1);
          routeSpan.setStatus({ code: SpanStatusCode.OK });
          return result;
        }
      }

      throw new Error("llm_route_exhausted");
    } catch (error) {
      routeSpan.recordException(error as Error);
      routeSpan.setStatus({
        code: SpanStatusCode.ERROR,
        message: (error as Error).message,
      });
      throw error;
    } finally {
      routeSpan.end();
    }
  });
}

En producción, añade tus contadores de métricas y eventos de registro estructurados junto a las trazas. Captura también los identificadores de solicitud del proveedor cuando estén disponibles; suelen ser esenciales al escalar un incidente a un proveedor de modelos. Mantén esos identificadores fuera de los mensajes de error públicos.

Logs sin filtración del prompt

La opción predeterminada más segura es registrar primero los metadatos.

Registrar por defecto

• IDs internos de solicitud y de trazas
• ID de solicitud del proveedor
• Nombre de la funcionalidad y de la ruta
• Proveedor, modelo y alias de despliegue
• Versión de la plantilla de prompt
• Parámetros como la temperatura y el máximo de tokens de salida
• Uso de tokens
• Latencia y tiempo hasta el primer token
• Clase de error y decisión de reintento
• Resultado del validador
• Nombres de herramientas desinfectados

No registrar por defecto

• Prompts o respuestas sin procesar
• Claves API o encabezados de autorización
• Secretos de clientes
• Documentos recuperados
• Argumentos de herramientas que contengan datos personales o regulados
• Rutas completas de archivos o registros de bases de datos
• URLs firmadas

Cuando sea necesario capturar contenido para depuración o evaluación, muéstrelo por separado, elimine o enmascare datos sensibles antes de almacenarlo, restrinja el acceso, encríptelo y establezca un periodo de retención corto. La guía de gestión segura de claves API cubre los controles adyacentes para secretos, registro, rotación y respuesta a incidentes.

SLOs para funcionalidades basadas en LLM

Un objetivo de nivel de servicio de LLM debe describir la funcionalidad visible para el usuario, no la cuenta del proveedor.

Ejemplos de SLO para una funcionalidad estructurada de respuesta de soporte:

Estas cifras son ejemplos, no objetivos universales. Defínalas a partir de las expectativas del usuario, la complejidad de la tarea, el comportamiento del proveedor y la economía unitaria.

Use los presupuestos de error para decidir cuándo ralentizar los lanzamientos de funcionalidades, endurecer la política de rutas o desviar el tráfico. Un proveedor puede cumplir su propio objetivo de disponibilidad mientras su producto no alcanza su SLO porque la cola, las herramientas, la validación o el comportamiento de fallback añaden fallos.

Alerta sobre síntomas, diagnóstico con causas

Envíe una alerta a un operador por impacto en el usuario. Use alertas de menor severidad o anotaciones en el panel para las causas probables.

Síntomas que merecen alerta inmediata

• La tasa de éxito validado incumple el SLO
• El p95 del tiempo hasta el primer token supera el umbral visible para el usuario
• Aumenta bruscamente la tasa de rutas agotadas
• El coste por tarea aceptada supera el límite
• Una funcionalidad crítica no tiene un objetivo compatible con el contrato y saludable

Señales diagnósticas

• La tasa de 429 de un proveedor aumenta
• Cambia la tasa de fallos de esquema de un modelo
• Aumenta la amplificación de reintentos
• Crece el tiempo de espera en cola
• Se abre el disyuntor
• El uso de tokens cambia después de una versión del prompt

Evite alertar por cada 5xx del proveedor. Si el fallback funciona y los usuarios siguen recibiendo respuestas válidas dentro del presupuesto de latencia, el evento puede requerir investigación sin despertar al ingeniero de guardia.

Un modelo operativo de tres paneles

Panel 1: Experiencia de usuario

Muestre la disponibilidad validada, la latencia, el tiempo hasta el primer token, la finalización de tareas y los errores visibles para el usuario por funcionalidad.

Dashboard 2: Routing y proveedores

Muestra la cuota de tráfico, errores del proveedor, reintentos, fallbacks, circuit breakers, agotamiento de rutas y latencia por modelo y destino.

Dashboard 3: Uso y economía

Muestra tokens, gasto estimado, gasto conciliado, coste por tarea aceptada, variación frente al presupuesto y las principales funcionalidades por coste.

Mantén las anotaciones de despliegue y de versión de prompt en los tres. De lo contrario, una regresión que comienza inmediatamente después de una release puede parecer una variación aleatoria del proveedor.

Lista de verificación para el despliegue

1. Define un esquema de eventos versionado.
2. Genera un ID interno de solicitud en el límite del producto.
3. Propaga el contexto de trazas a través de colas, herramientas y llamadas al modelo.
4. Crea un span hijo para cada intento del modelo.
5. Registra los IDs de solicitud del proveedor cuando se devuelvan.
6. Añade validación determinista de la salida.
7. Realiza un seguimiento explícito de los motivos de reintento y fallback.
8. Calcula el coste estimado a partir de una tabla de precios versionada.
9. Concilia las estimaciones con exportaciones autorizadas de uso o facturación.
10. Construye primero un dashboard de resultados de usuario antes que dashboards de proveedores.
11. Define un SLO para éxito validado y latencia.
12. Anonimiza o excluye prompts, respuestas, secretos y datos sensibles de herramientas.
13. Ejecuta pruebas de fallo para timeout, 429, 5xx, salida malformada y agotamiento de rutas.
14. Revisa la cardinalidad de las etiquetas antes de habilitar métricas en producción.
15. Muestrea las trazas por riesgo: conserva con mayor peso los errores y las solicitudes lentas que los éxitos rutinarios.

Errores comunes de observabilidad

Tratar cada 200 como éxito

Añade validadores de contrato e informa del éxito validado por separado.

Registrar prompts sin procesar para cada solicitud

Esto genera problemas de privacidad, seguridad, retención y coste. Es preferible usar metadatos y un muestreo controlado.

Ocultar los reintentos dentro de una sola duración

Crea un span y un evento por intento para que los operadores puedan ver la amplificación.

Usar los nombres de modelo como única identidad de ruta

Realiza un seguimiento del proveedor, el alias de despliegue o cuenta, la región y la política de ruta. El mismo modelo puede comportarse de forma diferente según el destino.

Alertar sobre la latencia media

Las medias ocultan los problemas de la cola. Usa p95 y p99, y separa el tiempo hasta el primer token del tiempo total de finalización.

Confiar eternamente en el coste estimado

Las tablas de precios, el tratamiento de la caché y la contabilidad del proveedor pueden cambiar. Concilia las estimaciones con los datos de facturación y registra la versión de la tabla de precios.

Permitir que las etiquetas de telemetría crezcan sin límites

Los IDs de solicitud y los identificadores de cliente pertenecen a las trazas o los logs, no a las etiquetas de métricas.

Dónde ayuda una API gateway de IA

Las aplicaciones con múltiples proveedores, de otro modo, necesitan adaptadores separados para autenticación, nombres de modelo, reintentos, campos de uso, errores y exportaciones de facturación. Una gateway puede reducir esa superficie de integración al ofrecer a la aplicación un límite de API estable, preservando al mismo tiempo los detalles del proveedor y del modelo en la telemetría interna.

Flatkey proporciona una sola clave de API, un endpoint compatible con OpenAI y acceso a modelos de los principales proveedores. Eso permite centralizar el contrato de telemetría del lado de la aplicación incluso cuando las cargas de trabajo usan distintos modelos de texto, imagen o vídeo. La gateway no sustituye la observabilidad a nivel de producto: tu aplicación debe seguir registrando la funcionalidad, la versión del prompt, el resultado de validación, la latencia visible para el usuario y el resultado de tarea aceptada.

Si tu equipo está consolidando proveedores, empieza con la guía de arquitectura de gateway de API de IA, y luego añade el contrato de telemetría de este artículo antes de mover tráfico de producción.

Preguntas frecuentes

¿Qué es la observabilidad de APIs LLM?

La observabilidad de APIs LLM es la recopilación y correlación de métricas, trazas, logs, comprobaciones de calidad, uso y datos de coste para funciones impulsadas por modelos. Explica tanto el comportamiento del proveedor como si la aplicación devolvió un resultado válido para el usuario.

¿Qué debo monitorizar para una API LLM?

Monitoriza la tasa de éxito validado, la latencia de extremo a extremo, el tiempo hasta el primer token, la latencia del proveedor, las tasas de 429 y 5xx, los reintentos, los fallbacks, el uso de tokens, el coste estimado, el coste por tarea aceptada y los fallos del contrato de salida.

¿Deben almacenarse los prompts y las respuestas en las trazas?

No por defecto. Almacena primero los metadatos. Captura el contenido solo con un propósito definido de depuración o evaluación, con redacción, controles de acceso, cifrado, muestreo y una política de retención.

¿Cuál es la diferencia entre monitorización de LLM y observabilidad de LLM?

La monitorización te dice que una métrica conocida ha superado un umbral. La observabilidad te proporciona suficientes evidencias correlacionadas para investigar nuevos modos de fallo en toda la aplicación, la ruta, el proveedor, el modelo, las herramientas y el contrato de salida.

¿Cómo calculo el coste por solicitud de un LLM?

Multiplica las unidades facturables de entrada, salida, entrada en caché, medios u otras unidades de uso por una tabla de precios versionada y luego añade el coste de los reintentos y de los intentos de fallback. Reconcili la estimación con los datos de facturación del proveedor o del gateway.

¿Qué ID de solicitud debo almacenar?

Crea tu propio ID interno de solicitud y tu ID de trazabilidad, y luego almacena también el ID de solicitud del proveedor cuando la API devuelva uno. Los IDs internos conectan tus sistemas; el ID del proveedor ayuda con el soporte externo y la escalada de incidencias.

Construye el contrato de telemetría antes del incidente

El mejor momento para decidir qué debe registrar una llamada al modelo es antes de que llegue tráfico de producción. Empieza con el éxito validado, distribuciones de latencia, un span por intento, etiquetas de métricas acotadas, logs con metadatos primero y coste por tarea aceptada. Luego prueba el sistema forzando los fallos que esperas que el enrutador tenga que manejar.

Esa base convierte un informe vago: “la función de IA es lenta y cara” en una decisión trazable: qué función, qué ruta, qué modelo, qué intento, qué fallo, cuánto retraso y cuánto coste.

Explora los precios de Flatkey cuando estés listo para comparar rutas multmodelo detrás de una sola API compatible con OpenAI.