> ## Documentation Index > Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt > Use this file to discover all available pages before exploring further. # Ciclo de Vida do Incidente > Guia completo de como os incidentes fluem pela detecção, análise, remediação, escalação e resolução — incluindo o que fazer quando o sistema requer intervenção humana ## Visão Geral A plataforma AIOps do ChatCLI gerencia incidentes através de uma máquina de estados bem definida com **6 estados** para incidentes e **6 estados** para planos de remediação. Entender este ciclo de vida é essencial para operadores que precisam intervir quando a remediação automática falha. ## Estados do Incidente | Estado | Descrição | Terminal? | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `Detected` | Anomalia correlacionada em um incidente, aguardando análise | Não | | `Analyzing` | IA realizando análise de causa raiz | Não | | `Remediating` | Plano de remediação em execução | Não | | `Contained` | Workload silenciado via ação de contenção (ex: `ScaleDeployment replicas=0`) — **bug subjacente não resolvido, requer ação humana** | Semi-terminal | | `Resolved` | Incidente resolvido com sucesso | Sim | | `Escalated` | Todas as tentativas automáticas esgotadas — **requer intervenção humana** (auto-resolve se o recurso recuperar) | Semi-terminal | | `Failed` | Tentativa única falhou sem retry configurado | Sim | **Novo estado `Contained` (chaos test 2026-05-23, GAP-03)** — Antes deste fix, qualquer ação `ScaleDeployment replicas=0 containment=true` declarava o Issue como `Resolved`, mascarando indisponibilidade real. Agora a plataforma transita para `Contained`, que: * **NÃO** é terminal (auto-resolve quando o recurso volta com `replicas > 0` E todos os pods ready) * Bloqueia o PostMortem de fechar (`requiresHumanAction: true`) até o operador confirmar via API ou anotação * Dispara notificações em política configurada para o estado `Contained` * É contado separadamente em `analytics/summary.containedIssues` Configure uma `NotificationPolicy` com `states: [Contained]` para garantir que humanos sejam paginados quando isso acontecer. ## Fluxo da Máquina de Estados ``` Detected → Analyzing → Remediating → Resolved ↓ ↓ ↑ Escalated Contained ───────┘ (humano restaura replicas) (após max (ação com tentativas) containment=true) ↓ ↓ Re-análise Failed/RolledBack (até 5x) ↓ Escalated ↓ Auto-resolve se o recurso recuperar (configurável) ``` ### Fase de Detecção (`Detected`) Quando o watcher bridge detecta anomalias, o correlation engine as agrupa em incidentes: 1. **Pontuação de sinal** — cada tipo de sinal tem um peso (OOMKill=40, ErrorRate=30, PodRestart=25, etc.) 2. **Cálculo do risk score** — agregado de todas as anomalias correlacionadas 3. **Determinação da severidade** — Critical (risk > 80), High (> 60), Medium (> 40), Low (demais) 4. **Geração do ID do incidente** — formato: `INC-AAAAMMDD-NNN` 5. **Máximo de tentativas de remediação** configurado para 5 (padrão, configurável via Instance `aiops.maxRemediationAttempts`) ### Fase de Análise (`Analyzing`) O sistema cria um AIInsight CR para análise via IA. Durante a detecção, TODOS os runbooks candidatos são injetados no contexto da IA para validação. 1. **Descoberta de runbooks candidatos** (em camadas): * **Camada 1**: Todos os runbooks com SignalType + Severity + ResourceKind * **Camada 2**: Fallback por Severity + ResourceKind * Multiplos runbooks podem existir por trigger (causas raiz diferentes geram runbooks diferentes) 2. **IA válida candidatos**: O LLM recebe todos os runbooks candidatos e avalia cada um contra a análise de causa raiz atual: * **`RUNBOOK_APPROVED: <nome>`** → usa aquele runbook específico (caminho rápido) * **`RUNBOOK_REJECTED`** → ignora todos os candidatos, usa sugestões da IA ou modo agentico * **Nenhum dos dois** → usa primeiro candidato como default (compatibilidade) 3. **Se não ha candidatos** e a IA tem ações sugeridas → gera um novo runbook 4. **Se não ha candidatos e nem ações da IA** → entra no **Modo Agentico** (IA passo-a-passo) 5. Transiciona para `Remediating` ### Fase de Remediação (`Remediating`) O remediation controller executa o plano usando um **loop ReAct** (Reason-Act-Observe): 1. **Snapshot pre-voo** capturado para capacidade de rollback 2. Para **cada acao** no plano: * **OBSERVE** — verifica se o recurso já está saudável (após a ação anterior). Se sim, **para imediatamente** sem executar as ações restantes (early exit) * **ACT** — executa a ação com checkpoint * Se a ação **falha** → rollback automático ao estado pre-voo 3. **Verificação final de saude** (polling por até 90 segundos) 4. **Em caso de sucesso** → `Resolved` + PostMortem gerado 5. **Em caso de falha** → rollback automático tentado → re-análise com contexto da falha ``` Exemplo: plano com 3 ações (AdjustResources + DeletePod + RollbackDeployment) Ação 1: AdjustResources → SUCCESS (memory 1Mi → 64Mi) Ação 2: OBSERVE → recurso healthy (ReadyReplicas == Desired) → EARLY EXIT! Pula DeletePod e RollbackDeployment → Evidence: "Resource healthy after 1/3 actions — skipped remaining 2" ``` Isso evita que ações contraditórias sejam executadas (ex.: `AdjustResources` seguido de `RollbackDeployment` que desfaria o ajuste) e reduz o impacto operacional ao mínimo necessário. ### Mecanismo de Retry Quando a remediação falha: * **Tentativa \< MaxAttempts (5)**: O sistema re-analisa com o contexto da falha injetado, potencialmente selecionando um runbook ou estratégia diferente * **Todas as tentativas esgotadas**: Transiciona para `Escalated` ### Estado Escalated — O Que os Operadores Devem Fazer Quando um incidente atinge `Escalated`, o sistema esgotou todas as opções automáticas. Veja o que acontece e o que você precisa fazer: **O que o sistema faz automaticamente:** 1. Dispara a EscalationPolicy correspondente a severidade do incidente 2. Envia notificações para L1 on-call (Slack, PagerDuty, etc.) 3. Se não houver reconhecimento dentro do timeout configurado, escala para L2, depois L3 4. Gera eventos de auditoria para compliance **O que os operadores devem fazer:** 1. **Reconhecer** o incidente (para a progressão da escalação): ```bash theme={"system"} curl -X POST https://operator:8090/api/v1/incidents/INC-20260319-001/acknowledge \ -H "X-API-Key: $API_KEY" \ -d '{"acknowledgedBy": "seu-email@empresa.com"}' ``` 2. **Investigar e corrigir** o problema manualmente 3. **Resolver** o incidente via um dos tres metodos: **Método 1: REST API** (recomendado para automacao/scripts) ```bash theme={"system"} curl -X POST https://operator:8090/api/v1/incidents/INC-20260319-001/resolve \ -H "X-API-Key: $API_KEY" \ -d '{"resolution": "Corrigido memory leak no payment-service v2.4.1, hotfix implantado manualmente"}' ``` **Método 2: Web Dashboard** Navegue até a página de detalhes do incidente e clique no botão **"Resolve"**. Insira a descrição da resolução no diálogo. **Método 3: Kubernetes Direto** (avancado) ```bash theme={"system"} kubectl patch issue INC-20260319-001 -n production --type=merge \ -p '{"status":{"state":"Resolved","resolution":"Correção manual aplicada"}}' ``` ## Auto-Resolve para Issues Escalados Quando um incidente atinge `Escalated`, o sistema continua monitorando o recurso a cada 30 segundos. Se o recurso recuperar (todas as replicas saudaveis), o incidente e **automaticamente resolvido** com a mensagem: > "Auto-resolved: resource recovered while awaiting human intervention" Isso cobre os casos onde: * Um operador corrige o problema manualmente (kubectl rollout undo, etc.) sem usar a API * O recurso se auto-corrige (ex: problema de rede transitorio se resolve) * Um pipeline de CI/CD implanta uma correção enquanto o incidente ainda está aberto O auto-resolve pode ser desabilitado via Instance CRD: `spec.aiops.enableAutoResolve: false` ## Parâmetros AIOps Configuraveis Todos os parâmetros de timing e retry são configuraveis via a seção `aiops` do Instance CRD: ```yaml theme={"system"} apiVersion: platform.chatcli.io/v1alpha1 kind: Instance metadata: name: chatcli-prod spec: provider: OPENAI model: gpt-5.4 aiops: maxRemediationAttempts: 5 # padrão: 5, range: 1-10 resolutionCooldownMinutes: 10 # padrão: 10, range: 0-120 dedupTTLMinutes: 60 # padrão: 60, range: 5-1440 enableAutoResolve: true # padrão: true ``` | Parâmetro | Padrão | Descrição | | --------------------------- | ------ | ------------------------------------------------------------------------- | | `maxRemediationAttempts` | 5 | Quantas vezes a IA pode tentar antes de escalar | | `resolutionCooldownMinutes` | 10 | Após resolver, quanto tempo suprimir novas anomalias para o mesmo recurso | | `dedupTTLMinutes` | 60 | Quanto tempo o cache de dedup do bridge mantem hashes de alertas | | `enableAutoResolve` | true | Auto-resolver issues Escalados quando o recurso recupera | | `agenticMaxSteps` | 10 | Steps maximos por tentativa em modo agentico (range: 3-30) | Runbooks auto-gerados pela IA (tanto standard quanto agenticos) herdam automaticamente o valor de `maxRemediationAttempts` da configuração do Instance. Runbooks criados manualmente via YAML ou API usam o default do CRD (`maxAttempts: 3`) a menos que especificado explicitamente. ## Estados do Plano de Remediação Cada incidente pode ter múltiplos planos de remediação (um por tentativa): | Estado | Descrição | | ------------ | ---------------------------------------------------- | | `Pending` | Validação de segurança em andamento | | `Executing` | Ações sendo executadas sequencialmente | | `Verifying` | Verificação de saúde pós-ação (até 90s) | | `Completed` | Todas as ações bem-sucedidas e saude verificada | | `Failed` | Ação falhou, rollback não possível | | `RolledBack` | Ação falhou, rollback ao estado pre-voo bem-sucedido | ## Modo de Remediação Agentico Quando nenhum runbook corresponde, o sistema usa remediação agentica dirigida por IA: 1. **IA propoe uma acao** via AgenticStep RPC 2. **Acao e executada** e o resultado e observado 3. **IA analisa a observacao** e propoe a proxima acao 4. **Loop continua** até resolver ou detectar convergencia **Guardrails de segurança:** * **Max steps**: 10 (configurável via `AgenticMaxSteps`) * **Max tempo**: 10 minutos por plano agentico * **Detecção de convergencia**: * Ultimas 3 observações identicas → parada forcada * Padrão alternante A→B→A→B → parada forcada * 5 ações consecutivas falharam → parada forcada ## Limiares de Confiança do Decision Engine O decision engine determina se a remediação pode prosseguir automaticamente: | Severidade | Limiar de Auto-Aprovação | Ação | | ---------- | ------------------------ | ---------------------------- | | Low | Confiança ≥ 0.95 | Auto-execução | | Medium | Confiança ≥ 0.85 | Auto-execução + notificação | | High | Confiança ≥ 0.80 | Requer aprovação | | Critical | Sempre | Aprovação manual obrigatória | **Ajustes**: Taxa de sucesso histórico, correspondência de padrão, hora do dia e contagem de issues ativas modificam o score base de confiança. **Circuit breaker**: Se 3+ remediações falharam na última hora, a auto-remediação é bloqueada inteiramente. ## Rollback Engine O rollback engine fornece redes de segurança em dois níveis: 1. **Snapshot pré-voo** — capturado antes de QUALQUER ação. Restaura o estado completo do recurso. 2. **Checkpoints por acao** — capturados antes de CADA acao. Permite rollback parcial. **Gatilhos de rollback automático:** * Execução da ação falha * Verificação de saude expira (90 segundos) **Alvos de rollback suportados:** * Deployment: replicas, imagens de container, limites de recursos * StatefulSet: replicas, imagens, recursos, partition * DaemonSet: imagens, recursos, max unavailable * Job/CronJob: suspend, deadline, backoff limit, parallelism * Node: uncordon (restaurar schedulable) ## Tipos de Ação de Remediação A plataforma suporta **46+ tipos de ação de remediação** entre tipos de recurso: ### Deployment (18 ações) `ScaleDeployment`, `RollbackDeployment`, `RestartDeployment`, `PatchConfig`, `AdjustResources`, `DeletePod`, `HelmRollback`, `ArgoSyncApp`, `AdjustHPA`, `RestartStatefulSetPod`, `CordonNode`, `DrainNode`, `ResizePVC`, `RotateSecret`, `ExecDiagnostic`, `UpdateIngress`, `PatchNetworkPolicy`, `ApplyManifest` ### StatefulSet (9 ações) `ScaleStatefulSet`, `RestartStatefulSet`, `RollbackStatefulSet`, `AdjustStatefulSetResources`, `DeleteStatefulSetPod`, `ForceDeleteStatefulSetPod`, `UpdateStatefulSetStrategy`, `RecreateStatefulSetPVC`, `PartitionStatefulSetUpdate` ### DaemonSet (7 ações) `RestartDaemonSet`, `RollbackDaemonSet`, `AdjustDaemonSetResources`, `DeleteDaemonSetPod`, `UpdateDaemonSetStrategy`, `PauseDaemonSetRollout`, `CordonAndDeleteDaemonSetPod` ### Job (9 ações) `RetryJob`, `AdjustJobResources`, `DeleteFailedJob`, `SuspendJob`, `ResumeJob`, `AdjustJobParallelism`, `AdjustJobDeadline`, `AdjustJobBackoffLimit`, `ForceDeleteJobPods` ### CronJob (10 ações) `SuspendCronJob`, `ResumeCronJob`, `TriggerCronJob`, `AdjustCronJobResources`, `AdjustCronJobSchedule`, `AdjustCronJobDeadline`, `AdjustCronJobHistory`, `AdjustCronJobConcurrency`, `DeleteCronJobActiveJobs`, `ReplaceCronJobTemplate` ## Sistema de Aprendizado de Runbooks ### Node Failure — Fluxo de Remediação Quando um node apresenta problemas, o watcher detecta a condição e emite anomalias automaticamente: ``` Node MemoryPressure detectado → Anomaly CR criado (signal: memory_high, severity: critical) → Issue correlacionada com pods afetados → IA analisa: "Node worker-2 com MemoryPressure, pods do echo-app impactados" → Remediação: CordonNode (impede novos pods) + DrainNode (evacua pods existentes) → Kubernetes re-schedula pods em nodes saudáveis → Verificação: pods healthy em novos nodes → Resolved ``` As ações `CordonNode` e `DrainNode` respeitam PodDisruptionBudgets e fazem eviction graceful. O contexto de node (CPU, memória, pod count, condições) e incluido na análise da IA, permitindo decisões mais precisas. A plataforma constrói uma **biblioteca de estratégias aprendidas** ao longo do tempo. Cada remediação bem-sucedida gera um runbook reutilizável que pode ser aplicado a incidentes futuros com a mesma causa raiz. ### Como os Runbooks São Nomeados Nomes de runbooks incluem um hash da análise de causa raiz da IA, garantindo que causas diferentes produzam runbooks diferentes: ``` auto-{sinal}-{severidade}-{tipo}-{hash} Exemplos: auto-oom-kill-critical-deployment-a3f2b1 (causa: tail /dev/zero) auto-oom-kill-critical-deployment-c7d4e9 (causa: memory limit muito baixo) auto-pod-not-ready-low-deployment-e8b3d2 (causa: imagem invalida) ``` ### Seleção Multi-Runbook Quando múltiplos runbooks correspondem ao mesmo trigger (sinal + severidade + tipo), a IA recebe TODOS os candidatos e seleciona o mais apropriado: ``` Novo incidente OOMKill em Deployment ↓ 3 runbooks candidatos encontrados (causas raiz diferentes) ↓ Todos os 3 injetados no contexto da IA com seus steps e descrições ↓ IA analisa a causa raiz atual e responde: "RUNBOOK_APPROVED: auto-oom-kill-critical-deployment-c7d4e9" (porque este incidente e causado por memory limits baixos, correspondendo ao runbook) ↓ Runbook selecionado executado → resolução rapida sem loop agentico ``` Se **nenhum** dos candidatos corresponde a causa raiz atual, a IA responde com `RUNBOOK_REJECTED`, gera uma nova estratégia do zero, e um **novo runbook e criado** com hash único — expandindo a biblioteca para incidentes futuros. ### Ciclo de Vida do Runbook | Estágio | O que Acontece | | --------------------- | --------------------------------------------------------------- | | **Criado** | Auto-gerado após remediação bem-sucedida pela IA | | **Encontrado** | Descoberto por criterios de trigger (sinal + severidade + tipo) | | **Validado** | IA avalia se o runbook se aplica a causa raiz atual | | **Executado** | Steps executados sequencialmente com capacidade de rollback | | **Biblioteca cresce** | Cada nova causa raiz adiciona um novo runbook a biblioteca | Com o tempo, a plataforma se torna mais rapida e precisa — falhas comuns são resolvidas via runbooks (segundos) em vez de análise completa da IA (minutos). ## Geração de PostMortem Quando um incidente e resolvido (automaticamente ou manualmente), um PostMortem CR e auto-gerado contendo: * **Timeline** — eventos cronológicos da detecção a resolução * **Análise de causa raiz** — gerada por IA com score de confiança * **Ações executadas** — histórico completo de remediação * **Avaliação de impacto** — pods, serviços e SLOs afetados * **Lições aprendidas** — recomendações da IA para prevenção * **Correlação com Git** — deploys recentes que podem ter causado o problema * **Análise de cascata** — incidentes relacionados entre servicos PostMortems podem ser revisados e fechados via os endpoints [Review PostMortem](/pt/reference/api/review-postmortem) e [Close PostMortem](/pt/reference/api/close-postmortem). ### PostMortems com `requiresHumanAction` Quando o Issue pai está em estado `Contained`, **tanto o Issue quanto o PostMortem** são gerados com os fields tipados em `status` (GAP-07 fix): ```bash theme={"system"} # Issue kubectl get issue -o jsonpath='{.status.requiresHumanAction}' # true kubectl get issue -o jsonpath='{.status.requiredAction}' # restore the deployment's replicas to the desired count after fixing the root cause... # PostMortem kubectl get postmortem pm- -o jsonpath='{.status.requiresHumanAction}' # true kubectl get postmortem pm- -o jsonpath='{.status.requiredAction}' # (mesmo texto, propagado do Issue) ``` Comportamentos garantidos: * O `PostMortemReconciler` **se recusa** a transitar para `Closed` enquanto a anotação `aiops.chatcli.io/human-action-acknowledged` não for `true` (mesmo se alguém forçar `kubectl patch`) * Quando o auto-resolve dispara (humano restaura replicas), o controller **limpa** os dois fields e adiciona condition `RequiresHumanAction: False` — o CR nunca mente sobre o estado atual * A REST API expõe os fields como top-level no `IncidentItem` (`spec.requiresHumanAction`, `spec.requiredAction`) para dashboards renderizarem direto sem precisar fetch do PostMortem matching **Migração de schema (v1alpha1)** — Na 1.122.x os fields viviam em `PostMortemSpec`, violando a convenção K8s (Spec = user input, Status = controller-derived facts). Pior: o valor era `null` em runtime porque o controller escrevia via `Status().Update()` enquanto o CRD declarava em `Spec`. O fix moveu para `PostMortemStatus` e adicionou em `IssueStatus`. O hook de upgrade de CRD (GAP-06) atualiza o schema automaticamente — não há ação manual necessária. Para reconhecer a ação executada e desbloquear o fechamento: ```bash theme={"system"} # Via API REST curl -X POST -H "Authorization: Bearer $TOKEN" \ "$AIOPS_URL/api/v1/postmortems//ack-human-action?namespace=default" \ -d '{"acknowledgedBy":"sre-team","note":"rolled back to v1.2.3 and scaled to 3 replicas"}' # Ou via kubectl kubectl annotate postmortem -n default \ aiops.chatcli.io/human-action-acknowledged=true \ aiops.chatcli.io/human-action-acknowledged-by=sre-team ``` No web dashboard, isso aparece como o botão **"Ack Human Action"** (roxo) na linha do PostMortem quando `requiresHumanAction=true`. ## Correlação com Chaos Engineering Issues que disparam durante uma `ChaosExperiment` ativa no mesmo namespace recebem automaticamente os labels: * `platform.chatcli.io/source=chaos-experiment` * `platform.chatcli.io/chaos-experiment=` Esses labels alteram o comportamento da plataforma: | Comportamento | Issue produção | Issue chaos-induced | | ---------------------------------------- | -------------- | ------------------------ | | Pipeline AIOps completo | ✅ | ✅ | | Escalação L1→L2 (paging) | ✅ | ❌ (suprimida) | | Métrica `issueResolutionDuration` (MTTR) | ✅ | ❌ (excluída) | | `analytics/summary.chaosInducedIssues` | - | Contado separadamente | | Label no PostMortem gerado | - | Propagado para filtragem | Veja [Chaos Engineering](/pt/features/aiops/chaos-engineering) para detalhes da CR e do controller. ## Integração com SLA Cada severidade de incidente pode ter uma configuração de SLA: * **Tempo de resposta** — tempo máximo da detecção até a primeira análise * **Tempo de resolução** — tempo máximo da detecção até a resolução * **Horario comercial** — opcionalmente pausar o relogio do SLA fora do horario comercial * **Política de escalação** — disparada automaticamente na violação do SLA