Runbooks PHP para recuperar incidentes com segurança

Um runbook de incidentes para aplicações PHP transforma um alerta numa sequência de decisões controladas. Não é uma lista de comandos nem um documento que pressupõe uma causa: deve indicar qual sintoma foi detetado, que evidências recolher, que ações são aceitáveis, quando parar e quem pode decidir o passo seguinte.

Isto é especialmente importante em aplicações com tráfego web, processos PHP em segundo plano, filas, cron, integrações externas e bases de dados partilhadas. Uma intervenção aparentemente simples, como reiniciar consumidores ou repetir mensagens, pode ocultar a origem, duplicar operações ou aumentar a carga sobre um serviço já degradado.

O que um runbook resolve e o que não deve substituir

Um runbook reduz a improvisação durante situações repetíveis ou previsíveis. Torna explícita a ordem das verificações, os limites de uma intervenção e as evidências necessárias para declarar a recuperação. Também permite que desenvolvimento, operações e negócio partilhem a mesma linguagem perante um incidente.

Não substitui os controlos que devem existir antes do incidente:

• Observabilidade: métricas, logs correlacionados, traces e alertas com limiares compreensíveis. Um procedimento não compensa um sinal ambíguo ou sem contexto.
• Formação e permissões: as pessoas que o executam devem compreender o risco e dispor apenas dos acessos necessários.
• Cópias de segurança e restauro testado: um backup não é uma estratégia de recuperação se não se conhecerem a sua integridade, âmbito e tempo de restauro.
• Arquitetura: tentativas idempotentes, limites de recursos, timeouts, circuit breakers e isolamento de dependências reduzem a necessidade de intervenções manuais.
• Gestão de alterações: um deployment não equivale a um release. O runbook deve saber que versão está ativa e se uma exposição gradual pode reduzir o risco de reverter.

O objetivo não é documentar todas as falhas possíveis. É padronizar respostas para sinais que têm impacto operacional e para os quais uma decisão incorreta pode piorar o estado do sistema.

Quando um alerta merece um procedimento específico

Nem todo o alerta requer o seu próprio documento. Convém priorizar as situações que combinam frequência, impacto, pressão temporal ou dependência entre equipas. Um alerta merece um runbook quando a reação não deveria depender de recordar passos sob stress.

• Repete-se e costuma exigir as mesmas verificações iniciais.
• Afeta receitas, processos de clientes, cumprimento de prazos ou disponibilidade de uma funcionalidade crítica.
• A ação corretiva só é reversível dentro de uma janela limitada.
• Requer coordenação entre a aplicação PHP, infraestrutura, base de dados ou um fornecedor de API.
• Uma ação manual pode provocar perda, duplicação ou exposição de dados.
• O alerta tem falsos positivos conhecidos que devem ser descartados com evidências concretas.

Comece pelo sintoma observável, não por uma teoria. «Os trabalhos pendentes aumentam», «a latência do endpoint ultrapassa o limiar», «os erros 5xx aumentam» ou «uma integração devolve respostas inválidas» são entradas úteis. «A base de dados está saturada» é uma hipótese que deve ser verificada, não o ponto de partida do procedimento.

A estrutura mínima de um runbook acionável

Um documento operacional útil pode ser lido e executado durante um incidente. Deve evitar frases como «verificar os logs» sem especificar o que procurar, em que intervalo e que resultado altera a decisão.

1. Objetivo e âmbito: descreva o sintoma abrangido, os componentes afetados e os que ficam excluídos. Indique se se aplica a produção, a ambientes específicos ou a um tipo de processo.
2. Sinais de entrada: inclua o alerta, limiares, dashboards relevantes, mensagem de erro e condições que distinguem um alerta real de ruído.
3. Responsável inicial e permissões: especifique quem reconhece o incidente, quem executa as ações e quem autoriza operações de elevado impacto.
4. Riscos e condições de paragem: deixe claro que ações não devem ser realizadas, que dados podem ser afetados e quando escalar sem continuar.
5. Passos e evidências: cada passo deve solicitar uma verificação, registar um resultado esperado e definir o ramo de decisão seguinte.
6. Saída: defina que provas permitem encerrar o incidente e que acompanhamento permanece em aberto depois.

As ligações internas para dashboards, repositórios ou ferramentas podem ser úteis na versão operacional, mas não devem ser o único contexto. Anote que métrica observar, que etiqueta filtrar e que janela temporal utilizar. Se uma ferramenta não estiver disponível, a equipa deve saber que evidência alternativa pode recolher.

Separe diagnóstico, mitigação e recuperação

Uma causa frequente de incidentes prolongados é misturar investigação e alterações. O runbook deve classificar as ações de acordo com o seu nível de risco e a sua finalidade.

Ações seguras e diagnóstico

Reconhecer o alerta, abrir um canal de coordenação, recolher métricas, consultar logs de erros e verificar o estado das dependências costumam ser ações de baixo risco. Ainda assim, devem ter limites: consultas dispendiosas numa base de dados degradada ou pesquisas de logs sem filtro também podem adicionar pressão.

O diagnóstico deve formular hipóteses verificáveis. Por exemplo: se os erros de ligação aumentam e o pool de ligações está esgotado, investiga-se a dependência e o padrão de utilização antes de modificar limites. Se falhar apenas uma versão recentemente exposta, compara-se o seu tráfego e os seus erros com a versão anterior.

Mitigação e recuperação

Mitigar limita o dano sem afirmar que a causa foi corrigida: reduzir a exposição de uma funcionalidade, pausar uma entrada de trabalhos ou aplicar rate limiting são exemplos possíveis. Recuperar devolve o serviço a um estado aceitável: restaurar um consumidor, reverter uma versão ou processar trabalho pendente de forma controlada.

Cada ação deve incorporar um ponto de decisão: que métrica melhora, durante quanto tempo é observada e o que acontece se piorar. Reiniciar um processo PHP pode ser válido como mitigação limitada, mas não deve ser uma instrução automática se existirem tarefas não idempotentes, bloqueios de base de dados ou consumo de memória sem explicação.

Exemplo hipotético: acumulação de trabalhos numa fila PHP

Considere uma aplicação PHP com consumidores que processam notificações, sincronizações ou tarefas de comércio. O alerta indica que o número de trabalhos pendentes aumenta de forma sustentada. O runbook não deve simplesmente ordenar «esvaziar a fila».

1. Confirme o âmbito: meça pendentes por tipo de trabalho, antiguidade da mensagem, taxa de entrada e taxa de processamento. Verifique se o atraso afeta todos os consumidores ou uma rota específica.
2. Reveja a saúde dos consumidores: processos ativos, reinícios, memória, erros de PHP, timeouts e exceções repetidas. Verifique também a conectividade com a fila e as dependências chamadas pelos trabalhos.
3. Classifique a hipótese: entrada anormalmente elevada, capacidade insuficiente, trabalho bloqueado, erro de código, dependência externa lenta ou dados inválidos. Não aumente os consumidores se a dependência de destino já estiver saturada.
4. Defina limites de repetição. As mensagens que falham repetidamente devem ir para uma rota de revisão ou fila de erros quando o design o permitir; repeti-las sem limite pode amplificar o tráfego e duplicar efeitos.
5. Aplique recuperação gradual: restaure ou escale consumidores por etapas, observe a taxa de sucesso e monitorize erros, latência e carga da base de dados. Mantenha uma condição de paragem se o backlog crescer mais depressa ou se as falhas aumentarem.
6. Valide o resultado: verifique que o trabalho antigo diminui, que não existem duplicados, que as operações associadas são consistentes e que o alerta estabiliza durante uma janela definida.

Se os trabalhos produzirem efeitos externos, como cobranças, emails ou alterações de inventário, o runbook deve exigir uma revisão humana antes de reprocessar lotes. A idempotência reduz o risco, mas não deve ser assumida sem evidências do design e dos dados afetados.

Proteja dados sensíveis e operações irreversíveis

Um procedimento que envolve dados pessoais, credenciais, encomendas, pagamentos ou registos regulamentares necessita de controlos adicionais. Não basta que o comando esteja tecnicamente correto.

• Utilize privilégios mínimos e contas separadas para leitura, intervenção operacional e administração.
• Exija dupla confirmação para eliminações, reprocessamentos em massa, restauros ou modificações diretas de dados.
• Registe quem autorizou e executou a ação, que intervalo de dados abrangeu e que resultado obteve.
• Defina uma amostra de validação antes de atuar sobre todo o conjunto.
• Estabeleça uma condição de paragem explícita perante discrepâncias, dados não identificáveis ou efeitos fora do âmbito inicial.

Evite incluir segredos no runbook, logs ou capturas. O documento pode indicar o sistema autorizado para obter credenciais temporárias, mas não deve transformar informação sensível em texto permanente.

Escalonamento e verificação após a recuperação

O escalonamento não é uma falha da equipa que atende o alerta; é uma decisão de controlo de risco. Escale para desenvolvimento quando houver um possível defeito da aplicação, regressão de versão ou comportamento não idempotente. Escale para infraestrutura se existir esgotamento de recursos, rede, armazenamento ou plataforma de execução. Envolva o fornecedor externo quando as evidências apontarem para a sua API ou serviço. Solicite uma decisão de negócio se a mitigação exigir pausar vendas, atrasar comunicações ou aceitar uma ordem de processamento diferente.

Defina também um tempo máximo para cada fase. Se não houver evidências suficientes após o diagnóstico inicial, ou se uma mitigação não melhorar o sinal no intervalo esperado, a pessoa responsável deve escalar em vez de repetir ações.

A recuperação termina quando se verifica mais do que o desaparecimento do alerta:

• O sintoma inicial permanece dentro dos limites durante uma janela de observação.
• O trabalho pendente, as transações e os dados afetados são consistentes.
• Os utilizadores conseguem concluir os fluxos relevantes sem degradação percetível.
• Os alertas relacionados não apresentam efeitos secundários após a alteração.
• Ficam documentadas a cronologia, as hipóteses confirmadas ou descartadas, as ações e as melhorias pendentes.

Reveja o runbook depois de o utilizar. Elimine passos que não forneceram evidências, incorpore decisões que foram necessárias e transforme os resultados recorrentes em melhorias de observabilidade, testes ou arquitetura. Assim, o procedimento deixa de ser documentação estática e torna-se uma ferramenta de recuperação segura.