Este guia percorre as decisões por trás da página de status de um SaaS: o que listar nela, quando um monitor de disponibilidade deve considerar algo uma queda, como redigir as atualizações de um incidente e onde a página deve ficar. O exemplo prático é a página de status com monitores de disponibilidade que acabei de adicionar ao Kookee, e as capturas de tela vêm do Lumen, o produto fictício de análise de dados do meu projeto de demonstração. Um desses monitores foi posto à prova antes do previsto: enquanto fazia as capturas, desliguei por engano o portal do projeto de demonstração, e os dois monitores dele perceberam 68 e 78 segundos depois.
O que vai numa página de status
Uma página de status útil tem quatro partes:
as partes do seu produto, cada uma com o status de agora;
os incidentes em aberto, com o que você sabe até o momento;
as manutenções planejadas, antes de começarem;
o passado recente: os incidentes dos últimos meses e quanto desse tempo cada parte ficou no ar.
Acima delas, uma linha resume a página inteira, para que o visitante que só quer saber se o problema está do lado dele possa parar de ler ali. A página do Kookee diz Todos os sistemas funcionando normalmente, Interrupção leve do serviço, Interrupção grave ou Manutenção em andamento, conforme os componentes e os incidentes em aberto.
Dê aos componentes os nomes que os clientes usam
Um componente é algo que o cliente consegue comparar com o que está vendo. O Lumen lista Dashboards, Data ingestion, Public API, Email reports e Help center. Não lista os workers de fila nem o banco de dados, porque ninguém fora da equipe sabe o que eles fazem. Na captura acima, o incidente fictício do Lumen aponta Email reports como componente afetado, e mais abaixo na página esse componente aparece como Desempenho degradado. Um cliente que não recebeu um relatório agendado consegue relacionar isso ao que vê.
O Kookee permite 10 componentes no plano gratuito e 50 no Pro. Cada um ganha uma barra por dia, colorida pelo pior status que teve naquele dia: 90 dias numa tela larga, os últimos 30 no celular e nenhum se você desligar Mostrar disponibilidade.
Decida quando um site está mesmo fora do ar
Um monitor de disponibilidade acessa uma URL em intervalos regulares e precisa decidir quando uma falha é uma queda. A regra do Kookee são três verificações com falha seguidas. Quando uma verificação falha, o monitor verifica de novo 20 segundos depois, então as três falhas levam uns 40 segundos em qualquer intervalo, ou mais se cada verificação esperar até o tempo limite. O intervalo só decide quando vem a primeira falha: no Pro e no Ultra um monitor pode verificar a cada minuto; no plano gratuito, o intervalo mínimo é de cinco minutos. Uma única verificação com falha não dispara nada, e duas verificações bem-sucedidas seguidas trazem o monitor de volta ao ar.
Foi assim quando desliguei o portal de demonstração. O portal saiu do ar às 08:02:36 UTC. Os monitores declararam a queda às 08:03:44 e às 08:03:54, cada um depois de três 404, e o que vigia a central de ajuda abriu um incidente em rascunho, “Help center is down”. O portal voltou às 08:04:18, os monitores voltaram ao ar às 08:05:24 e às 08:05:34, e o rascunho foi resolvido sozinho, sem nunca chegar à página pública. A queda que cada monitor registrou durou mais ou menos o mesmo que a real e veio cerca de um minuto atrasada nas duas pontas: é o custo de confirmar antes de declarar a queda.
Mais algumas regras decidem se dá para confiar no monitor. Um monitor que nunca teve uma verificação bem-sucedida só alerta a sua equipe, porque um erro de digitação na URL não deve mostrar aos seus clientes uma queda que nunca aconteceu. Depois que ele já esteve no ar, um monitor fora do ar marca o componente como Interrupção grave, qualquer que seja o resto da configuração, e assim a página não pode dizer Operacional enquanto a verificação falha. E, se o componente estiver em manutenção planejada, o monitor segura a queda até o fim da janela.
O que acontece depois você escolhe para cada monitor: Só alertar, Abrir um incidente em rascunho ou Publicar um incidente na hora. Um rascunho entrega um incidente pronto para você conferir e reescrever antes de ele ir ao ar. Publicar na hora serve para uma URL cuja falha sempre significa clientes afetados, como o health check da sua API.
Escreva atualizações que respondam ao que o cliente pergunta
Um incidente é um título e uma série de atualizações. Cada atualização tem um status, e o Kookee limita os status de incidente a quatro: Investigando, Identificado, Monitorando e Resolvido. O título deve nomear o que os clientes percebem (“Os painéis carregaram devagar”), não a causa.
Cada atualização deve responder ao que o cliente perguntaria em seguida. No incidente resolvido do Lumen, logo abaixo, a primeira atualização diz o que foi afetado, com um número: “Alguns painéis levam mais de 20 segundos para carregar.” Identificado traz a causa assim que ela é conhecida: “A versão desta manhã mudou a forma como os gráficos de funil grandes são consultados.” Monitorando diz o que a equipe acompanha antes de dar o problema por resolvido: “Vamos acompanhar os tempos de carregamento na próxima hora.” O incidente dos relatórios por e-mail, lá em cima, acrescenta a outra coisa que os clientes perguntam, se algo se perdeu: “Os relatórios atrasados ainda serão enviados, e nenhum se perdeu.”
No Kookee, cada atualização também define o status de cada componente que ela envolve, então uma única atualização muda ao mesmo tempo o incidente e a lista de componentes.
Anuncie a manutenção antes de ela começar
No Kookee, uma janela de manutenção fica pública assim que você a agenda, em Próximas manutenções. Ela fica em andamento entre o início e o fim, e seus componentes aparecem como Em manutenção. Depois ela é concluída, sem que ninguém precise iniciá-la ou encerrá-la à mão. Diga o que os clientes podem notar e por quanto tempo, como faz a manutenção Database upgrade do Lumen: “Os painéis e a API podem responder devagar por até 15 minutos durante a janela.”
Como o Kookee calcula a disponibilidade
O Kookee conta como indisponibilidade só o tempo em Interrupção grave. Desempenho degradado e interrupções parciais colorem a barra do dia, mas não baixam o número. A porcentagem cobre 90 dias e começa quando o componente foi adicionado, então os dias anteriores ficam cinza, não verdes. Ela é arredondada para baixo: 99,996% aparece como 99,99%, nunca como 100,00%.
Hospede a página longe do que ela monitora
Uma página de status servida pelo sistema que ela descreve cai junto com ele. A página hospedada do Kookee fica em <your-project>.kookee.dev/status, separada dos seus servidores. Se você a quiser no seu próprio domínio, a mesma página é montada com @kookee/react/status: StatusHeadline e StatusOverview para a página, StatusIncidentArticle para cada incidente. Sirva a página de outro lugar que não o app que ela monitora, como uma hospedagem estática, e deixe o navegador ler o status na API do Kookee:
import { useStatus } from '@kookee/react';
import { StatusHeadline, StatusOverview } from '@kookee/react/status';
const { data: status } = useStatus({ refreshSeconds: 60 });
if (!status) return null;
<StatusHeadline status={status} />
<StatusOverview status={status} incidentHref="/status/incidents/{id}" />As leituras de status não contam para o seu limite mensal de requisições à API. Em qualquer um dos quatro modelos prontos do Kookee, KOOKEE_STATUS=true adiciona /status e uma página por incidente. O mesmo limite vale para o Kookee: a página e os componentes leem da API do Kookee, então, se essa API cair, eles também não carregam.
Configure no Kookee
Abra Página de status, vá até a aba Componentes e clique em Adicionar componente para cada parte que os clientes veem.
Abra Monitor de disponibilidade, clique em Adicionar monitor, informe a URL, escolha o Intervalo de verificação e o Componente, e defina o que acontece Quando ficar fora do ar.
Abra Portal público, ligue Ativar o portal público se estiver desligado e marque Página de status em Módulos do portal.
De volta à Página de status, clique em Ver página de status.
Configure uma página de status cobre incidentes e manutenções, e Monitore seu site com verificações de disponibilidade explica cada configuração do monitor.
O que a página de status do Kookee ainda não faz
Os visitantes não podem assinar atualizações por e-mail ou RSS. Não há alertas por SMS nem escalas de plantão, os monitores só fazem verificações HTTP e HTTPS, e não há páginas de status privadas. A página hospedada não pode ter um domínio próprio; os componentes React são o caminho para colocá-la no seu.
Perguntas frequentes
A página de status é gratuita? Sim. Todos os planos têm a página de status e os monitores de disponibilidade. O plano gratuito tem 10 componentes e 3 monitores, com intervalo mínimo de 5 minutos entre as verificações; o Pro tem 50 componentes e 20 monitores, que podem verificar a cada minuto.
Quem fica sabendo quando um monitor sai do ar? Os proprietários e administradores do projeto, no Kookee e por e-mail. Webhooks podem receber um evento monitor.down, e no Pro e no Ultra as integrações com Slack, Discord e Telegram podem publicá-lo no canal da sua equipe.
Um assistente de IA pode publicar incidentes? Sim. Pelo servidor MCP do Kookee, um assistente com acesso de escrita pode ler o status e criar, atualizar e resolver incidentes.
Continue lendo
Configure uma página de status: cada passo no Kookee, dos componentes às manutenções.
Mostre sua página de status no seu próprio site: os componentes React, a API e os modelos prontos.
Seus webhooks não deveriam confiar na URL que receberam: por que um servidor que chama URLs de clientes precisa verificar para onde elas apontam.