Gatus: how to monitor APIs and publish a status page without complication

O que é Gatus

Gatus é uma ferramenta open source para monitorar serviços e endpoints. Ela executa verificações periódicas e apresenta os resultados em uma status page.

O projeto resolve uma necessidade comum de equipes pequenas: acompanhar APIs, páginas e integrações sem montar uma plataforma inteira de observabilidade. A configuração fica em arquivo e pode ser revisada junto do código.

O Gatus é mantido no GitHub pela organização TwiN. Seu foco é oferecer uma visão simples de disponibilidade, com histórico e alertas para falhas e recuperações.

Como funciona

O Gatus lê um arquivo de configuração, agenda verificações e testa cada endpoint no intervalo definido. Para uma API, o teste pode conferir código HTTP, tempo de resposta e conteúdo.

Cada resultado vira um evento de disponibilidade. Quando uma regra falha, o sistema pode notificar um canal configurado. Quando o serviço volta a responder, uma nova notificação informa a recuperação.

Pense em cada endpoint como uma sentinela com uma regra própria. Todas as sentinelas aparecem na mesma página, o que ajuda a separar uma falha isolada de um problema maior.

Principais recursos

O recurso central é o monitoramento de endpoints HTTP. Você pode validar respostas, cabeçalhos e conteúdo, indo além da simples abertura de uma porta.

A status page mostra o estado dos serviços e pode ser usada pelo time técnico ou publicada para clientes, desde que os nomes e detalhes exibidos sejam adequados.

O sistema de alertas permite enviar avisos para canais configurados. A configuração versionável também facilita revisar mudanças por pull request.

• Verificações periódicas de APIs e páginas.
• Histórico visual de disponibilidade.
• Alertas de falha e recuperação.
• Configuração declarativa em arquivo.

Como começar: instalação ou acesso passo a passo

A forma mais simples de experimentar o Gatus é usar a imagem do projeto. Crie uma pasta para a configuração e mantenha o arquivo sob controle de versão.

Depois, defina um endpoint inicial. O exemplo abaixo monitora uma página pública e exige uma resposta HTTP bem-sucedida.

Por fim, inicie o contêiner apontando para a configuração e abra a porta local.

mkdir gatus
cd gatus
mkdir config

endpoints:
  - name: CuritibaBlog
    group: sites
    url: https://curitibablog.com.br
    interval: 60s
    conditions:
      - [STATUS] == 200
      - RESPONSE_TIME < 2s

Docker run --rm -p 8080:8080   -v ${PWD}/config:/config   twinproduction/gatus

Exemplo prático

Imagine uma aplicação com uma API pública e uma rota de autenticação. Um teste superficial pode retornar 200 mesmo quando a resposta está incompleta.

Combine status, tempo e conteúdo para representar uma experiência mínima do usuário. Assim, o alerta fica mais útil do que um simples teste de porta.

Uma configuração de exemplo pode exigir que a rota de saúde retorne o texto esperado.

endpoints:
  - name: API principal
    group: produção
    url: https://api.exemplo.com/health
    interval: 30s
    conditions:
      - [STATUS] == 200
      - [BODY] == "ok"
      - RESPONSE_TIME < 1s

Comparação com alternativas

O Uptime Kuma oferece uma interface visual e vários tipos de monitor. Ele pode ser confortável para quem prefere configurar tudo pelo navegador.

Prometheus com Alertmanager é mais amplo para métricas e regras, especialmente quando a equipe já usa exporters e dashboards. Em troca, exige mais componentes.

Serviços hospedados reduzem a manutenção, mas podem gerar custo recorrente. O diferencial do Gatus é manter uma configuração simples, legível e próxima do código.

Pontos positivos e limitações

Entre os pontos positivos estão a configuração declarativa, a execução leve e a revisão por pull request. Isso combina com equipes que tratam infraestrutura como código.

A status page pronta economiza tempo, pois você não precisa criar uma aplicação de frontend separada para mostrar o estado básico dos serviços.

A limitação é que o Gatus não substitui métricas, logs e rastreamento distribuído. Para investigar consumo, consultas lentas ou chamadas encadeadas, você precisará de outras ferramentas.

Casos de uso reais

Uma pessoa desenvolvedora pode monitorar frontend, API e serviços gerenciados de um projeto pessoal. A página mostra rapidamente qual camada precisa de atenção.

Uma pequena empresa pode publicar uma página de status para informar clientes. O time mantém as regras em um repositório e revisa cada alteração.

Em um pipeline de entrega, o Gatus pode funcionar como verificação contínua depois do deploy. Ele também serve para acompanhar painéis internos e endpoints de terceiros.

Dicas e boas práticas

Use intervalos diferentes para serviços críticos e secundários. Monitorar tudo a cada poucos segundos pode aumentar ruído sem melhorar a decisão.

Nomeie os endpoints pelo serviço e pelo ambiente. Produção, homologação e desenvolvimento não devem parecer iguais na tela de incidentes.

Evite testar rotas que alteram dados. Prefira endpoints idempotentes e dados controlados, principalmente quando o monitoramento roda muitas vezes ao dia.

Vale a pena?

O Gatus vale a pena para quem quer monitorar APIs e sites com configuração pequena, versionável e fácil de compartilhar.

Ele não é a escolha única para observabilidade completa. Times que precisam de métricas detalhadas, logs centralizados e tracing devem tratá-lo como peça complementar.

O próximo passo é colocar uma aplicação em teste, observar os resultados por alguns dias e só depois adicionar alertas e serviços críticos.