Endpoint de Verificação de Integridade da Instância Mastodon: Como Monitorar com Uptime Kuma

Você quer saber se sua instância Mastodon está acessível e respondendo a requisições sem precisar fazer login manualmente a cada hora. O Mastodon oferece um endpoint público de verificação de integridade que retorna uma resposta JSON simples quando o servidor está funcionando corretamente. Este artigo explica o que o endpoint de verificação de integridade faz, como configurar o Uptime Kuma para monitorá-lo e o que fazer quando o endpoint indica um problema.

As instâncias Mastodon expõem um caminho /health que retorna HTTP 200 e um objeto JSON vazio se o servidor web e o banco de dados estiverem operacionais. O Uptime Kuma é uma ferramenta de monitoramento auto-hospedada que pode consultar esse endpoint a cada poucos segundos e alertá-lo quando o status mudar. Ao combinar essas duas ferramentas, você pode detectar indisponibilidade, respostas lentas ou erros de configuração antes que eles afetem seus usuários.

O guia a seguir cobre a especificação do endpoint de verificação de integridade, a configuração passo a passo do Uptime Kuma e as armadilhas comuns de monitoramento a serem evitadas.

Por que o Endpoint de Verificação de Integridade do Mastodon Existe

Mastodon é uma aplicação Ruby on Rails que depende de um banco de dados PostgreSQL e de um processador de tarefas em segundo plano Sidekiq. O endpoint /health é uma verificação leve que confirma se a aplicação Rails consegue conectar ao banco de dados e retornar uma resposta. Ele não verifica se o Sidekiq está em execução, se os arquivos de mídia estão acessíveis ou se a federação está funcionando.

O endpoint é intencionalmente mínimo. Ele evita autenticação porque ferramentas de monitoramento como o Uptime Kuma precisam verificá-lo sem armazenar credenciais. Uma resposta bem-sucedida significa que o servidor da aplicação e o banco de dados estão ativos. Uma resposta com falha pode indicar um servidor web travado, exaustão do pool de conexões do banco de dados ou uma implantação que não foi concluída.

Especificação do Endpoint

O endpoint de verificação de integridade está localizado em https://suainstancia.exemplo.com/health. A resposta tem estas propriedades:

• Código de status HTTP: 200 em caso de sucesso, 500 ou 503 em caso de falha.
• Content-Type: application/json.
• Corpo: {} em caso de sucesso. Em caso de falha, o corpo pode estar vazio ou conter uma mensagem de erro.

O endpoint não requer cabeçalhos, parâmetros de consulta ou tokens de autenticação. O Uptime Kuma pode monitorá-lo com uma simples requisição GET.

Passos para Configurar o Uptime Kuma para Monitoramento de Integridade do Mastodon

Estas instruções pressupõem que você tenha o Uptime Kuma instalado e acessível. Se ainda não o instalou, implante-o em um servidor ou máquina local usando Docker ou Node.js. As etapas abaixo usam a interface web do Uptime Kuma versão 1.23 ou posterior.

1. Faça login no Uptime Kuma e adicione um novo monitor
   Abra o painel do Uptime Kuma em um navegador. Clique no botão Adicionar Novo Monitor no canto superior direito. Um formulário de configuração aparecerá.
2. Selecione o tipo de monitor HTTP(s)
   No menu suspenso Tipo de Monitor, escolha HTTP(s). Isso informa ao Uptime Kuma para enviar uma requisição HTTP GET para a URL fornecida.
3. Insira a URL de verificação de integridade da instância Mastodon
   No campo URL, digite https://suainstancia.exemplo.com/health. Substitua suainstancia.exemplo.com pelo domínio real da sua instância Mastodon. Não inclua nenhum caminho após /health.
4. Configure o intervalo de verificação
   Defina o Intervalo para 60 segundos ou mais. Um intervalo de 60 segundos equilibra detecção rápida com carga no servidor. Para instâncias de produção, 120 segundos também é aceitável.
5. Defina o código de status HTTP esperado
   Mantenha o Código de Status Esperado no valor padrão 200. O Uptime Kuma tratará qualquer resposta diferente de 200 como uma falha.
6. Ative a validação do certificado SSL, se necessário
   Marque a caixa Verificar Certificado se quiser que o Uptime Kuma verifique se o certificado SSL é válido e não expirou. Isso é opcional, mas recomendado para instâncias de produção.
7. Adicione canais de notificação
   Role até a seção Notificação. Clique em Configurar Notificação e escolha seu método de alerta preferido. Por exemplo, selecione Telegram Bot e insira o token do bot e o ID do chat. Você pode adicionar vários canais de notificação.
8. Salve o monitor
   Clique no botão Salvar na parte inferior. O Uptime Kuma começa imediatamente a consultar o endpoint de integridade. O painel mostra um indicador de status verde se a verificação for bem-sucedida.

Armadilhas Comuns de Monitoramento e Como Evitá-las

A verificação de integridade retorna 200, mas a instância não está atendendo usuários

O endpoint /health verifica apenas a aplicação e o banco de dados. Ele não verifica Sidekiq, proxy de mídia ou federação. Se o Sidekiq parar de processar tarefas, novas postagens e notificações não aparecerão, mesmo que a verificação de integridade seja bem-sucedida. Para detectar isso, adicione um segundo monitor que verifique o endpoint /api/v1/instance e valide se o corpo da resposta contém campos esperados como uri e title. Defina o código de status esperado como 200 e, opcionalmente, adicione uma verificação de palavra-chave para "uri":.

O monitor mostra indisponível, mas a instância está acessível pelo navegador

Isso geralmente acontece quando o Uptime Kuma não consegue resolver o domínio da instância ou o caminho de rede está bloqueado. Verifique se o servidor do Uptime Kuma consegue resolver o domínio usando nslookup suainstancia.exemplo.com. Se o Uptime Kuma estiver atrás de um firewall corporativo, certifique-se de que o tráfego HTTPS de saída para a porta 443 seja permitido. Verifique também se a instância não está limitando a taxa do IP do Uptime Kuma. Adicione o IP do Uptime Kuma à lista de permissões da instância, se necessário.

Alertas do Uptime Kuma são muito frequentes

Uma única verificação de integridade com falha pode disparar um alerta mesmo que a instância se recupere imediatamente. Para reduzir ruídos, defina o Intervalo de Repetição no Uptime Kuma para 2 ou 3. Isso significa que o monitor deve falhar várias verificações consecutivas antes de enviar um alerta. Vá para as configurações do monitor, expanda Configurações Avançadas e defina Intervalo de Repetição como 2. Aumente também o Intervalo para 120 segundos para evitar falsos positivos devido a oscilações de rede temporárias.

Item	Apenas endpoint de integridade	Monitoramento do endpoint de integridade + API
Cobertura	Apenas servidor da aplicação e banco de dados	Aplicação, banco de dados, disponibilidade da API e metadados da instância
Risco de falso positivo	Baixo — endpoint é simples	Médio — a API pode falhar devido a cache ou limites de taxa
Complexidade de configuração	Um monitor no Uptime Kuma	Dois monitores com verificações de palavra-chave
Precisão do alerta	Perde falhas do Sidekiq e de mídia	Captura mais modos de falha

O endpoint de verificação de integridade do Mastodon fornece um sinal confiável para disponibilidade básica do servidor. Para cobertura completa, combine-o com um monitor de endpoint da API que valide o conteúdo da resposta. O Uptime Kuma suporta verificação de palavras-chave no corpo da resposta, o que permite confirmar se a instância está retornando os dados esperados. Comece com o endpoint de integridade e adicione a verificação da API após a primeira semana de monitoramento para ajustar os limites de alerta.

Quando a verificação de integridade falhar, investigue os logs do servidor Mastodon em /var/log/mastodon/ ou o journal do systemd usando journalctl -u mastodon-web. Causas comuns incluem disco cheio, pool de conexões do banco de dados esgotado ou um processo Puma obsoleto que precisa ser reiniciado. Após corrigir o problema, o endpoint de integridade deve retornar 200 dentro de um intervalo de consulta.