Boas práticas de resposta a incidentes para devs solo

Boas práticas de resposta a incidentes

As melhores práticas de resposta a incidentes foram escritas para equipas empresariais, não para devs solo. Você lança um side project, encontra utilizadores, e uma manhã alguém tuíta que o serviço está sem funcionar há três horas. Você nem sabia. Sem alertas. Sem runbook. Sem status page.

Esse é o modo de falha para 90% dos produtos construídos por uma pessoa só. Não é uma violação de segurança, não é um evento catastrófico de infraestrutura, apenas: ninguém te avisou que estava quebrado, não tinhas um plano, e os teus utilizadores souberam antes de ti.

Isto não requer um manual de 40 páginas ou uma stack de ferramentas empresariais. Requer três coisas: saber quando algo quebrou, saber o que fazer com isso, e comunicar o estado a quem se importa. Este guia cobre cada uma a partir da perspetiva de um builder, incluindo o que construir tu mesmo e o que juntar de ferramentas existentes.

O que quebra em primeiro lugar quando estás sozinho em on-call

O primeiro incidente que geres sozinho, vais gastar 12 minutos a descobrir onde as coisas estão antes de gastar 4 minutos a resolvê-las.

É esse o custo real. Não é o tempo de inatividade. É a sobrecarga de coordenação de uma equipa de uma pessoa que não escreveu nada. Onde estão as variáveis de ambiente? Qual é o serviço que realmente falhou? É que isto afeta todos os utilizadores ou apenas um cliente? Gastas a janela dourada de um incidente à procura de respostas que devias ter pré-respondido.

A solução não é ferramentas complexas. É ter respondido a essas perguntas antes das 3 da manhã.

Existe um teste útil: imagina que a tua API de produção cai neste momento. Tens 10 minutos. Consegues encontrar os logs relevantes, identificar o componente a falhar, e fazer rollback ou hotfix sem abrir mais de duas abas que já não tinhas abertas? Se a resposta é não, é exatamente isto que a resposta a incidentes resolve.

As três coisas que qualquer setup de resposta a incidentes indie realmente precisa

Antes de construires nada, nomeia o que o sistema tem de fazer:

• Detetar o problema antes de um utilizador te enviar uma mensagem sobre isso

• Dizer-te o que fazer quando estás meio adormecido e tens contexto apenas do alerta

• Dizer aos teus utilizadores o que está a acontecer sem piorar

Todas as ferramentas de resposta a incidentes, desde PagerDuty até à tua cron job pessoal, mapeiam para um destes três trabalhos. Constrói a versão mais simples que faça os três, depois para.

A tentação é construir em direção à versão empresarial: horários de on-call, políticas de escalação, níveis de severidade P0 até P5, templates de postmortem. Isto é apropriado em 20 engenheiros e 500K utilizadores. Com um dev e 500 utilizadores, essas abstrações queimam os teus fins de semana e ficam por usar. A versão mínima é viável este fim de semana. Lança isso primeiro.

Construir a tua camada de alerta: o problema dos falsos positivos vem em primeiro lugar

Cada dev que construiu os seus próprios alertas tem a mesma história: a primeira regra que escreveu era errada, e desligou o pager após duas semanas de ruído.

Começa com uma verificação que importa. Um endpoint de health check a falhar é suficiente.

# Endpoint de health check simples (Express/Node)
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: Date.now() });
});

Depois liga uma cron job para fazer ping cada 60 segundos. Se falhar três vezes seguidas, recebe uma mensagem de texto. Essa é a tua primeira camada de alerta. Apanha 80% dos incidentes que afetam utilizadores.

A taxa de falsos positivos neste setup é próxima de zero. Recebés um alerta quando o serviço realmente está em baixo, não quando um pico de CPU acionou um threshold que nunca foi calibrado. É a coisa mais difícil de acertar em alertas: o alerta tem de ser verdadeiro, sempre, senão treinas-te a ignorá-lo.

Alerta baseado em logs vem depois de a verificação de uptime estar funcionando e confiável. Para stacks auto-alojadas, Grafana funciona bem a custo mais baixo. Datadog começa a fazer sentido quando estás a gerir mais de dois ou três serviços e queres uma vista unificada com integração fácil no teu pipeline de deployment.

Runbooks são o documento que escreves às 23h para leres às 3 da manhã

Um runbook não é documentação. A documentação explica como algo funciona. Um runbook diz à versão futura de ti, que está stressada, meio adormecida e sob pressão, exatamente o que fazer neste momento.

O formato que funciona para projetos solo:

• O que está quebrado? Uma frase, apenas sintomas observáveis

• É urgente? Afeta clientes pagadores neste momento?

• O que faço? Três a cinco passos numerados, começando pela coisa mais rápida de tentar primeiro

É só. Escreve quando não estás num incidente. Revê e atualiza após um incidente para ver se realmente foi útil.

Onde armazenas runbooks importa menos do que o hábito de os escrever. Uma página Notion, um ficheiro Markdown no teu repo, um documento partilhado. O teste: consegues abrir no telemóvel em 30 segundos, meio adormecido, às 3 da manhã?

O argumento prático de Notion sobre um ficheiro de repo é o acesso móvel. Se dormes perto do telemóvel porque tens tráfego de produção e um mau presságio sobre um deploy que lançaste, isso importa. GitBook é outra opção sólida se preferes algo mais estruturado que funciona como documentação pública de dev.

Construir uma status page pública: o que os utilizadores realmente querem quando as coisas quebram

Os teus utilizadores não precisam de um dashboard de observabilidade em tempo real. Precisam saber duas coisas: está quebrado para todos, e tens conhecimento disso?

A status page minimamente viável tem três elementos:

• Um indicador de estado com no máximo três estados: operacional, degradado, em baixo

• Um timestamp para quando o estado atual foi atualizado pela última vez

• Uma linha de português simples quando algo está errado

Utilizadores a verificar uma status page durante um incidente não estão a ler diagramas de arquitetura. Querem deixar de resolver a sua própria setup porque agora sabem que não é culpa deles.

Construir isto demora menos de quatro horas:

1. Uma página HTML estática com um snippet JavaScript que busca estado de um endpoint

2. Uma tabela Supabase com dois campos: status (enum) e message (texto)

3. Uma cron job que atualiza o status baseada no resultado da verificação de health

4. Um endpoint admin atrás de autenticação para escrever uma mensagem manual quando necessário

A parte difícil não é a construção. É o hábito de a atualizar durante um incidente em vez de mergulhares direto na correção. A atualização demora 30 segundos e poupa 15 e-mails de suporte ao cliente.

O outro argumento de construir isto tu mesmo: ferramentas comerciais de status page cobram 30 a 100 dólares por mês por aquilo que é fundamentalmente um endpoint JSON e uma página HTML estática. Constrói uma vez, é teu. Os teus utilizadores não precisam de Statuspage.io. Precisam de um URL que continua a funcionar quando o teu domínio principal cai.

Post-mortems quando és a única pessoa a culpar

Post-mortems em ambientes empresariais são sobre não culpar indivíduos e identificar falhas sistémicas. Solo, és tu o sistema. A psicologia é diferente, mas a prática continua a importar.

A razão de escrever post-mortems sozinho: vais resolver a mesma classe de problema duas vezes se não o fizeres. Três meses depois vais estar a olhar para uma query de base de dados que bloqueou porque não adicionaste um índice, e terás uma memória vaga de ter resolvido algo assim antes, mas não te lembras como.

Um formato de cinco minutos que aguenta:

1. O que aconteceu (um parágrafo, apenas factos, sem linguagem de culpa)

2. O que fizeste para o resolver

3. Uma coisa a mudar no sistema

4. Uma coisa a mudar no teu processo

Escreve no mesmo lugar que os teus runbooks. Torna-se na entrada para a próxima atualização de runbook. Ao longo de seis meses, isto cria um registo leve dos modos de falha do teu sistema que nenhuma ferramenta empresarial de postmortem replica para um builder solo.

Deves construir isto ou juntar ferramentas existentes?

A resposta honesta depende de onde estás.

Se tens zero clientes pagadores: constrói tudo tu mesmo. Cron de health check, status page, runbooks em Notion. Este é o projeto certo para aprender os padrões. Funciona num fim de semana. Ensina-te o que a resposta a incidentes realmente requer. E se decidires mais tarde construir e vender como produto, validaste os requisitos em ti próprio primeiro.

Se tens clientes pagadores que dependem de uptime hoje: começa com ferramentas existentes. Liga a Grafana Cloud tier gratuito, configura um monitor de uptime, abre uma página de runbook em Notion esta tarde. Precisas de cobertura agora, não depois de três fins de semana a construir.

A peça que vale a pena construir tu mesmo independentemente do estágio: a status page. É tua, aloja-a num domínio separado, constrói-a este fim de semana. Tudo o resto podes juntar de tier gratuito de ferramentas existentes até a complexidade justificar construir.

A lacuna que nenhum guia de resposta a incidentes fala

O problema não é as ferramentas. É as 48 horas entre deveria configurar alertas e configurei realmente os alertas.

A maioria dos stacks de dev solo têm primitivas de observabilidade suficientes para construir uma primeira camada de resposta a incidentes num único dia. O endpoint de health check existe em algum lado. Os logs estão em algum lado. O pipeline de deploy tem algum tratamento de erro. O que falta é 90 minutos de ligação focada: health check para monitor de uptime, monitor de uptime para alerta SMS ou Telegram, uma página Notion com três runbooks, página estática com endpoint de status Supabase.

Isto não é o projeto que lanças aos utilizadores. É o projeto que lanças para ti.

Constrói isto este fim de semana. A primeira vez que algo quebra às 3 da manhã e gastas 4 minutos a resolvê-lo em vez de 40 minutos a descobri-lo, vais entender porque é que as melhores práticas de resposta a incidentes existem. Não porque equipas empresariais as mandataram, mas porque a alternativa é pior.