Pular para o conteúdo

Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês

Monitorando o servidor de fora

Como apontar um monitor de disponibilidade para o servidor, como evitar que o monitoramento aumente o custo de execução e como distinguir o modo de manutenção (Manutenção) de uma indisponibilidade. Os caminhos das sondas estão em a seção de verificação de saúde do guia de execução.

Os fatos de terceiros abaixo trazem a data em que foram confirmados e a fonte. Os serviços mudam seus planos e suas telas; confira a página vinculada antes de confiar em um limite.

Caminho Para Acessa o banco No modo de manutenção
GET /api/v1/instance/health Monitores de disponibilidade, páginas de status, o cliente web No máximo uma vez a cada 60 s por processo 503 com Retry-After e {"status":"maintenance"}
GET /healthz, GET /health/live A sonda de vivacidade da plataforma Nunca 200 {"status":"maintenance"}
GET /readyz, GET /health/ready A sonda de prontidão do balanceador de carga ou do Kubernetes A cada requisição (requisições simultâneas compartilham uma verificação) 200 {"status":"maintenance"}

Aponte o monitor externo para /api/v1/instance/health, não para /readyz (/health/ready): ele consulta o banco de dados a cada requisição, então um monitor com intervalo curto mantém acordado um banco de dados que escala a zero. As sondas são para a sua plataforma. A seção monitoring do mycroblog-gcp verifica /health/live no Google Cloud, e a do mycroblog-aws verifica /readyz, cada uma pelo monitor da própria plataforma em um intervalo longo: o uptime_period dela é o que isso custa, já que cada verificação acorda uma instância.

Para onde vão as métricas, os traces e os relatórios de erros do próprio servidor é a seção observability dos mesmos módulos, que monitoring lê. Por padrão, ela envia cada um à plataforma: no Google Cloud, as métricas ao Cloud Monitoring, os traces de requisições ao Cloud Trace e os relatórios de erros ao Error Reporting, os três a partir do que o Cloud Run envia, com as APIs deles ativadas; na AWS, as métricas ao CloudWatch no Embedded Metric Format, os relatórios de erros ao CloudWatch Logs e os traces ao X-Ray, por meio de um coletor que roda ao lado do servidor em cada tarefa (traces no AWS ECS). O monitoring precisa das métricas ali: ele recusa observability.metrics = "settings", que deixa metrics_exporter para a entrada settings.

Respostas de /api/v1/instance/health (sem autenticação, Cache-Control: no-store):

Estado HTTP Corpo
Saudável 200 {"status":"ok","checked_at":"<RFC 3339>"}
Indisponível (o banco de dados está inacessível ou o esquema não foi aplicado) 503 {"status":"unavailable","checked_at":"<RFC 3339>"}
Modo de manutenção 503 com Retry-After {"status":"maintenance"}

/healthz e /readyz respondem 200 com {"status":"ok"} quando saudáveis, e /readyz responde 503 com um documento de problema quando o banco de dados não está pronto. /health/live e /health/ready são as mesmas verificações com outros nomes.

No Cloud Run, chame os caminhos que não terminam em z. O Cloud Run reserva alguns caminhos que terminam em z e os responde com o próprio 404 antes de uma requisição chegar ao contêiner: /healthz é um deles, e nada promete que /readyz continue respondendo. De fora de uma implantação no Cloud Run (um monitor de disponibilidade, curl), use /health/live, /health/ready ou /api/v1/instance/health. As sondas do próprio contêiner não são afetadas. O corpo nunca traz um motivo, um nome de host nem uma versão. A causa está no log do servidor.

checked_at é o horário da verificação em que a resposta se baseia. O servidor executa a verificação do banco de dados no máximo uma vez por minuto por processo e reutiliza o resultado, então um monitor que consulta com mais frequência que a cada 60 s vê o mesmo checked_at e não ganha nada. Com vários processos, cada um executa a própria verificação.

Com origin_secret definido, esses três caminhos ainda respondem sem o cabeçalho, então não mostram que a CDN o perdeu. Monitore também uma página pela CDN, como https://<host>/about, se um monitor for o seu primeiro sinal de problema.

  • Bancos de dados que param quando ociosos. Se o intervalo do monitor for menor que o tempo que o banco de dados espera antes de parar, o banco nunca para. O Neon suspende um compute após 5 minutos sem atividade; o plano Free não permite desativar isso (confirmado em 2026-10-25, Neon: Scale to zero). Como regra prática, um intervalo de 5 minutos ou mais permite que um banco ocioso pare entre as verificações, e cada verificação o acorda pelo tempo da verificação mais o tempo ocioso. Um servidor federado recebe entregas de outros servidores o tempo todo, então o banco fica acordado grande parte do dia de qualquer forma; o custo extra se limita às horas silenciosas.
  • Uma divisão mais barata se o custo ocioso importar mais. Monitore /health/live (ele nunca acessa o banco de dados) em um intervalo curto, e /api/v1/instance/health, que acessa o banco, em um intervalo longo (15 minutos ou mais). /health/live responde 200 também no modo de manutenção, então verifique "status":"ok" no corpo.
  • As requisições em si são pequenas. Uma verificação a cada 5 minutos são cerca de 8.640 requisições por mês, e uma a cada minuto cerca de 43.200. Isso cabe no nível gratuito do Cloud Run (2 milhões de requisições, 180.000 vCPU-segundos e 360.000 GiB-segundos por mês; tempo arredondado para cima em 100 ms; confirmado em 2026-10-23, preços do Cloud Run).

Distinguindo o modo de manutenção de uma indisponibilidade

Seção intitulada “Distinguindo o modo de manutenção de uma indisponibilidade”

Durante o modo de manutenção (guia de manutenção), o endpoint de saúde responde 503, o que a maioria dos monitores trata como uma indisponibilidade. O código de status sozinho não consegue distinguir os dois casos, então decida pelo corpo:

  • Trate "status":"ok" no corpo como saudável, e qualquer outra coisa como fora do ar. Um monitor de palavra-chave ou de valor JSON faz isso.
  • Para evitar alertas durante uma manutenção planejada, defina a janela de manutenção do monitor, se o serviço tiver uma (veja a tabela abaixo), ou pause o monitor manualmente antes de começar.
  • O plano Free do UptimeRobot não tem janela de manutenção: pause o monitor ou aceite o alerta.

Todos eles verificam a mesma coisa: GET https://<your-host>/api/v1/instance/health está saudável quando a resposta é 200 e o corpo contém "status":"ok".

Serviço Tipo de monitor Saudável quando Janela de manutenção Confirmado
UptimeRobot Keyword O corpo contém "status":"ok" Não no Free (Solo e acima) 2026-10-25, preços
Better Stack Status HTTP, ou Keyword 2xx, ou o corpo contém "status":"ok" Não verificada 2026-10-25
Gatus Endpoint conditions [STATUS] == 200 e [BODY].status == ok maintenance na configuração 2026-10-25, README
Uptime Kuma HTTP(s) - Keyword, ou JSON Query O corpo contém "status":"ok", ou status é ok Integrada 2026-10-23, README
Upptime sites em .upptimerc.yml 200 e o corpo contém "status":"ok" Nenhuma 2026-10-25, Configuration

Crie um monitor do tipo Keyword: URL https://<your-host>/api/v1/instance/health, palavra-chave "status":"ok", e alerte quando a palavra-chave não existir. O plano Free permite 50 monitores com intervalo de 5 minutos, e inclui monitores de palavra-chave. “Custom headers & statuses” e janelas de manutenção começam no plano Solo (pago, intervalo de 60 segundos) (confirmado em 2026-10-25, preços). Um monitor de palavra-chave basta aqui, porque a verificação é feita no corpo.

Duas formas funcionam (confirmado em 2026-10-25, Uptime monitor, Keyword monitor):

  • Um monitor de status HTTP: ele trata uma resposta 2xx como ativa, então 200 está ativo e 503 (indisponível ou em manutenção) abre um incidente.
  • Um monitor de Keyword: “Alert us when” é “URL doesn’t contain keyword”, com a palavra-chave "status":"ok". A correspondência não diferencia maiúsculas de minúsculas.

A frequência de verificação e as janelas de manutenção do plano Free não foram verificadas: as páginas oficiais não as informam para o plano Free. Os limites do nível gratuito (10 monitores e heartbeats juntos, uma página de status) vêm da página de preços, confirmados em 2026-10-23.

Em config.yaml (intervalo padrão 60s; confirmado em 2026-10-25, README):

endpoints:
- name: my
url: "https://<your-host>/api/v1/instance/health"
interval: 5m
conditions:
- "[STATUS] == 200"
- "[BODY].status == ok"

O Gatus tem uma seção maintenance no nível superior (start como hh:mm, duration, timezone, que é UTC por padrão, e every como uma lista de dias da semana, em que vazio significa todos os dias) para trabalhos planejados. O README só diz que ela serve para evitar alertas durante janelas de manutenção; verifique o comportamento na sua versão.

Adicione um monitor do tipo HTTP(s) - Keyword com a palavra-chave "status":"ok", ou HTTP(s) - Json Query com a consulta status e o valor esperado ok. Os códigos de status aceitos são 200-299 por padrão, então a 503 de manutenção e a 503 de indisponibilidade ficam ambas como inativas. O Uptime Kuma tem um recurso de manutenção para janelas de monitores (wiki o lista; os detalhes não foram verificados). Os tipos de monitor foram confirmados em 2026-10-23 no código-fonte (monitor.js, EditMonitor.vue).

No .upptimerc.yml (confirmado em 2026-10-25, Configuration):

sites:
- name: My server
url: https://<your-host>/api/v1/instance/health
__dangerous__body_down_if_text_missing: '"status":"ok"'

Por padrão, 20x e 30x contam como ativos; defina expectedStatusCodes: [200] para aceitar apenas 200. A verificação roda no GitHub Actions em um agendamento definido para todos os sites (workflowSchedule.uptime, padrão a cada 5 minutos, que também é o mínimo que o GitHub Actions permite). O nome da opção diz que ela não é recomendada, mas é o caminho para testar o corpo.

Defina status_page_url (MY_STATUS_PAGE_URL, uma URL https:; veja a referência de configuração) como a página pública do seu monitor. O servidor mostra o link em GET /api/v1/instance, nas páginas de login e de erro que ele renderiza, no cliente web (também quando o servidor não responde) e na página de manutenção, para que um usuário que não consegue alcançar o servidor descubra o motivo. Ele é lido da configuração, não do banco de dados, então funciona quando o banco está fora do ar. Uma mudança passa a valer após um reinício.

Opções para a própria página (este servidor não importa o estado de uma página de status, então publique também os anúncios como um aviso para todo o servidor):

  • A página de status hospedada do serviço de monitoramento que você escolheu (o plano Free do UptimeRobot tem uma página de status sem personalização; o nível gratuito do Better Stack tem uma), as páginas que o Gatus e o Uptime Kuma servem por conta própria, ou o site estático do Upptime no GitHub Pages.
  • Atlassian Statuspage, que é um lugar para publicar, e não um monitor. Um componente tem um entre cinco estados: Operational, Under maintenance, Degraded performance, Partial outage, Major outage (valores da API operational, under_maintenance, degraded_performance, partial_outage, major_outage; confirmado em 2026-10-23, What is a component?, Statuspage API). Não está verificado como mudar o estado de um componente automaticamente a partir do alerta de um monitor (isso exige uma integração por serviço configurada em uma conta real).

Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt

Análise de acesso deste site