Health checks para projetos HTTP

O health check permite que a Zenifra confirme se uma aplicação HTTP está pronta para receber tráfego. A verificação chama uma rota GET da aplicação em intervalos regulares. Quando uma falha é confirmada, a instância é reiniciada automaticamente para tentar recuperar o serviço.

O recurso é opcional por projeto e depende do plano contratado. Ele foi criado para aplicações que precisam de uma validação contínua além da publicação inicial. Para entender o fluxo completo, consulte Implantação e Como criar um projeto HTTP.

Verifique se o plano inclui o recurso

O catálogo de planos (GET /v1/project/plans) informa em capabilities.healthcheck se o plano disponibiliza health checks para projetos HTTP. Hoje o recurso está incluído a partir do plano Premium. No catálogo, procure por:

{
  "plan": "premium",
  "capabilities": {
    "healthcheck": true
  }
}

Quando o valor é false, a opção não fica disponível para ativação. Projetos em planos sem o recurso continuam funcionando normalmente, sem health check.

A disponibilidade do health check vem do plano: o projeto só pode ativá-lo quando o plano inclui o recurso. Se você precisa desse recurso e não vê a opção no Console, verifique o plano atual ou fale com o responsável pela organização.

Configure uma rota GET

Crie uma rota simples na aplicação, como /health, e faça com que ela retorne um status HTTP entre 200 e 299 quando a aplicação estiver pronta. O caminho deve começar com / e não pode conter domínio, query string ou fragmento.

Exemplo em Node.js:

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' })
})

Uma resposta 204 No Content também é válida quando a aplicação não precisa enviar um corpo. Não use redirecionamentos como resposta de sucesso: o health check considera somente respostas 2xx como saudáveis.

A rota deve responder rapidamente e evitar dependências desnecessárias. Se a aplicação depende de um banco ou de outro serviço para funcionar, faça uma validação curta e previsível, sem executar consultas pesadas nem expor segredos na resposta.

Na configuração do projeto, o recurso equivale a:

{
  "healthcheck": {
    "enabled": true,
    "path": "/health"
  }
}

O intervalo de verificação é fixo em 1 minuto. Timeout e quantidade de tentativas são definidos pela Zenifra e não são configuráveis nesta versão.

Entenda o comportamento da verificação

Depois que o health check é ativado:

1. A Zenifra chama a rota configurada usando GET a cada 1 minuto.
2. Uma resposta 2xx indica que a instância está saudável.
3. Resposta 3xx, 4xx ou 5xx, timeout ou impossibilidade de conexão indicam falha.
4. Quando a falha é confirmada, a instância é reiniciada automaticamente.
5. O estado atual e os eventos observados ficam disponíveis para consulta.

A reinicialização pode causar uma breve indisponibilidade enquanto a aplicação volta a responder. O health check não altera o código da aplicação nem substitui testes de disponibilidade; ele é uma proteção operacional para recuperar instâncias que deixaram de responder corretamente.

As falhas ficam disponíveis por 30 dias. Cada registro público informa o horário da ocorrência e o status HTTP quando disponível. Detalhes internos de instâncias, corpo da resposta, headers, segredos e outras informações sensíveis não fazem parte do histórico público.

Configure no Console

Para configurar pelo Console:

1. Abra Projetos e selecione um projeto HTTP.
2. Clique em Editar.
3. Na seção Healthcheck da aplicação, ative Ativar healthcheck e informe o Caminho da verificação, por exemplo /health.
4. Clique em Salvar healthcheck.
5. Use a tabela Falhas nos últimos 30 dias para confirmar o resultado das verificações.

A seção só aparece quando o plano do projeto retorna capabilities.healthcheck: true. Projetos existentes também podem ativar o recurso depois da criação, desde que o plano seja elegível. Desativar o health check interrompe novas verificações, preserva a última rota configurada e não apaga o histórico já registrado.

Use a CLI

A CLI oferece os mesmos recursos do Console para consulta e automação:

zenifra project healthcheck get --project <id>
zenifra project healthcheck set --project <id> --path /health
zenifra project healthcheck disable --project <id>
zenifra project healthcheck failures --project <id> --page 1 --limit 20

Adicione --json aos comandos quando precisar usar a saída em scripts ou pipelines:

zenifra project healthcheck get --project <id> --json
zenifra project healthcheck failures --project <id> --json

A consulta de falhas retorna somente o histórico dos 30 dias anteriores. Para autenticação e outros comandos, consulte a CLI de Deploy e Automação.

Use a API pública

A configuração também pode ser administrada pela API autenticada do projeto:

GET /v1/project/:id/healthcheck
PATCH /v1/project/:id/healthcheck
GET /v1/project/:id/healthcheck/failures?page=1&limit=50

Para ativar ou alterar a rota:

{
  "healthcheck": {
    "enabled": true,
    "path": "/health"
  }
}

Para desativar, envie apenas enabled: false. O último caminho é preservado:

{
  "healthcheck": {
    "enabled": false
  }
}

A resposta de configuração informa available, interval_seconds e retention_days, além da configuração atual. A resposta de falhas contém occurred_at, status_code quando disponível e pagination. A API mantém a autorização e o entitlement no servidor; o Console e a CLI não substituem essa validação.

Solução de problemas

A opção não aparece no Console

Confirme se o projeto é HTTP e se o plano retorna capabilities.healthcheck: true. Se o plano não for elegível, a configuração não pode ser ativada. Uma alteração de plano pode levar alguns instantes para aparecer no projeto.

A verificação retorna 404 ou 405

Confira o caminho salvo no projeto e confirme que a aplicação expõe exatamente essa rota com o método GET. O caminho deve começar com /, sem incluir o domínio completo.

A verificação retorna 3xx, 4xx ou 5xx

Ajuste a rota para retornar 2xx quando a aplicação estiver pronta. Redirecionamentos, autenticação obrigatória, páginas de erro e respostas de validação não são considerados sucesso.

A instância reinicia repetidamente

Teste a rota diretamente na URL pública e verifique se ela responde rapidamente. Confirme também se o projeto usa a mesma porta configurada pela aplicação e se a rota não depende de chamadas lentas ou indisponíveis. Consulte os logs da aplicação no Console para identificar o motivo da falha.

Não há falhas no histórico

O histórico registra falhas observadas depois da ativação e mantém os registros por 30 dias. Se o recurso foi desativado, novas verificações não são executadas; falhas anteriores continuam disponíveis durante o período de retenção.

Para outros cenários, consulte Solução de problemas.

Próximos passos

• Alterar configurações do projeto HTTP
• Métricas HTTP
• CLI de Deploy e Automação
• Solução de problemas

FAQ

Posso usar qualquer caminho para o health check?

Sim, desde que seja um caminho absoluto da aplicação, comece com / e seja atendido por GET. Não inclua domínio, query string ou fragmento.

Qual código HTTP é considerado saudável?

Qualquer status de 200 a 299. Respostas 3xx, 4xx, 5xx, timeouts e falhas de conexão são consideradas falhas.

Posso alterar o intervalo de 1 minuto?

Não. O intervalo é fixo em 1 minuto nesta versão. Timeout e quantidade de tentativas também são definidos pela Zenifra.

O recurso funciona em projetos existentes?

Sim. Um projeto HTTP existente pode ativar o health check quando o plano incluir health check (capabilities.healthcheck: true). A configuração começa a valer depois que for salva.

O que acontece com o histórico quando desativo o recurso?

O histórico não é apagado. Ele continua disponível por até 30 dias, enquanto novas verificações deixam de ser executadas.