Observabilidad en APIs

Audiencia

Esta guía es para desarrolladores y operadores que quieren entender qué está pasando dentro de sus APIs:

• Desarrolladores backend que construyen APIs y necesitan saber cuándo las cosas fallan
• Ingenieros DevOps responsables de mantener las APIs saludables
• SREs que necesitan responder a incidentes y prevenir futuros
• Líderes técnicos que quieren entender por qué importa la observabilidad
• Cualquiera que haya sido despertado a las 3am y no pudo descifrar qué salió mal

Deberías entender cómo funcionan las APIs REST. Si no, comienza con Cómo Funciona una API REST.

Objetivo

Después de leer esta guía, entenderás:

• Por qué la observabilidad es diferente del monitoreo
• Los tres pilares: logs, métricas y trazas
• Qué medir en tus APIs
• Cómo detectar fallos silenciosos (200 OK que en realidad fallaron)
• Métricas clave que importan: p50, p95, p99, presupuestos de error
• La perspectiva SRE sobre la salud de las APIs

Esta guía construye criterio—la capacidad de saber qué observar y por qué.

1. Por Qué Observar APIs

No puedes arreglar lo que no puedes ver.

La Diferencia Entre Monitoreo y Observabilidad

Monitoreo responde: “¿Está funcionando mi sistema?”

Observabilidad responde: “¿Por qué no está funcionando mi sistema?”

graph TD
    A[Estado del Sistema] --> B{Monitoreo}
    B -->|Verde| C[Todo OK]
    B -->|Rojo| D[Algo está mal]
    D --> E{Observabilidad}
    E --> F[Logs: ¿Qué pasó?]
    E --> G[Métricas: ¿Qué tan mal?]
    E --> H[Trazas: ¿Dónde falló?]
    style C fill:#c8e6c9
    style D fill:#ffccbc

El monitoreo te dice que hay un incendio. La observabilidad te ayuda a encontrar dónde empezó y cómo apagarlo.

Lo Que Pierdes Sin Observabilidad

Sin observabilidad adecuada, estás volando a ciegas:

• Debugging lento: “Revisa los logs” se convierte en una búsqueda de horas
• Problemas no detectados: Los problemas que no disparan alertas pasan desapercibidos
• Señalar culpables: Los equipos se culpan entre sí porque nadie tiene la imagen completa
• Recuperación lenta: El Tiempo Medio de Recuperación (MTTR) aumenta dramáticamente
• Erosión de confianza: Los usuarios descubren problemas antes que tú

El Costo de las Caídas

El tiempo de inactividad de las APIs es costoso:

La observabilidad no es un lujo—es el costo de operar sistemas en producción.

2. Los Tres Pilares de la Observabilidad

La observabilidad descansa sobre tres pilares complementarios: logs, métricas y trazas.

graph LR
    subgraph "Tres Pilares"
        L[Logs
¿Qué pasó?]
        M[Métricas
¿Cuánto?]
        T[Trazas
¿Dónde?]
    end

    L --> O[Observabilidad]
    M --> O
    T --> O

    O --> I[Entendimiento]

    style L fill:#e3f2fd
    style M fill:#fff3e0
    style T fill:#e8f5e9
    style O fill:#f3e5f5

Cada pilar responde preguntas diferentes:

Necesitas los tres. Logs sin métricas carecen de contexto. Métricas sin trazas carecen de especificidad. Trazas sin logs carecen de detalle.

Cómo Trabajan Juntos

Imagina que un usuario reporta: “La API está lenta.”

1. Métricas muestran: la latencia se disparó a las 14:30
2. Trazas revelan: el endpoint lento es /users/search
3. Logs explican: el pool de conexiones a la base de datos estaba agotado

Sin los tres, seguirías adivinando.

3. Logs: La Historia de lo que Pasó

Los logs son registros con marca de tiempo de eventos discretos.

Qué Registrar

Siempre registra:

• Petición recibida (método, ruta, IP del cliente)
• Eventos de autenticación (éxito, fallo, tipo de token)
• Acciones de negocio (usuario creado, pedido realizado, pago procesado)
• Errores y excepciones (con stack traces en desarrollo)
• Petición completada (código de estado, duración)

Nunca registres:

• Contraseñas o credenciales
• Números completos de tarjetas de crédito
• Datos personales (cumplimiento GDPR/CCPA)
• Secretos de API o tokens

Logging Estructurado

No registres cadenas de texto plano. Usa formatos estructurados:

{
  "timestamp": "2026-01-12T14:32:05.123Z",
  "level": "ERROR",
  "service": "user-api",
  "requestId": "abc-123-def",
  "userId": "user_789",
  "action": "authentication",
  "status": "failed",
  "reason": "invalid_token",
  "duration_ms": 45
}

¿Por qué estructurado?

• Búsqueda: Consulta level:ERROR AND service:user-api
• Parseable: Las herramientas pueden agregar y visualizar
• Consistente: Mismo formato en todos los servicios

Niveles de Log

Usa niveles consistentemente:

No abuses de ERROR. Si todo es un error, nada es un error.

El Patrón Request ID

Cada petición debería tener un identificador único:

GET /users/123 HTTP/1.1
X-Request-Id: abc-123-def

Este ID debería aparecer en cada log de esa petición:

{"requestId": "abc-123-def", "message": "Petición recibida"}
{"requestId": "abc-123-def", "message": "Obteniendo usuario de base de datos"}
{"requestId": "abc-123-def", "message": "Respuesta enviada", "status": 200}

Ahora puedes buscar abc-123-def y ver todo el ciclo de vida de la petición.

4. Métricas: Números que Dicen la Verdad

Las métricas son mediciones numéricas recolectadas a lo largo del tiempo.

Qué Medir

Las Cuatro Señales Doradas (de Google SRE):

graph TD
    subgraph "Cuatro Señales Doradas"
        L[Latencia
¿Qué tan rápido?]
        T[Tráfico
¿Cuánto?]
        E[Errores
¿Qué tan roto?]
        S[Saturación
¿Qué tan lleno?]
    end

    L --> H[Salud de la API]
    T --> H
    E --> H
    S --> H

    style L fill:#e3f2fd
    style T fill:#fff3e0
    style E fill:#ffccbc
    style S fill:#e8f5e9

1. Latencia — Cuánto tardan las peticiones.

• Mide peticiones exitosas y fallidas por separado
• Las peticiones que fallan rápido pueden sesgar promedios

2. Tráfico — Demanda sobre tu sistema.

• Peticiones por segundo
• Conexiones concurrentes
• Datos transferidos

3. Errores — Peticiones fallidas.

• Tasa de HTTP 5xx (errores del servidor)
• Tasa de HTTP 4xx (errores del cliente, pero rastrea picos)
• Tipos de error personalizados (fallos de lógica de negocio)

4. Saturación — Qué tan “lleno” está tu servicio.

• Utilización de CPU
• Uso de memoria
• Uso del pool de conexiones a BD
• Profundidad de colas

Entendiendo los Percentiles

Los promedios mienten. Usa percentiles.

Ejemplo: Si p50 = 100ms y p99 = 2000ms, la mayoría de usuarios tienen buena experiencia, pero 1 de cada 100 espera 20 veces más.

Por qué importa el p99:

• Un servicio manejando 1M de peticiones/día
• p99 = 2000ms significa 10,000 usuarios/día tienen experiencia terrible
• Eso es suficiente para perder clientes

Rate, Errors, Duration (RED)

Una alternativa a las Señales Doradas, más simple para APIs:

Ambos frameworks funcionan. Elige uno y sé consistente.

5. Trazas: Siguiendo el Camino de la Petición

Las trazas muestran el viaje de una petición a través de tu sistema.

Qué es Distributed Tracing

Cuando una petición toca múltiples servicios, los logs y métricas muestran cada servicio aislado. Las trazas los conectan.

graph LR
    subgraph "Viaje de una Petición"
        A[API Gateway
5ms] --> B[Servicio Auth
15ms]
        B --> C[Servicio Usuario
120ms]
        C --> D[Base de Datos
95ms]
    end

    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#ffccbc
    style D fill:#e8f5e9

Una traza muestra:

• Tiempo total de petición: 235ms
• Tiempo en cada servicio
• Dónde está el cuello de botella (Servicio Usuario + BD = 215ms)

Estructura de una Traza

• Trace: El viaje completo (una petición)
• Span: Una operación individual dentro de la traza
• Trace ID: Identificador único que conecta todos los spans

Trace ID: trace-xyz-789
├── Span: API Gateway (5ms)
├── Span: Servicio Auth (15ms)
├── Span: Servicio Usuario (120ms)
│   └── Span: Consulta a BD (95ms)
└── Total: 235ms

Cuándo las Trazas Salvan el Día

Sin trazas, debuggear “petición lenta” significa:

1. Revisar logs del API Gateway
2. Revisar logs del Servicio Auth
3. Revisar logs del Servicio Usuario
4. Intentar correlacionar por timestamp
5. Adivinar qué pasó

Con trazas:

1. Buscar trace ID
2. Ver el flujo completo
3. Identificar el cuello de botella inmediatamente

La Conexión del Correlation ID

El patrón correlation ID es fundamental para el tracing:

# Petición inicial
GET /api/users/123 HTTP/1.1
X-Request-Id: abc-123

# Propagado a servicios downstream
GET /auth/validate HTTP/1.1
X-Request-Id: abc-123

# Aparece en consultas a base de datos
-- request_id: abc-123
SELECT * FROM users WHERE id = 123

Cada servicio, cada log, cada consulta a base de datos incluye el mismo ID.

6. Fallos Silenciosos: El 200 OK que Mintió

Los fallos más peligrosos no parecen fallos.

Qué es un Fallo Silencioso

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": false,
  "error": "Procesador de pagos no disponible"
}

La capa HTTP dice “éxito.” La capa de negocio dice “fallo.”

Tu monitoreo ve: 200 OK, ¡todo bien! Tus usuarios ven: “Mi pago no funcionó.”

Por Qué Ocurren los Fallos Silenciosos

1. Manejo de errores demasiado optimista:

# MAL: Capturando todo y retornando éxito
try:
    process_payment()
    return {"status": "success"}
except Exception:
    return {"status": "success", "note": "reintentará después"}  # ¡MAL!

2. Fallos parciales en operaciones batch:

{
  "status": 200,
  "processed": 95,
  "failed": 5,
  "errors": ["item 3 no encontrado", "item 7 inválido"]
}

¿Esto es éxito? El estado HTTP dice que sí. Cinco items dicen que no.

3. Respuestas degradadas:

{
  "user": {
    "id": 123,
    "name": "Alice",
    "preferences": null,
    "recommendations": []
  }
}

El usuario existe, pero el servicio de preferencias estaba caído. ¿Es esto un error?

Detectando Fallos Silenciosos

1. Métricas de negocio, no solo métricas HTTP:

# Métricas HTTP muestran
http_requests_total{status="200"} = 10000

# Métricas de negocio revelan la verdad
payment_success_total = 8500
payment_failed_total = 1500

2. Parsing del cuerpo de respuestas de error:

Monitorea por "success": false o "error" en respuestas 200.

3. Monitoreo de dependencias downstream:

Si el servicio de pagos está caído, los 200s de tu API probablemente son mentiras.

La Solución: Sé Honesto

# NO HAGAS: Fallo silencioso
HTTP/1.1 200 OK
{"success": false, "error": "Pago falló"}

# HAZ: Fallo honesto
HTTP/1.1 502 Bad Gateway
{"error": "Procesador de pagos no disponible"}

Si algo falló, el código de estado debería reflejarlo.

7. Métricas Clave para la Salud de APIs

¿Qué deberías realmente rastrear?

SLIs, SLOs y SLAs

graph TD
    SLI[SLI: Service Level Indicator
Lo que mides] --> SLO[SLO: Service Level Objective
Objetivo al que apuntas]
    SLO --> SLA[SLA: Service Level Agreement
Promesa a los clientes]

    style SLI fill:#e3f2fd
    style SLO fill:#fff3e0
    style SLA fill:#ffccbc

Métricas Esenciales de API

1. Disponibilidad

Disponibilidad = (Peticiones exitosas) / (Peticiones totales)

Objetivo: 99.9% = 8.7 horas de caída/año
Objetivo: 99.99% = 52 minutos de caída/año

2. Tasa de Error

Tasa de Error = (Respuestas 5xx) / (Respuestas totales)

Saludable: < 0.1%
Preocupante: > 1%
Crítico: > 5%

3. Distribución de Latencia

4. Throughput

Peticiones por segundo (RPS)

Conoce tu línea base: 1000 RPS normal
Alerta cuando: < 500 RPS (caída inusual) o > 2000 RPS (pico)

Presupuestos de Error

Un presupuesto de error es el inverso de la disponibilidad:

Si SLO = 99.9% disponibilidad
Presupuesto de error = 0.1% = 43.2 minutos/mes de caída permitida

Cómo usarlo:

• Presupuesto disponible: Despliega nuevas features
• Presupuesto agotado: Enfócate en confiabilidad
• Presupuesto excedido: Todos a estabilidad

graph LR
    A[Presupuesto Error
100%] -->|Deployment| B[Presupuesto: 80%]
    B -->|Incidente| C[Presupuesto: 30%]
    C -->|Otro incidente| D[Presupuesto: 0%]
    D --> E[CONGELAR:
Sin nuevos deploys
Arreglar confiabilidad]

    style A fill:#c8e6c9
    style B fill:#fff9c4
    style C fill:#ffccbc
    style D fill:#ef9a9a
    style E fill:#ef5350

Estrategia de Alertas

No toda métrica necesita una alerta. Alerta sobre:

No alertes sobre:

• Métricas dentro de la varianza normal
• Cosas que se auto-recuperan
• Duplicados del mismo problema

El objetivo: Cada alerta debería requerir acción humana.

Qué Sigue

Esta guía cubrió los fundamentos de la observabilidad de APIs—el por qué y qué observar.

Para temas más profundos como:

• Instrumentar tu código para observabilidad
• Correlacionar eventos entre servicios
• Construir dashboards efectivos
• Runbooks para respuesta a incidentes
• Técnicas avanzadas de diagnóstico

Consulta el próximo curso: Observabilidad efectiva de APIs REST

Términos Relacionados del Vocabulario

Profundiza tu entendimiento:

• Observability - La capacidad de entender el estado del sistema
• Logging - Registrar eventos para debugging
• Metrics - Mediciones numéricas a lo largo del tiempo
• Tracing - Seguir peticiones a través de sistemas
• Correlation ID - Vincular eventos relacionados entre servicios