Gerenciamento de incidentes e ciclo operacional

1. O que é um incidente no mundo de ChatGPT Apps

Na web clássica, incidente é geralmente algo como “o servidor está fora do ar”, “os erros 500 aumentaram muito”, “a latência dobrou”. Definição formal do ITIL: incidente é uma interrupção não planejada do serviço ou degradação da qualidade do serviço.

No mundo de ChatGPT Apps e GiftGenius o cenário é mais complexo. Passamos a ter uma camada de modelos que podem:

• não chamar a tool necessária, embora tudo esteja disponível;
• chamar a tool com parâmetros incorretos;
• “alucinar” o resultado, ignorando seu MCP.

Portanto, incidente pode ser não apenas um HTTP 500, mas também a situação em que todas as métricas de backend estão verdes e os usuários reclamam em massa: “o bot está lento e não mostra presentes” — porque o modelo parou de chamar suggest_gifts ou confunde os argumentos. Isso é um incidente de qualidade (Quality incident).

É útil pensar nos incidentes por categorias:

Um incidente é o momento em que a métrica real ultrapassa os limites do SLO acordado previamente. Por exemplo:

• combinamos: p95 da seleção de presentes < 4 segundos. Passou a 9 segundos;
• queremos que 99% dos checkouts na semana sejam bem-sucedidos, mas virou 94%;
• esperamos que em cenários com compra o modelo quase sempre chame create_checkout_session, mas pelos logs vemos um aumento acentuado de “omissões”.

Importante: incidente não é “alguém reclamou no chat”. A reclamação é um gatilho, e a decisão “sim, isso é um incidente” é tomada com base nos SLO/SLI e nos dashboards.

2. Como SLO/SLI viram incidentes

No módulo sobre observabilidade você já definiu as métricas-chave: latência, disponibilidade, taxa de erro, sucesso de checkout. Agora vamos usá-las como “guardiões na porta”.

Cenário mais simples: temos um SLO para checkout_success_rate. Mantemos logs estruturados de eventos:

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

Sobre esses logs se constrói a métrica: fração de status = "success" entre todos os checkout_result nos últimos N minutos/horas. Quando essa fração cai abaixo do limiar (por exemplo, 95% em 10 minutos), o sistema de monitoramento envia um alerta para o canal de on‑call. Essa é a detecção do incidente: o SLI saiu dos limites do SLO.

Alertas podem disparar da mesma forma para:

• aumento de error_rate das ferramentas suggest_gifts, search_products;
• aumento de p95/p99 de latência;
• queda anômala na quantidade de workflow_completed (as pessoas não chegam ao fim do fluxo);
• aumento anômalo do custo de LLM sem aumento do tráfego (incidente econômico).

Tudo isso só é possível porque fazemos logging estruturado, e não escrevemos nos logs “tem algo errado com o checkout de novo”. Quando métricas e alertas estão configurados, aprendemos a notar quando algo deu errado. Próxima pergunta: o que acontece após a detecção, quem e como reage?

3. Ciclo de vida do incidente: da detecção ao post‑mortem

Para não viver em modo de incêndio eterno, é útil descrever o pipeline padrão do incidente. Muitas equipes de SRE o formalizam como uma cadeia:

flowchart TD
    D["Detection (deteção)"] --> T["Triage (avaliação de gravidade)"]
    T --> M["Mitigation (contenção rápida)"]
    M --> R["Resolution (correção definitiva)"]
    R --> P["Post-mortem (análise e melhorias)"]

Vamos analisar as etapas usando o GiftGenius como exemplo.

Detection — como entender que está ruim

A identificação do problema pode ser automática ou manual.

Automática — são alertas do monitoramento com base em SLO/SLI:

• PagerDuty / Opsgenie / e‑mail / bot do Slack alerta: SEV-1: checkout_success_rate < 60% em 10 minutos;
• alerta de latência: p95(suggest_gifts) > 10 s;
• anomalia de custo: “os custos de LLM dobraram com o mesmo número de workflow_completed”.

Detecção manual — quando chega ao suporte (ou a você pessoalmente no Telegram) uma enxurrada de mensagens “o pagamento não passa”, “o widget fica girando para sempre”. Às vezes é isso que destaca o problema antes de o monitoramento alcançar.

Conclusão prática: mesmo que você ainda não tenha um monitoramento ideal, acostume‑se a olhar qualquer enxurrada de reclamações de usuários pela lente das métricas: “que métrica está por trás disso e como medi‑la?”.

Triage — classificação e priorização

Após a detecção, é preciso responder a duas perguntas: quão ruim está e quem vai corrigir.

É útil ter uma escala simples de severidade:

• SEV-1: crítico — os usuários não conseguem comprar, o App não funciona no fluxo principal (por exemplo, checkout=0 com tráfego ativo).
• SEV-2: sério, mas com degradação — parte dos usuários não consegue concluir o fluxo, a latência aumentou muito, mas não a zero.
• SEV-3: bugs menores — uma das tools adicionais cai às vezes, só quebra um caso de borda.

Para o GiftGenius, incidentes de commerce quase sempre são SEV-1: se o dinheiro não flui, você não tem apenas um problema técnico, mas um prejuízo direto na receita e na confiança.

Nessa mesma etapa, designa‑se o on‑call (ou você mesmo, se a equipe for de uma pessoa) e toma‑se a decisão: “Sim, este é um incidente oficial SEV‑1, vamos trabalhar pelo runbook N” (runbook é uma instrução passo a passo pré‑definida; a estrutura veremos em uma seção separada).

Mitigation — estancar o “sangramento”

Mitigation não é buscar a causa raiz, mas sim ações rápidas para que os usuários sofram menos. Exemplos:

• reverter a última release de MCP/Agents/ACP;
• desligar o feature flag problemático;
• colocar o GiftGenius em modo “apenas visualização”: mostramos recomendações, mas não permitimos finalizar a compra;
• reduzir temporariamente a carga (rate limiting) ou desativar ferramentas pesadas.

Exemplo típico de código para “modo degradado” no nosso MCP:

// Pseudo-código: flag global que pode ser alternado rapidamente
let checkoutDisabled = false;

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

export async function createCheckoutSession(args: CheckoutArgs) {
  if (checkoutDisabled) {
    // Informamos ao modelo que a compra está temporariamente indisponível
    return {
      error: 'checkout_temporarily_disabled',
      message: 'Pagamento temporariamente indisponível, mostre uma explicação ao usuário.',
    };
  }

  // lógica normal de criação da sessão
}

No sistema de feature flags você pode acionar setCheckoutDisabled(true) como parte da mitigação: os usuários pelo menos não receberão erros 500 e pagamentos travados, e sim uma mensagem honesta.

Resolution — correção definitiva

Quando o “sangramento foi estancado”, você ganha tempo para encontrar a causa raiz e corrigi‑la:

• bug no código do MCP/ACP;
• problema com provedor externo (Stripe, gateway de pagamento);
• limites da OpenAI API (429, sobrecarga);
• prompt quebrado ou mudança de modelo que parou de chamar a tool.

Resolution geralmente inclui:

• fix (patch/rollback/config);
• deploy em staging, depois em produção;
• verificação de todos os SLI/SLO;
• retorno dos flags ao estado normal.

Post-mortem — aprendendo com os erros

Após o incidente, especialmente SEV‑1/SEV‑2, faz‑se um post‑mortem: um documento em que você responde honestamente às perguntas:

• o que aconteceu (em fatos e timeline);
• como foi percebido;
• como foi a reação;
• o que funcionou bem e o que não funcionou;
• que mudanças você fará para que isso não se repita.

Post‑mortem não é sobre encontrar culpados, e sim sobre melhorar o sistema e o processo. Com base nele, atualizam‑se runbooks, alertas e às vezes até a arquitetura.

4. Papéis e responsabilidades: mesmo se você for “sozinho no campo”

Para que o pipeline de incidentes descrito acima funcione na vida real, é importante combinar com antecedência quem decide o quê durante o incêndio. Mesmo que sua equipe caiba em um único elevador, faz sentido formalizar os papéis em incidentes. Isso reduz o caos.

Normalmente se separam:

• Engenheiro on‑call — quem recebe o alerta primeiro e toma decisões técnicas para estabilizar (rollback, feature flags, soluções temporárias).
• Incident commander — a pessoa que conduz o processo: registra a timeline, decide a prioridade das tarefas, garante que a equipe não se disperse. Em uma microequipe é o mesmo on‑call, mas com outro “chapéu”.
• Comunicação — responde pela comunicação com usuários e stakeholders de negócio: mensagens no Slack, na status page, na interface do App (widget/chat), na loja do ChatGPT.
• Scribe — registra os passos e fatos importantes; depois, com base nesse rascunho, escreve‑se o post‑mortem.

Numa equipe de uma pessoa, você exerce os quatro papéis — só é útil alternar conscientemente o modo: “agora sou engenheiro e estou corrigindo”, “agora estou comunicando”, “agora estou registrando a timeline”.

5. Runbook: manual em vez de memória

Runbook é um documento que descreve passo a passo o que fazer para um tipo específico de incidente: quais gráficos olhar, que botões apertar, de que se pode abrir mão. Ele reduz muito a improvisação e o nível de estresse.

Estrutura de um runbook

Normalmente o runbook contém:

1. Descrição curta do incidente e como é detectado. Exemplo: “Aumento de erros de ACP checkout > 5% em 5 minutos” ou “Error talking to app para >20% das requisições”.
2. Escopo — quem é afetado: todo o tráfego, apenas uma região, apenas uma tool específica.
3. Onde olhar: links para dashboards (SLO de checkout, error‑rate do MCP, logs com tool_name = create_checkout_session), para o MCP Inspector, etc.
4. Passos rápidos de mitigação: “verificar o status do Stripe”, “reverter a última release do ACP”, “ativar modo de recomendações sem compra”.
5. Passos para análise definitiva e fix.
6. O que deve ser atualizado ao final: alertas, código, documentação.

Mini‑exemplo de runbook para o GiftGenius (checkout falhando)

Vamos descrevê‑lo como dados estruturados, para ficar mais próximo de 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 erros de checkout no GiftGenius',
  severity: 'SEV-1',
  detection: 'Alerta: checkout_success_rate < 60% em 10 minutos',
  steps: [
    {
      title: 'Verificar status externos',
      description: 'Abrir o status do Stripe e do backend ACP, garantindo que não haja outage global.',
    },
    {
      title: 'Verificar releases recentes',
      description: 'Checar se houve deploy de MCP/ACP nos últimos 30 minutos. Reverter se necessário.',
    },
  ],
};

Num runbook real você adicionará mais passos: ativar o feature flag de leitura (read‑only), mostrar um banner no widget, coletar logs para o post‑mortem.

Exemplo de texto para o widget em um incidente de commerce

No runbook é útil pensar antes no texto para o usuário. Por exemplo, o widget do GiftGenius pode mostrar:

“Estamos com problemas técnicos temporários no pagamento. Você ainda pode salvar as ideias de presente de que gostou e concluiremos a compra em breve.”

Esse texto pode então ser codificado em um estado de UI:

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

if (!checkoutAvailable) {
  return (
    <Alert>
      Pagamento temporariamente indisponível. Você ainda pode navegar e salvar ideias de presente.
    </Alert>
  );
}

6. Prática no GiftGenius: código em torno de incidentes

Para que o tema não fique apenas organizacional, vamos ver alguns trechos de código que ajudam diretamente no gerenciamento de incidentes.

Endpoint de health check para MCP/Backend

Ferramenta simples, mas importante — o health check. No Next.js 16 é possível fazê‑lo via route handler:

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

export function GET(_req: NextRequest) {
  // Você pode adicionar checagens de BD, filas etc.
  return NextResponse.json({
    status: 'ok',
    mcp: 'healthy',
    timestamp: new Date().toISOString(),
  });
}

O sistema de monitoramento vai consultar periodicamente /api/health. Se em vez de 200 OK vierem timeouts ou 5xx, isso é um sinal claro de incidente de Availability (MCP fora).

Classificação do incidente por métricas

No serviço analítico ou em um script de backend administrativo, você pode manter uma lógica simples de definição de severidade:

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'; // o dinheiro não flui
  if (ctx.giftSearchErrorRate > 0.3 || ctx.p95GiftSearchMs > 8000) return 'SEV-2';
  return null; // ainda não é incidente
}

Esse trecho pode rodar em cron ou ser acionado pelo monitoramento: ao retornar SEV‑1, cria‑se automaticamente um incidente no seu sistema e sai uma notificação para o on‑call.

Log de eventos-chave do incidente

Incidentes não são apenas métricas, mas também eventos: quando o incidente é criado, alterado, fechado. É útil manter isso em 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 exemplo, ao ativar o modo “read‑only” para o GiftGenius:

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

Depois esses eventos são fáceis de localizar e correlacionar com as séries temporais das métricas.

7. Calendário operacional: a vida após o “ufa, consertamos tudo”

Gerenciamento de incidentes não é apenas apagar incêndios, mas também prevenção regular. Nas práticas de SRE, o ciclo operacional é frequentemente descrito como um calendário operacional com revisões regulares de SLO, custos e segurança.

De forma geral, é possível dividir as atividades por periodicidade.

Semanalmente

Uma vez por semana (ou a cada duas) faz sentido:

• revisar os SLO principais: latência, taxa de erro, sucesso de checkout, proporção de incidentes por categorias;
• ver se houve alertas na semana que “se resolveram sozinhos” e decidir se vale reforçar/afrouxar os limiares;
• discutir brevemente pelo menos um incidente (mesmo SEV‑3) — isso treina o músculo de post‑mortem.

Mensalmente

Uma vez por mês é bom:

• fazer a revisão de custos (LLM, comissões ACP/Stripe, infraestrutura) e compará‑los com a receita — ligação com os tópicos 1–2 do módulo 19;
• ver métricas de produto: activation, retention, conversão de workflow_completed → checkout_success — ligação com o módulo de marketing e growth;
• percorrer os logs de segurança em busca de anomalias: padrões estranhos de login, erros de autorização, picos incomuns de requisições (ponte para o módulo de segurança).

Trimestralmente

Uma vez por trimestre você:

• rotaciona segredos: chaves de API da OpenAI, Stripe, clientes OAuth etc.;
• verifica se os SLO ficaram obsoletos: talvez o App tenha crescido e agora p95 de 2 segundos em vez de 1 seja a norma, ou ao contrário, você possa apertar as metas;
• revisa os runbooks: novos tipos de incidentes, dependências atualizadas (SDK, especificação do MCP etc.).

O calendário pode ser mantido simplesmente como uma página de Wiki ou README no repositório do GiftGenius: o importante é que seja “vivo” e atualizado.

8. Incidentes, dinheiro e produto: por que incidentes de commerce são os mais críticos

O módulo 19 trata de economia e da “vida operacional” do App, e incidentes aqui estão intimamente ligados ao dinheiro. Incidentes de commerce — quando o checkout não passa, o dinheiro é bloqueado ou cobrado em duplicidade — quase sempre têm prioridade mais alta do que, por exemplo, um timeout eventual na busca de presentes.

As razões são simples:

• perdas diretas de receita no momento atual;
• risco de perda de confiança (um usuário que foi cobrado e não recebeu o produto dificilmente voltará);
• potenciais consequências jurídicas e de reputação.

Por isso, no seu catálogo de incidentes do GiftGenius, incidentes de commerce devem estar marcados explicitamente como SEV‑1 com SLO rígidos para tempo de resposta (por exemplo, “resposta do on‑call em até 15 minutos, mitigação em até 1 hora”).

Anomalias econômicas (por exemplo, o custo de LLM aumenta abruptamente sem aumento de receita) — também são incidentes, mas geralmente de nível SEV‑2: não quebram o UX imediatamente, mas podem “comer” toda a margem se não forem percebidas.

Do lado de produto, qualquer incidente grande é motivo para refletir:

• o workflow não está complexo demais (talvez mais simples = mais confiável);
• vale adicionar um cenário de fallback: por exemplo, se o MCP não responde, o modelo ao menos fornece conselhos sem dados externos;
• é preciso ajustar o UX para comunicar honestamente os problemas, e não escondê‑los.

9. Mini‑exercícios (para prática individual)

Embora a aula não seja um laboratório, recomendo fortemente realizar de verdade os passos a seguir no seu GiftGenius:

1. Descreva em um único documento pelo menos dois runbooks:
   • “Erros em massa no pagamento (checkout)”;
   • “MCP não responde / ChatGPT mostra Error talking to app”.
2. Monte um calendário operacional para um mês:
   • quais SLO você vai revisar toda semana;
   • qual revisão de custos fará no fim do mês;
   • quais checagens de segurança incluir (ao menos as básicas).

Isso vai levar algumas horas, mas mudará muito a forma como você olha para seu aplicativo: ele deixará de ser apenas código e se tornará um serviço vivo.

Erros comuns no gerenciamento de incidentes de ChatGPT Apps

Erro Nº1: “Incidente é só quando tudo cai”
Muitos, por hábito, consideram incidente apenas a queda total do MCP ou do banco. Em AI‑Apps, muitas vezes são mais dolorosos os incidentes “suaves” de qualidade: o modelo parou de chamar a tool necessária, o fluxo de checkout ficou confuso, os usuários não chegam ao fim, embora as métricas HTTP estejam verdes. Se você não considera essas situações incidentes e não as analisa, a qualidade do App vai degradar de forma silenciosa.

Erro Nº2: Ausência de SLO claros e de limites de “operação normal”
Sem SLO formais, qualquer discussão sobre incidente vira “acho que está lento” vs “na minha máquina está rápido”. É por isso que SLO são a base do gerenciamento de incidentes: eles tornam a gravidade do problema objetiva.

Erro Nº3: Improvisação em vez de runbooks
Cenário comum: alerta, todos entram em pânico no prod, alguém reverte a release, alguém mexe em configs, depois de uma hora “parece que consertou”, mas ninguém lembra o que exatamente ajudou. Sem runbooks, cada incidente é um mini‑caos, e a equipe não aprende. Mesmo um runbook simples para incidentes de checkout reduz muito o estresse.

Erro Nº4: Ignorar a comunicação com os usuários
Às vezes os engenheiros consertam o sistema em silêncio, enquanto os usuários veem apenas o “spinner” e o erro “algo deu errado”. Para cenários de commerce isso é especialmente tóxico: as pessoas ficam preocupadas com o dinheiro. É importante ter previamente modelos de mensagens no widget, na descrição do App e, se necessário, em canais externos, para comunicar de forma honesta o problema e o tempo esperado de correção.

Erro Nº5: Culpar “a OpenAI” sem analisar sua parte
É fácil colocar tudo na conta de “a OpenAI está instável”, mas a prática mostra que mesmo com problemas upstream há muito a fazer do seu lado: tratar corretamente timeouts e erros, alternar para modo sem MCP, reduzir o número de tentativas para não agravar a situação. A ideia de responsabilidade compartilhada implica que você responde pela sua parte da cadeia, mesmo se algum provedor estiver instável.

Erro Nº6: Sem post‑mortems e sem ciclo operacional
Se o incidente termina com “bom, parece tudo certo, vamos em frente”, e nenhum documento, alerta ou código muda — o sistema está condenado a repetir os mesmos erros. Post‑mortems, revisões regulares de SLO, custos e segurança — não são burocracia, e sim um jeito de combinar com o seu eu futuro e com sua equipe para que, em um ano, o GiftGenius esteja mais confiável, e não mais frágil.