Gestión de incidentes y ciclo operativo

1. Qué es un incidente en el mundo de ChatGPT Apps

En la web clásica, un incidente suele ser algo como «el servidor está caído», «los errores 500 aumentaron mucho», «la latencia se duplicó». Definición formal de ITIL: un incidente es una interrupción no planificada del servicio o una degradación de la calidad del servicio.

En el mundo de ChatGPT Apps y GiftGenius el panorama es más complejo. Aparece una capa de modelos que pueden:

• no invocar la herramienta necesaria, aunque todo esté disponible;
• invocar la herramienta con parámetros incorrectos;
• «alucinar» el resultado, ignorando tu MCP.

Por eso un incidente puede no ser solo un HTTP 500, sino también la situación en la que todas las métricas de backend están en verde y, aun así, los usuarios se quejan masivamente: «el bot está tonto y no muestra regalos», porque el modelo dejó de llamar a suggest_gifts o confunde los argumentos. Esto es un incidente de calidad (Quality incident).

Es útil pensar los incidentes por categorías:

Un incidente es el momento en el que la métrica real se sale de los límites del SLO acordado de antemano. Por ejemplo:

• acordamos: p95 de la selección de regalos < 4 segundos. Pasó a 9 segundos;
• queremos que el 99 % de los checkouts a la semana sea satisfactorio, y pasó a 94 %;
• esperamos que en los flujos con compra el modelo casi siempre llame a create_checkout_session, y en los logs vemos un aumento brusco de «omisiones».

Importante: un incidente no es «alguien se quejó en el chat». La queja es un disparador, y la decisión «sí, es un incidente» la tomamos basándonos en SLO/SLI y dashboards.

2. Cómo los SLO/SLI se convierten en incidentes

En el módulo sobre observabilidad ya definiste las métricas clave: latencia, disponibilidad, tasa de error y éxito del checkout. Ahora las usamos como «guardias en la puerta».

El escenario más sencillo: tenemos un SLO sobre checkout_success_rate. Mantenemos logs estructurados de eventos:

// Ejemplo de evento de log de checkout en el servidor MCP
logger.info({
  event: 'checkout_result',
  request_id,
  user_id,
  checkout_session_id,
  status: 'success', // o 'failed'
  error_code: null,
});

Sobre estos logs se construye una métrica: proporción de status = "success" entre todos los checkout_result de los últimos N minutos/horas. Cuando esta proporción baja del umbral (por ejemplo, 95 % en 10 minutos), el sistema de monitorización envía una alerta al canal de on‑call. Esta es la detección del incidente: el SLI se salió del SLO.

Del mismo modo pueden dispararse alertas por:

• incremento del error_rate de las herramientas suggest_gifts, search_products;
• aumento del p95/p99 de latencia;
• caída anómala del número de workflow_completed (la gente no llega al final del flujo);
• aumento anómalo del coste de LLM sin incremento del tráfico (incidente económico).

Todo esto es posible solo porque registramos logs de forma estructurada, y no escribimos en los logs «algo va mal con el checkout». Cuando las métricas y alertas están configuradas, aprendemos a notar que algo va mal. La siguiente pregunta: ¿qué pasa después de la detección, quién y cómo reacciona?

3. Ciclo de vida del incidente: de la detección al post‑mortem

Para no vivir en modo incendio eterno, conviene describir un pipeline estándar del incidente. Muchos equipos SRE lo formalizan como una cadena:

flowchart TD
    D["Detection (detección)"] --> T["Triage (evaluación de gravedad)"]
    T --> M["Mitigation (contención rápida)"]
    M --> R["Resolution (corrección definitiva)"]
    R --> P["Post-mortem (análisis y mejoras)"]

Analicemos las etapas con el ejemplo de GiftGenius.

Detection — cómo entender que todo va mal

La detección del problema puede ser automática o manual.

Automática — alertas del sistema de monitorización basadas en SLO/SLI:

• PagerDuty / Opsgenie / correo / un bot de Slack avisa: SEV-1: checkout_success_rate < 60 % en 10 minutos;
• alerta por latencia: p95(suggest_gifts) > 10 s;
• anomalía de coste: «los costes de LLM se duplicaron con el mismo número de workflow_completed».

Detección manual — cuando a soporte (o a ti personalmente por Telegram) te llega una avalancha de mensajes «el pago no pasa», «el widget gira infinitamente». A veces esto pone de relieve el problema antes de que la monitorización lo alcance.

Conclusión práctica: incluso si aún no tienes una monitorización perfecta, acostúmbrate a mirar cualquier queja masiva de usuarios a través del prisma de las métricas: «¿qué métrica hay detrás y cómo la medimos?».

Triage — clasificación y priorización

Tras la detección hay que responder a dos preguntas: qué tan grave es y quién se pondrá a arreglarlo.

Conviene tener una escala simple de severidad:

• SEV-1: crítico — los usuarios no pueden comprar, la App no funciona en el flujo clave (por ejemplo, checkout=0 con tráfico activo).
• SEV-2: grave, pero con degradación — parte de los usuarios no puede completar el flujo, la latencia aumentó mucho, pero no hasta detenerse.
• SEV-3: bugs menores — una de las herramientas adicionales a veces falla, solo se rompe un caso límite (edge case).

Para GiftGenius los incidentes de commerce casi siempre son SEV-1: si el dinero no fluye, no es solo un problema técnico, es un daño directo a los ingresos y a la confianza.

En este paso también se asigna el on‑call (o tú mismo, si el equipo es de una persona) y se toma la decisión: «Sí, este es un incidente oficial SEV‑1, trabajamos según el runbook N» (un runbook es una instrucción paso a paso descrita de antemano; veremos la estructura en una sección aparte).

Mitigation — detener la «hemorragia»

La mitigación no es buscar la causa raíz, sino tomar medidas rápidas para que los usuarios sufran menos. Ejemplos:

• hacer rollback de la última release de MCP/Agents/ACP;
• desactivar el feature flag problemático;
• pasar GiftGenius a modo de «solo visualización»: mostramos recomendaciones, pero no permitimos comprar;
• reducir temporalmente la carga (rate limiting) u desactivar herramientas pesadas.

Ejemplo típico de código para un «modo degradado» en nuestro MCP:

// Pseudocódigo: flag global que se puede cambiar rápidamente
let checkoutDisabled = false;

export function setCheckoutDisabled(value: boolean) {
  checkoutDisabled = value;
}

export async function createCheckoutSession(args: CheckoutArgs) {
  if (checkoutDisabled) {
    // Informamos al modelo que el pago no está disponible temporalmente
    return {
      error: 'checkout_temporarily_disabled',
      message: 'El pago no está disponible temporalmente; muestra una explicación al usuario.',
    };
  }

  // lógica habitual de creación de la sesión
}

En el sistema de feature flags puedes activar setCheckoutDisabled(true) como parte de la mitigación: al menos los usuarios no recibirán 500s ni pagos colgados, sino un mensaje honesto.

Resolution — corrección definitiva

Cuando has «detenido la hemorragia», tienes tiempo para encontrar la causa raíz y corregirla:

• bug en el código de MCP/ACP;
• problema con un proveedor externo (Stripe, pasarela de pago);
• límites del OpenAI API (429, sobrecarga);
• prompt roto o cambio de modelo que dejó de invocar la herramienta.

La resolución suele incluir:

• fix (patch/rollback/config);
• deploy a staging y luego a producción;
• verificación de todos los SLI/SLO;
• devolver los flags a su estado normal.

Post-mortem — aprender de los errores

Tras un incidente, especialmente SEV‑1/SEV‑2, se realiza un post‑mortem: un documento donde respondes con honestidad a:

• qué ocurrió (hechos y línea temporal);
• cómo se detectó;
• cómo se reaccionó;
• qué funcionó bien y qué no;
• qué cambios harás para que no se repita.

El post‑mortem no va de buscar culpables, sino de mejorar el sistema y el proceso. Sobre su base se actualizan runbooks, alertas e incluso, a veces, la arquitectura.

4. Roles y responsabilidad: incluso si eres «uno en el campo»

Para que el pipeline de incidentes descrito funcione en la vida real, es importante acordar de antemano quién decide qué durante el incendio. Aunque tu equipo quepa en un ascensor, tiene sentido formalizar los roles ante incidentes. Esto reduce el caos.

Normalmente se distinguen:

• Ingeniero on-call — a quien le llega primero la alerta y quien toma decisiones técnicas para estabilizar (rollback, feature flags, parches temporales).
• Incident commander — la persona que lleva el proceso: fija la línea temporal, prioriza tareas y evita que el equipo vaya dando tumbos. En un microequipo es el mismo on‑call, pero con otro «sombrero».
• Comunicaciones — responsable de la comunicación con usuarios y stakeholders de negocio: mensajes en Slack, en la status page, en la interfaz de la App (widget/chat), en la tienda de ChatGPT.
• Scribe — anota los pasos y hechos importantes; luego, con estas notas, se redacta el post‑mortem.

En un equipo de una sola persona, los cuatro roles eres tú; simplemente conviene cambiar conscientemente de modo: «ahora soy ingeniero y arreglo», «ahora comunico», «ahora anoto la línea temporal».

5. Runbook: la norma en lugar de la memoria

Un runbook es un documento que describe paso a paso qué hacer ante un tipo concreto de incidente: qué gráficas mirar, qué botones pulsar y de qué se puede prescindir. Reduce mucho la improvisación y el nivel de estrés.

Estructura del runbook

Normalmente un runbook contiene:

1. Descripción breve del incidente y cómo se detecta. Ejemplo: «Aumento de errores de ACP checkout > 5 % en 5 minutos» o «Error talking to app para >20 % de las solicitudes».
2. Scope — a quién afecta el problema: todo el tráfico, solo una región, solo una herramienta concreta.
3. Dónde mirar: enlaces a dashboards (SLO de checkout, error‑rate de MCP, logs para tool_name = create_checkout_session), a MCP Inspector, etc.
4. Pasos rápidos de mitigación: «comprobar el estado de Stripe», «hacer rollback de la última release de ACP», «activar el modo de recomendaciones sin compra».
5. Pasos para el análisis definitivo y el fix.
6. Qué actualizar tras el incidente: alertas, código, documentación.

Mini ejemplo de runbook para GiftGenius (el checkout cae)

Describámoslo como datos estructurados, para acercarlo al código:

type Severity = 'SEV-1' | 'SEV-2' | 'SEV-3';

interface RunbookStep {
  title: string;
  description: string;
}

interface Runbook {
  id: string;
  title: string;
  severity: Severity;
  detection: string;
  steps: RunbookStep[];
}

export const checkoutFailureRunbook: Runbook = {
  id: 'rb-checkout-failure',
  title: 'Aumento de errores de checkout en GiftGenius',
  severity: 'SEV-1',
  detection: 'Alerta: checkout_success_rate < 60% en 10 minutos',
  steps: [
    {
      title: 'Comprobar estados externos',
      description: 'Abrir la página de estado de Stripe y el backend de ACP; asegurarse de que no hay un outage global.',
    },
    {
      title: 'Revisar releases recientes',
      description: 'Comprobar si ha habido despliegues de MCP/ACP en los últimos 30 minutos. Hacer rollback si es necesario.',
    },
  ],
};

En un runbook real añadirás más pasos: activar el feature flag de solo lectura, mostrar un banner en el widget, recopilar logs para el post‑mortem.

Ejemplo de texto para el widget en un incidente de commerce

En el runbook conviene pensar de antemano también el texto para el usuario. Por ejemplo, el widget de GiftGenius puede mostrar:

«En este momento tenemos problemas técnicos temporales con el pago. Aun así puedes guardar las ideas de regalo que te gusten y completaremos la compra un poco más tarde.»

Ese texto luego puede codificarse en el estado del UI:

// Pseudocódigo del estado del widget
const [checkoutAvailable, setCheckoutAvailable] = useState(true);

if (!checkoutAvailable) {
  return (
    <Alert>
      El pago no está disponible temporalmente. Aún puedes explorar y guardar ideas de regalo.
    </Alert>
  );
}

6. Práctica en GiftGenius: código alrededor de incidentes

Para que el tema no se quede en lo organizativo, veamos un par de fragmentos de código que ayudan directamente en la gestión de incidentes.

Endpoint de health‑check para MCP/Backend

Una herramienta simple pero importante es el health‑check. En Next.js 16 se puede hacer con un route handler:

// app/api/health/route.ts
import { NextRequest, NextResponse } from 'next/server';

export function GET(_req: NextRequest) {
  // Se pueden añadir comprobaciones de BD, colas, etc.
  return NextResponse.json({
    status: 'ok',
    mcp: 'healthy',
    timestamp: new Date().toISOString(),
  });
}

El sistema de monitorización consultará periódicamente /api/health. Si en lugar de 200 OK empiezan a llegar timeouts o 5xx, es una señal clara de incidente de Availability (el MCP no está vivo).

Clasificación de incidentes por métricas

En el servicio analítico o en un script de backend administrativo puedes mantener una lógica simple de determinación de severidad:

type Severity = 'SEV-1' | 'SEV-2' | 'SEV-3';

interface IncidentContext {
  checkoutSuccessRate: number; // 0..1
  giftSearchErrorRate: number; // 0..1
  p95GiftSearchMs: number;
}

export function classifyIncident(ctx: IncidentContext): Severity | null {
  if (ctx.checkoutSuccessRate < 0.6) return 'SEV-1'; // el dinero no fluye
  if (ctx.giftSearchErrorRate > 0.3 || ctx.p95GiftSearchMs > 8000) return 'SEV-2';
  return null; // todavía no es incidente
}

Este fragmento puede ejecutarse con cron o dispararse desde la monitorización: cuando devuelva SEV‑1 se crea automáticamente un incidente en tu sistema y se envía una notificación al on‑call.

Registro de eventos clave del incidente

Los incidentes no son solo métricas, también son eventos: cuándo se crea, se modifica y se cierra un incidente. Es útil mantenerlos en logs separados.

function logIncidentEvent(event: {
  incidentId: string;
  type: 'created' | 'mitigated' | 'resolved';
  severity: Severity;
  requestId?: string;
  message: string;
}) {
  logger.warn({
    level: 'WARN',
    service: 'incident-manager',
    ...event,
    timestamp: new Date().toISOString(),
  });
}

Por ejemplo, al activar el modo «solo lectura» para GiftGenius:

setCheckoutDisabled(true);
logIncidentEvent({
  incidentId: 'inc-2025-11-21-001',
  type: 'mitigated',
  severity: 'SEV-1',
  message: 'Checkout disabled, app switched to recommendations-only mode',
});

Después, estos eventos se pueden encontrar fácilmente y correlacionar con las series temporales de las métricas.

7. Calendario operativo: la vida después del «hurra, todo arreglado»

La gestión de incidentes no es solo apagar fuegos, también es prevención regular. En prácticas SRE, el ciclo operativo a menudo se describe como un calendario operativo con revisiones regulares de SLO, costes y seguridad.

De forma aproximada, se pueden dividir las actividades por periodicidad.

Semanalmente

Una vez a la semana (o cada dos) conviene:

• revisar los SLO principales: latencia, tasa de error, éxito del checkout, proporción de incidentes por categoría;
• ver si hubo alertas que «se apagaron solas» y decidir si conviene endurecer o relajar umbrales;
• analizar brevemente al menos un incidente (incluso SEV‑3): ejercita el músculo del post‑mortem.

Mensualmente

Una vez al mes convendría:

• hacer una revisión de costes (LLM, comisiones ACP/Stripe, infraestructura) y compararlos con los ingresos — enlace con los temas 1–2 del módulo 19;
• revisar métricas de producto: activation, retention, conversión workflow_completed → checkout_success — enlace con el módulo de marketing y crecimiento;
• revisar los logs de seguridad en busca de anomalías: patrones extraños de login, errores de autorización, picos inusuales de solicitudes (puente al módulo de seguridad).

Trimestralmente

Una vez al trimestre:

• rotas secretos: claves de API de OpenAI, Stripe, clientes OAuth, etc.;
• compruebas si tus SLO han quedado desfasados: quizá la App creció y ahora un p95 de 2 segundos en lugar de 1 es lo normal, o al contrario, puedes endurecer objetivos;
• revisas runbooks: nuevos tipos de incidentes, dependencias actualizadas (SDK, MCP‑spec, etc.).

El calendario puede llevarse simplemente como una página de Wiki o un README en el repositorio de GiftGenius: lo importante es que esté «vivo» y se actualice.

8. Incidentes, dinero y producto: por qué un incendio de commerce es el más candente

El módulo 19 trata de la economía y la «vida operativa» de la App, y los incidentes aquí están estrechamente ligados al dinero. Los incidentes de commerce —cuando el checkout no pasa, el dinero queda bloqueado o se cobra dos veces— casi siempre tienen mayor prioridad que, por ejemplo, un timeout esporádico al buscar regalos.

Las razones son sencillas:

• pérdidas directas de ingresos en el momento;
• riesgo de pérdida de confianza (un usuario al que le cobran y no recibe el producto difícilmente vuelve);
• posibles consecuencias legales y de reputación.

Por tanto, en tu catálogo de incidentes de GiftGenius los incidentes de commerce deben estar marcados explícitamente como SEV‑1 con SLO estrictos de tiempo de reacción (por ejemplo, «reacción del on‑call en 15 minutos, mitigación en una hora»).

Las anomalías económicas (por ejemplo, el coste de LLM sube bruscamente sin aumento de ingresos) también son incidentes, pero por lo general de nivel SEV‑2: no rompen el UX de inmediato, pero pueden «comerse» todo el margen si no se detectan.

Desde el lado de producto, cualquier incidente grande es una oportunidad para reflexionar:

• si el flujo no es demasiado complejo (quizá más simple signifique más fiable);
• si conviene añadir un escenario de fallback: por ejemplo, si el MCP no responde, que el modelo al menos devuelva consejos sin datos externos;
• si hay que cambiar el UX para comunicar honestamente los problemas, en lugar de ocultarlos.

9. Mini ejercicios (para trabajo autónomo)

Aunque la lección no es un práctico, recomiendo encarecidamente realizar los siguientes pasos en tu propio GiftGenius:

1. Describir en un documento al menos dos runbooks:
   • «Errores masivos en el pago (checkout)»;
   • «El MCP no responde / ChatGPT muestra Error talking to app».
2. Elaborar un calendario operativo para un mes:
   • qué SLO revisarás cada semana;
   • qué revisión de costes harás a final de mes;
   • qué comprobaciones de seguridad incluirás (al menos las básicas).

Esto te llevará un par de horas, pero cambiará mucho la forma en que ves tu aplicación: dejará de ser solo código y se convertirá en un servicio vivo.

Errores típicos en la gestión de incidentes de ChatGPT Apps

Error n.º 1: «Un incidente es solo cuando todo se cae»
Muchos, por costumbre, consideran incidente solo la caída total del MCP o de la base. En las AI‑Apps a menudo son más dolorosos los incidentes de calidad «blandos»: el modelo deja de invocar la herramienta necesaria, el flujo de checkout se vuelve confuso, los usuarios no llegan al final aunque las métricas HTTP estén en verde. Si no consideras estas situaciones como incidentes y no las analizas, la calidad de la App se degradará sin que te des cuenta.

Error n.º 2: Ausencia de SLO claros y de los límites del «funcionamiento normal»
Sin SLO formales, cualquier discusión sobre un incidente se convierte en «me parece que todo va lento» vs «a mí en local me va rápido». Por eso los SLO son la base de la gestión de incidentes: hacen objetiva la gravedad del problema.

Error n.º 3: Improvisación en lugar de runbooks
Escenario común: suena la alerta, todos en pánico saltan a prod, alguien hace rollback, alguien toca configs, al cabo de una hora «parece que se arregló», pero nadie recuerda qué ayudó. Sin runbooks, cada incidente es un mini‑caos y el equipo no aprende. Incluso un runbook simple para incidentes de checkout reduce mucho el estrés.

Error n.º 4: Ignorar la comunicación con los usuarios
A veces los ingenieros arreglan el sistema en silencio, mientras los usuarios solo ven la «ruedita» y un error de «algo ha salido mal». Para escenarios de commerce esto es especialmente tóxico: la gente se preocupa por su dinero. Es importante tener preparados mensajes en el widget, en la descripción de la App y, si es necesario, en canales externos, para comunicar honestamente el problema y el tiempo estimado de solución.

Error n.º 5: Culpar a «OpenAI» sin revisar tu parte
Es fácil achacarlo todo a «OpenAI falla», pero la práctica demuestra que incluso con problemas upstream se puede hacer mucho en tu lado: manejar correctamente timeouts y errores, cambiar a un modo sin MCP, reducir el número de reintentos para no agravar la situación. El concepto de responsabilidad compartida implica que respondes por tu tramo de la cadena, incluso si uno de los proveedores es inestable.

Error n.º 6: Sin post‑mortems ni ciclo operativo
Si el incidente termina con «bueno, parece que ya, sigamos», y ningún documento, alerta o código cambia, el sistema está condenado a repetir los mismos errores. Los post‑mortems y las revisiones regulares de SLO, costes y seguridad no son burocracia: son una forma de pactar con tu yo futuro y con tu equipo para que dentro de un año GiftGenius sea más fiable, no más frágil.