Como criar uma página de estado: componentes, incidentes e verificações de disponibilidade

Uma página de estado diz aos seus utilizadores, num único lugar, se o serviço está a funcionar. Para a criar, precisa de uma lista de componentes (site, API, pagamentos, envio de email), de um estado atual para cada um, de incidentes com atualizações datadas, de um histórico de incidentes passados e, opcionalmente, de subscrições para que as pessoas fiquem a saber dos problemas sem terem de verificar. A página em si é simples. A decisão importante é onde corre: uma página de estado tem de continuar no ar quando a sua app estiver em baixo, por isso não deve partilhar o alojamento, a base de dados nem o pipeline de publicação com aquilo que reporta.

Para que serve uma página de estado

Quando algo falha, os utilizadores querem saber três coisas: se o problema é só deles, se já sabe e quando fica resolvido. Uma página de estado responde às três sem uma avalanche de pedidos de apoio. Também cria confiança ao longo do tempo, porque um histórico de incidentes visível, com relatos honestos, mostra como lida com os problemas.

Não é um registo de alterações. As novidades vão numa página de registo de alterações; as avarias e as manutenções vão aqui.

O que a página precisa

Dados

Os estados dos componentes costumam ser uma lista curta e fixa: Operacional, Desempenho degradado, Avaria parcial, Avaria grave, Em manutenção.

Páginas

• Página de estado pública: um banner geral (“Todos os sistemas operacionais” ou o pior estado atual), cada componente com o respetivo estado, qualquer incidente ativo com as suas atualizações, manutenções previstas e, se tiver dados de verificação, uma faixa com o histórico dos últimos 90 dias.
• Página de incidente: a linha temporal completa das atualizações de um incidente, com URL próprio para que o apoio ao cliente o possa partilhar.
• Histórico: incidentes passados, por mês.
• Subscrição: inscrição por email com confirmação e preferências por componente.
• Administração: criar um incidente, publicar atualizações, alterar estados dos componentes, agendar manutenções.

Permissões

O público vê tudo o que for publicado. Só a sua equipa pode publicar. Se for possível, mantenha o acesso de administração separado do sistema de login da app principal, para que uma avaria do seu fornecedor de autenticação não o deixe sem acesso à sua própria página de estado.

A decisão-chave: mantê-la independente

É aqui que a maioria das páginas de estado caseiras falha. Se a sua página de estado:

• correr no mesmo servidor ou na mesma conta de alojamento da app,
• ler da mesma base de dados,
• estiver atrás da mesma configuração de domínio ou CDN,
• ou for publicada pelo mesmo pipeline,

então muitas avarias também a derrubam, exatamente quando as pessoas mais precisam dela. Passos práticos:

• Alojamento separado. Um projeto ou fornecedor diferente da app principal.
• Subdomínio próprio, como estado.exemplo.com, apontado separadamente no DNS. Veja como funcionam os domínios e o DNS.
• Dados próprios. Os incidentes ficam no armazenamento da própria página de estado, não na base de dados da app.
• Uma alternativa estática. Algumas equipas tornam a página pública estática e recriam-na a cada atualização, para que quase não haja nada que possa falhar.

Atualizações manuais ou verificações automáticas

Manual (para começar aqui)

A sua equipa publica os incidentes e altera os estados dos componentes à mão, a partir da página de administração. É assim que muitas páginas de estado funcionam na prática, porque um juízo humano (“os pagamentos estão lentos para alguns tipos de cartão”) é mais útil do que um ponto vermelho automático.

Para saber rapidamente dos problemas, use um monitor de disponibilidade externo que verifique a sua app a cada minuto, mais ou menos, e que o alerte por email, SMS ou chat. Muitos serviços de monitorização têm planos gratuitos.

Automático

Automatizar significa que algo verifica regularmente cada componente e atualiza o respetivo estado. Isso exige código que corra num agendamento, a partir do exterior da infraestrutura da app principal. Dois padrões comuns:

• Um monitor externo chama a sua página de estado através de um webhook quando uma verificação falha ou recupera, e a página atualiza o componente.
• Uma tarefa agendada no próprio alojamento da página de estado faz o ping a cada componente e regista o resultado. Verifique como o seu alojamento trata tarefas agendadas antes de depender disto; o nosso guia sobre como correr tarefas em segundo plano explica as opções.

As alterações automáticas podem oscilar (em baixo, em cima, em baixo) numa rede lenta. Exija duas ou três falhas consecutivas antes de mudar um estado, e deixe uma pessoa confirmar antes de anunciar uma avaria grave.

Como escrever atualizações de incidentes

• Publique cedo. “Estamos a investigar relatos de falhas no início de sessão” em poucos minutos vale mais do que uma mensagem perfeita uma hora depois.
• Diga o que os utilizadores notam, e não o que avariou internamente.
• Indique a hora da próxima atualização e cumpra-a.
• Feche com um resumo curto quando estiver resolvido: o que aconteceu, quanto tempo durou e o que vai mudar.

Um primeiro prompt que funciona

Crie uma página de estado independente para a nossa app Parcelio, a alojar separadamente em estado.parcelio.com. Componentes: Site, API de rastreio, Notificações, Pagamentos, cada um com um estado entre Operacional, Desempenho degradado, Avaria parcial, Avaria grave ou Em manutenção. A página pública mostra um banner geral com o pior estado atual, cada componente com o seu estado, os incidentes ativos com atualizações datadas, da mais recente para a mais antiga, as manutenções previstas e uma lista de incidentes passados por mês. Cada incidente tem a sua própria página. Acrescente uma página de administração protegida por palavra-passe para criar incidentes (título, impacto, componentes afetados), publicar atualizações (mensagem e estado: A investigar, Identificado, A monitorizar, Resolvido), alterar os estados dos componentes e agendar manutenções. Acrescente um endpoint POST /api/check-result que aceite o nome de um componente e up/down de um monitor externo, protegido por um token secreto, e que marque um componente como Degradado apenas após três falhas consecutivas. Guarde tudo na base de dados desta app. Design simples e calmo que carregue depressa em telemóveis.

Passos de construção

1. Página pública e administração com incidentes manuais. Isto já é uma página de estado a funcionar.
2. Alojá-la separadamente e apontar um subdomínio para ela.
3. Páginas de incidentes e histórico.
4. Janelas de manutenção.
5. Subscrições. Inscrição por email com confirmação dupla e notificações sobre novos incidentes e atualizações. O email precisa de um fornecedor; veja como enviar emails a partir da sua app.
6. Webhook de monitorização, se quiser alterações de estado automáticas.
7. Faça um teste. Crie um incidente falso, publique atualizações, resolva-o, verifique os emails e depois apague-o.

Erros comuns

• Alojá-la junto com a app. O erro mais comum e também o mais grave.
• Uma página que diz sempre “Todos os sistemas operacionais”. Se nunca mostra problemas, os utilizadores deixam de confiar nela.
• Sem datas nem fuso horário. Mostre sempre as horas com o respetivo fuso.
• Depender do login da app principal para a página de administração.
• Silêncio entre atualizações. “Sem novidades, continuamos a trabalhar nisto” é uma atualização válida.
• Estados automáticos instáveis. Exija falhas repetidas antes de qualquer mudança.

Quando um serviço de página de estado pronto é a melhor escolha

Os serviços de páginas de estado alojados foram pensados para o problema da independência: correm em infraestrutura separada, tratam das notificações aos subscritores por email e SMS e costumam incluir monitorização e integrações com ferramentas de gestão de incidentes. Se a disponibilidade faz parte do que os seus clientes pagam, ou se tem obrigações contratuais de reportar incidentes, um serviço dedicado compensa normalmente. Muitos têm planos gratuitos ou de baixo custo para pequenas equipas, por isso veja antes de construir.

Construa a sua própria quando quiser controlo total do design e da redação, quando as suas necessidades forem simples (poucos componentes, atualizações manuais) ou quando a página de estado fizer parte de um produto que está a criar para outros.

Como fazer isto com a Mythex

Na Mythex pode construir a página de estado como um projeto próprio, separado da app principal, o que lhe dá alojamento separado e uma base de dados própria. Descreva-a no chat, verifique-a na pré-visualização em direto, depois publique-a e ligue um subdomínio como estado.o-seu-dominio.com (os domínios personalizados estão incluídos no plano Pro). Tenha em conta que as apps publicadas na Mythex e as suas bases de dados entram em repouso quando estão inativas e acordam na visita seguinte, por isso o primeiro carregamento após um período sem uso pode ser mais lento; uma página simples e leve ajuda.

A Mythex não documenta tarefas agendadas, por isso, para verificações automáticas, use um monitor de disponibilidade externo que chame um endpoint de webhook na sua página de estado (veja a receita de webhooks). Os alertas por email para os subscritores passam pelo seu próprio fornecedor, com a chave guardada como segredo do projeto (receita de envio de email).

Perguntas