Monitorização
Confirma que a tua instância está a funcionar e que as tarefas em segundo plano continuam a correr, com um monitor como o Uptime Kuma.
As sincronizações bancárias, as importações, as atualizações de preços e os emails agendados correm no worker, em segundo plano. Se o worker parar, a aplicação continua a abrir, por isso nada no ecrã te avisa. A API tem dois endpoints para vigiar.
Endpoints de saúde
| Endpoint | Responde | Para que serve |
|---|---|---|
GET /v1/health | 200 sempre que o processo da API está a correr | Verificações de saúde dos contentores. Nunca consulta a base de dados, por isso uma base de dados lenta não reinicia a API |
GET /v1/health/ready | 200 quando tudo funciona, 503 quando algo falha | Monitores de disponibilidade e alertas |
Ambos são públicos e não precisam de chave. /v1/health/ready verifica três coisas, em paralelo e cada uma em até 3 segundos:
| Verificação | Falha quando |
|---|---|
database | O Postgres não responde a uma consulta simples |
queue | Não é possível ler a fila de tarefas, ou uma tarefa espera para começar há mais de HEALTH_MAX_JOB_AGE_MINUTES (60 por omissão). Os lotes de emails agendados, que se esvaziam ao longo de algumas horas de propósito, têm mais margem |
worker | O worker não terminou a sua tarefa de heartbeat, que corre a cada 5 minutos, nos últimos 15 minutos |
Uma resposta saudável tem este aspeto:
{
"status": "ok",
"checks": {
"database": { "status": "ok" },
"queue": { "status": "ok" },
"worker": { "status": "ok", "lastHeartbeatAt": "2026-11-07T12:00:00.000Z" }
},
"version": "1.2.0",
"commit": "4f1c2e0..."
}Quando algo falha, status é degraded, a resposta é um 503 e a verificação que falhou indica um reason curto, como timeout, unreachable, backlog ou stale_heartbeat. Os detalhes estão nos registos: docker compose logs api para a verificação, docker compose logs worker para as tarefas.
Logo depois de arrancares os contentores, worker pode falhar durante alguns segundos, até o primeiro heartbeat do worker terminar.
version e commit indicam a versão que o servidor corre. GET /v1/instance também os mostra.
Uptime Kuma
O Uptime Kuma é um monitor que alojas tu próprio e que te pode avisar por email, Telegram, ntfy e muitos outros canais. Adiciona um monitor:
- Monitor type: HTTP(s) - Keyword
- URL:
https://money.example.com/v1/health/ready(o teuAPI_URLseguido de/v1/health/ready; numa instalação com um só nome de anfitrião, é o endereço da aplicação web) - Keyword:
"status":"ok" - Heartbeat interval: 60 segundos
Qualquer monitor que verifique um estado 200 funciona da mesma forma. O endpoint guarda a resposta durante 5 segundos e aceita 300 pedidos a cada 15 minutos vindos do mesmo endereço, por isso consulta-o no máximo a cada 30 segundos.
Se o Uptime Kuma correr no mesmo projeto Compose, usa http://api:3001/v1/health/ready.
Contentores
docker compose ps mostra cada contentor como saudável (healthy) ou não (unhealthy). O contentor worker fica unhealthy quando o executor de tarefas parou ou não consegue chegar ao Postgres. Não deteta uma tarefa bloqueada; /v1/health/ready deteta.