Plantilla de Monitoreo y Alertas de API

Visión General

Tu API devuelve 200 OK en cada health check mientras la latencia p95 se triplica en silencio y un mal despliegue empuja la tasa de error de 0.02% a 0.8%. Nada “falla” — pero todos los consumidores lo sienten. Por eso los checks de uptime no son monitoreo: los servicios se degradan antes de morir, y la única forma de detectar la degradación es medir los indicadores correctos contra objetivos explícitos.

Esta plantilla codifica ese modelo — el mismo marco SLI/SLO/presupuesto-de-error del libro SRE de Google. Define los indicadores a medir (disponibilidad, latencia, tasa de error, saturación), los objetivos a prometer, los umbrales que despiertan a un humano y los runbooks que le dicen al ingeniero on-call qué hacer después. Documentos relacionados: API Gateway para Microservicios, Patrón Circuit Breaker e Inyección de Dependencias.

Cuándo Usar

Usa este recurso cuando:

• Lanzas una nueva API o versión que necesita garantías de uptime
• Auditas la cobertura de monitoreo existente después de un incidente
• Defines reglas de alerta y políticas de escalamiento para on-call
• Migras de dashboards ad-hoc a alertas guiadas por SLO
• Incorporas una nueva rotación on-call que necesita umbrales y runbooks documentados

Omítela para prototipos que todavía están encontrando su superficie de API — los SLOs prematuros se fijan sobre números que serán incorrectos en un mes. Para alternativas, consulta la Plantilla de Gestión del Ciclo de Vida de API.

Solución

La plantilla de abajo es el documento rellenable que tu equipo produce una vez por API — metadatos, indicadores, objetivos, niveles de alerta, diseño del dashboard y enlaces a runbooks. Cópiala en tu sistema de documentación, reemplaza los <placeholders> y mantenla junto a las reglas de alerta que describe.

# Monitoreo y Alertas de API: `<Nombre de la API>`

## 1. Metadatos del Servicio

| Campo | Valor |
|-------|-------|
| Nombre de API | `nombre` |
| Equipo Responsable | `@team-name` |
| Nivel | `P0 (crítico) / P1 (importante) / P2 (estándar)` |
| Número de Consumidores | Internos: X, Externos: Y |

## 2. SLIs (Indicadores que Medimos)

| SLI | Métrica | Fuente de Datos |
|-----|---------|-----------------|
| Disponibilidad | `% de requests con 2xx/3xx` | Logs de load balancer o gateway |
| Latencia | `p95, p99 de tiempo de respuesta` | APM (Datadog, New Relic) |
| Tasa de Error | `% de respuestas 5xx / total` | Logs de aplicación |
| Throughput | `Requests por minuto` | Servidor de métricas (Prometheus) |
| Saturación | `CPU / Memoria / Conexiones DB` | Métricas de infraestructura |

## 3. SLOs (Objetivos que Prometemos)

| SLO | Objetivo | Ventana de Medición | Alerta de Burn Rate |
|-----|----------|---------------------|---------------------|
| Disponibilidad | 99.9% | 30 días | 2% de presupuesto en 1 hora |
| Latencia p95 | < 200ms | 7 días | 5x normal en 1 hora |
| Tasa de Error | < 0.1% | 30 días | 10% de presupuesto en 1 día |

## 4. Definición de Alertas

### 4.1. Alertas de Página (Despiertan a Alguien)

| Condición | Umbral | Duración | Severidad |
|-----------|--------|----------|-----------|
| Tasa de error > 1% | > 1% | 2 minutos | P1 |
| Latencia p95 > 1s | > 1000ms | 3 minutos | P1 |
| Disponibilidad < 99% | < 99% | 1 minuto | P0 |

### 4.2. Alertas de Advertencia (Ticket / Slack)

| Condición | Umbral | Duración | Acción |
|-----------|--------|----------|--------|
| Tasa de error > 0.1% | > 0.1% | 10 minutos | Crear ticket Jira |
| Latencia p95 > 300ms | > 300ms | 15 minutos | Notificar canal Slack |
| Caída de tráfico > 50% | < 50% baseline | 5 minutos | Página on-call (posible caída) |

### 4.3. Alertas Informativas (Solo Dashboard)

| Condición | Propósito |
|-----------|-----------|
| Throughput > 10x baseline | Detectar tráfico viral o DDoS |
| Tasa de 4xx > 5% | Detectar misconfiguración de clientes |

## 5. Diseño del Dashboard

**Fila 1: Resumen de Salud**
- Gauge de disponibilidad (última 1h, 24h, 7d)
- Heatmap de latencia por endpoint
- Línea de tiempo de tasa de error

**Fila 2: Desglose por Endpoint**
- Top 10 endpoints por latencia
- Top 10 endpoints por tasa de error
- Trazas más lentas (enlazadas a APM)

**Fila 3: Infraestructura**
- CPU y memoria de pods/contenedores
- Pool de conexiones de base de datos
- Profundidad de cola (si es async)

## 6. Enlaces a Runbooks

| Alerta | Runbook |
|--------|---------|
| Pico de tasa de error | `/runbooks/api-error-spike` |
| Degradación de latencia | `/runbooks/api-latency-spike` |
| Caída de tráfico | `/runbooks/api-traffic-drop` |

Explicación

Los SLIs son qué mides, los SLOs son qué tan bueno debe ser, y las alertas son cuándo actuar. La plantilla separa alertas de página (requieren intervención humana) de advertencias (pueden esperar a horario laboral). Las alertas de burn rate detectan violaciones de SLO temprano al rastrear qué tan rápido se consume tu presupuesto de error. Las filas del dashboard agrupan métricas relacionadas para que el ingeniero on-call pueda hacer triaje en menos de 30 segundos.

La clasificación por niveles importa más que los números. Una página significa “un humano debe actuar dentro de la hora” — cualquier cosa menos urgente que pagea igualmente está entrenando a la rotación on-call a ignorar sus teléfonos. Las advertencias acumulan problemas que vale arreglar esta semana: tasas de error elevadas que se autocuraron, latencia acercándose al umbral. Las señales informativas existen para forense — explican el incidente después de que la página dispara, no lo causan. La mayoría de equipos descubre que su presupuesto real de alertas es unas 2-3 páginas por semana; más allá de eso, la calidad de respuesta colapsa sin importar qué tan buenos sean los umbrales.

Matemática del presupuesto de error: un SLO de 99.9% te da 0.1% de requests fallidos — a 1M de requests/mes son 1,000 requests malos, o ~43 minutos de downtime. Un burn rate de 1 significa que agotarás el presupuesto exactamente al final de la ventana; 14.4x significa que se consume en ~2 horas en lugar de 30 días. Por eso el modelo SRE usa dos velocidades de alerta: burn rápido (ventana 1h, 14.4x) pagea inmediatamente, y burn lento (ventana 6h, 6x) crea un ticket.

Elegir los Umbrales

Los números de la plantilla son puntos de partida, no evangelio. Calíbralos contra tres insumos:

1. Primero mide la línea base de tus SLIs. Corre el dashboard durante 2-4 semanas antes de pagear a nadie. Si tu p95 naturalmente se sienta en 250ms, un umbral de 200ms garantiza ruido desde el día uno — pon el umbral de página en ~2x la base, la advertencia en ~1.3x.
2. Ajusta el SLO al dolor del consumidor, no a un número redondo. 99.9% es un default, no un requisito. Una API de reportes interna puede vivir en 99% (7h/mes de presupuesto); una API de pagos puede necesitar 99.95%. Pregunta: ¿a qué tasa de error los consumidores realmente abren tickets? Pon el SLO apenas por encima de esa línea.
3. Elige la duración para matar el flapping. Un pico de error de 1 minuto que se autocura no debería pagear. for: 2m en tasa de error y for: 3m en latencia filtran anomalías de un solo burst sin dejar de detectar incidentes reales en 5 minutos.

Las alertas de burn rate multi-ventana son el refinamiento que la mayoría de plantillas salta: combina una ventana rápida (1h, pagea) con una ventana larga (6h-3d, tickets) para que las fugas lentas — un goteo de error del 0.05% que nunca pica — igualmente aparezcan antes de que el presupuesto mensual muera.

Reglas de Alerta con Prometheus

Define las alertas como código para que queden versionadas y sean revisables — el YAML de abajo implementa el nivel de página de la plantilla más la regla de burn rate rápido. Cada regla lleva una anotación runbook que las herramientas de paging renderizan como enlace, que es lo que hace a la alerta accionable en lugar de solo ruidosa:

groups:
  - name: api_slo_alerts
    rules:
      - alert: HighErrorRate
        expr: |
          (
            sum(rate(http_requests_total{status=~"5.."}[5m]))
            /
            sum(rate(http_requests_total[5m]))
          ) > 0.01
        for: 2m
        labels:
          severity: P1
          team: platform
        annotations:
          summary: "Tasa de error arriba de 1% por 2 minutos"
          runbook: "/runbooks/api-error-spike"

      - alert: HighLatencyP95
        expr: |
          histogram_quantile(0.95, rate(
            http_request_duration_seconds_bucket[5m]
          )) > 1.0
        for: 3m
        labels:
          severity: P1
          team: platform
        annotations:
          summary: "Latencia p95 arriba de 1s por 3 minutos"
          runbook: "/runbooks/api-latency-spike"

      - alert: SLOBurnRateFast
        expr: |
          (
            sum(rate(http_requests_total{status=~"5.."}[1h]))
            /
            sum(rate(http_requests_total[1h]))
          ) > 0.002
        for: 5m
        labels:
          severity: P1
          team: platform
        annotations:
          summary: "Burn rate de SLO excede 2% del presupuesto en 1 hora"
          runbook: "/runbooks/slo-burn-rate"

      - alert: TrafficDrop
        expr: |
          sum(rate(http_requests_total[5m]))
          <
          sum(rate(http_requests_total[5m] offset 1h)) * 0.5
        for: 5m
        labels:
          severity: P1
          team: platform
        annotations:
          summary: "Tráfico cayó 50% comparado con hace 1 hora"
          runbook: "/runbooks/api-traffic-drop"

JSON de Dashboard Grafana

Un panel mínimo de dashboard para rastreo de tasa de error — impórtalo en Dashboards → New → Import y adapta los nombres de métricas a tu instrumentación (el ejemplo asume el naming estándar http_requests_total / http_request_duration_seconds de la mayoría de exporters de OpenTelemetry e ingress):

{
  "dashboard": {
    "title": "Resumen de Monitoreo de API",
    "panels": [
      {
        "title": "Tasa de Error (5xx)",
        "type": "stat",
        "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 },
        "targets": [
          {
            "expr": "sum(rate(http_requests_total{status=~\"5..\"}[5m])) / sum(rate(http_requests_total[5m])) * 100",
            "legendFormat": "Error %"
          }
        ],
        "fieldConfig": {
          "defaults": {
            "unit": "percent",
            "thresholds": {
              "steps": [
                { "value": null, "color": "green" },
                { "value": 0.1, "color": "yellow" },
                { "value": 1, "color": "red" }
              ]
            }
          }
        }
      },
      {
        "title": "Latencia p95 por Endpoint",
        "type": "heatmap",
        "gridPos": { "h": 8, "w": 12, "x": 6, "y": 0 },
        "targets": [
          {
            "expr": "histogram_quantile(0.95, sum by (endpoint, le) (rate(http_request_duration_seconds_bucket[5m]))) * 1000",
            "legendFormat": "{{endpoint}}"
          }
        ],
        "fieldConfig": {
          "defaults": { "unit": "ms" }
        }
      }
    ]
  }
}

Plantilla de Runbook

Cada alerta debe enlazar a un runbook — la página que convierte “algo está mal” en “esto es lo que hay que hacer” a las 3 AM. Un buen runbook asume que el lector está dormido, estresado y nunca vio esta alerta antes. Mantén el triaje bajo 60 segundos, los pasos de mitigación mecánicos y el seguimiento post-incidente explícito. Aquí hay una plantilla mínima:

# Runbook: Pico de Errores de API

## Condición de Alerta
Tasa de error > 1% por 2+ minutos (P1)

## Triaje Rápido (menos de 60 segundos)
1. Revisa el dashboard: ¿qué endpoints están devolviendo 5xx?
2. Revisa despliegues recientes: ¿hubo un release en los últimos 30 minutos?
3. Revisa salud de dependencias: ¿hay servicios upstream caídos?

## Pasos de Mitigación
1. Si un despliegue malo causó el pico, revierte a la versión anterior
2. Si una dependencia está caída, activa el fallback del circuit breaker
3. Si el tráfico es anormal, activa rate limiting en el gateway

## Post-Incidente
1. Presenta un reporte de incidente dentro de 24 horas
2. Agrega la causa raíz a la lista de problemas conocidos
3. Actualiza este runbook con cualquier nuevo paso de mitigación

Despliegue Gradual

No actives todas las alertas el primer día — así es como los equipos se entrenan para ignorar las páginas en un mes. La secuencia que funciona:

1. Semana 1-2: solo medir. Despliega el dashboard y las recording rules, sin alertas. Estás construyendo la línea base contra la que se calibrará cada umbral.
2. Semana 3: SLOs en borrador, activa advertencias. Escribe la tabla de SLOs, obtén el visto bueno del dueño de la API y activa solo el nivel de advertencia — tickets y Slack, nada que pagee.
3. Semana 4-6: ajusta. Vigila el volumen de advertencias. Si alguna regla dispara más de ~3 veces por semana sin acción, el umbral está mal, no el servicio. Ajusta hasta que la señal sea limpia.
4. Semana 6+: activa el paging. Enciende las alertas de página solo después de que el nivel de advertencia haya corrido en silencio. Cada alerta de página lleva su enlace a runbook antes de salir a producción — una alerta sin runbook es un juego de adivinanzas a las 3 AM.

Mantén la plantilla bajo control de versiones junto a las reglas de alerta. Cuando el SLO cambia, las reglas cambian en el mismo commit — el drift entre objetivos documentados y umbrales reales es cómo los equipos terminan “cumpliendo un SLO” que nadie acordó.

Variantes

Los defaults de la plantilla asumen una API de producción estándar con consumidores reales. Ajusta la forma al contexto:

Contexto	Enfoque	Notas
Microservicios internos	SLOs mas bajos, alertas mas simples	99% disponibilidad, alertas solo por Slack
API publica SaaS	SLOs estrictos, paging multi-canal	99.99% disponibilidad, PagerDuty + SMS
Serverless / Lambda	Enfocarse en cold start y concurrencia	Alertar por throttling, no CPU
Event-driven	Alertar por lag y profundidad de DLQ	El lag del consumidor es el equivalente de latencia

Dos ejes más que vale decidir explícitamente. Endpoint individual vs agregado: los caminos críticos (checkout, auth) merecen sus propios SLOs y sus propias alertas — un 99.9% a nivel servicio puede esconder un checkout fallando el 5% de las veces. Horario laboral vs 24/7: una herramienta interna que nadie usa a las 3 AM no necesita paging de madrugada; limita el canal por severidad y horario, no por conveniencia.

Lo que funciona

Las prácticas de abajo son la diferencia entre un sistema de alertas en el que la gente confía y uno que termina muteado:

1. Alertar por sintomas (latencia, errores) no por causas (disco lleno) para reducir ruido
2. Definir cada umbral de alerta basado en burn rate de SLO, no en porcentajes arbitrarios
3. Incluir enlaces a runbooks directamente en los mensajes de alerta
4. Revisar y ajustar umbrales mensualmente; los falsos positivos erosionan la confianza
5. Usar canales diferentes para pagina vs advertencia para que on-call sepa la urgencia inmediatamente
6. Rastrear volumen de alertas por semana para identificar alertas ruidosas que necesitan ajuste
7. Agregar un botón de “alerta de prueba” en tu herramienta de alertas para verificar que el paging funciona end-to-end
8. Escribir las alertas como código (YAML de Prometheus, Terraform) — revisables, versionadas y reproducibles entre entornos
9. Revisar los SLOs trimestralmente con el dueño de la API; los objetivos derivan a medida que cambian el tráfico y la arquitectura

Errores Comunes

Y los modos de fallo que silenciosamente destruyen los sistemas de alertas:

1. Alertar por CPU > 80% sin vincularlo a sintomas que afectan al usuario
2. Establecer el mismo SLO para todas las APIs sin importar su criticidad de negocio
3. Usar latencia promedio en lugar de percentiles (los promedios ocultan outliers)
4. Alertar por errores individuales sin umbral de duracion o tasa
5. Olvidar alertar por caidas de trafico (la ausencia de errores puede significar falla total)
6. No probar la entrega de alertas (rotacion de PagerDuty, webhook de Slack) antes de un incidente
7. Crear alertas sin runbooks, dejando a los ingenieros on-call adivinar pasos de mitigacion

Troubleshooting

• Una alerta que debía disparar nunca lo hizo. Revisa primero la expresión contra las métricas crudas — un label que no coincide (status vs code, un job renombrado) hace que rate() no devuelva nada, que se lee como “cero errores”, no como un error. Después revisa for: — una duración más larga que la vida del incidente se traga por completo las caídas cortas.
• Las alertas disparan constantemente y nadie reacciona. Eso es fatiga de alertas, y la solución es restar, no ajustar. Revisa los últimos 30 días de disparos; todo lo que se resolvió solo o no requirió acción pasa a solo-dashboard. Reserva el paging para condiciones que necesitan un humano dentro de la hora.
• Las páginas llegan pero la entrega por Slack/PagerDuty se rompe en silencio. Los webhooks expiran, las rotaciones terminan, los tokens se revocan. Programa una alerta de prueba sintética semanal — si la prueba no llega a un teléfono, nada más lo hará.
• Las métricas muestran huecos justo cuando ocurren los incidentes. Los targets de scrape muriendo bajo carga es un clásico — tu monitoreo comparte destino con el servicio que observa. Dale a Prometheus su propio margen de capacidad y alerta sobre fallos de scrape como señal de primera clase.
• El p95 se ve bien pero los usuarios igual se quejan. Los percentiles en la ventana equivocada esconden picos cortos — una tormenta de 30 segundos es invisible en un rate() de 5 minutos. Añade un panel de ventana corta (1m) junto a los paneles de SLO, o revisa si el timeout del lado del cliente es menor que tu umbral de p95.
• La alerta de SLO dispara pero el dashboard no muestra nada malo. Desajuste de agregación — la alerta calcula sobre sum(rate()) a través de endpoints mientras el panel desglosa por endpoint. El agregado puede estar en brecha mientras cada línea individual se ve sana; baja al grouping real de la expresión.

Ver también

• Plantilla de Presupuesto de Rendimiento de API — la doc hermana que fija presupuestos de latencia antes de alertar sobre ellos
• Guía de Manejo de Errores de API — cómo deberían verse esas respuestas 5xx cuando las alertas disparan
• Plantilla de Mapa de Dependencias de Servicios — mapea los upstreams antes de escribir alertas de dependencias
• Patrón Circuit Breaker — la mitigación a la que apuntan la mayoría de runbooks
• Libro SRE de Google — Monitoring Distributed Systems — la fuente del modelo SLI/SLO
• Workbook SRE de Google — Alerting on SLOs — matemática de burn rate y alertas multi-ventana
• Prometheus Alerting Rules — referencia de sintaxis de expresiones
• Grafana Alerting — canales de notificación y silencios

Código companion: recursos companion de monitoreo — archivo de reglas Prometheus, JSON de dashboard Grafana y una plantilla de runbook rellenable.