Monitores Heartbeat

Os monitores Heartbeat invertem a direção - a tua tarefa diz-nos que está viva. Dois modos: Agendado (intervalo esperado) e Recetor de eventos (dormente; dispara apenas quando os triggers correspondem ao payload).

MODOS

• Agendado: se nenhum batimento chegar dentro do intervalo configurado, o estado muda para MISS e os alertas disparam.
• Falha explícita agendada: chame o mesmo URL com ?status=fail quando a tarefa correu mas detetou um resultado mau. Isto regista um batimento KO e aciona o tratamento de indisponibilidade imediatamente.
• Recetor de eventos: o estado permanece dormente. Cada batimento guarda o teu payload; os triggers com condições avaliam-no. ?status=fail é ignorado no modo Recetor de eventos porque as condições dos triggers decidem o que importa.

OK beat:
curl -fsS https://keepitalive.dev/heartbeat/{token}

Explicit failed beat:
curl -fsS "https://keepitalive.dev/heartbeat/{token}?status=fail"

RECEITAS AGENDADAS

*/5 * * * * curl -fsS https://keepitalive.dev/heartbeat/{token} >/dev/null

0 2 * * * /usr/bin/backup.sh && curl -fsS https://keepitalive.dev/heartbeat/{token}

curl -fsS "https://keepitalive.dev/heartbeat/{token}?status=fail&payload=disk+full"

*/1 * * * * if ping -c 1 -W 2 192.168.1.50 >/dev/null 2>&1; then \
  curl -fsS "https://keepitalive.dev/heartbeat/{token}"; \
else \
  curl -fsS -X POST "https://keepitalive.dev/heartbeat/{token}?status=fail" \
    -d "unreachable"; \
fi

:: C:\scripts\keepalive_heartbeat.bat
@echo off
curl -fsS https://keepitalive.dev/heartbeat/{token} >nul 2>&1

:: schtasks /create /tn "KEEPitALIVE" /tr C:\scripts\keepalive_heartbeat.bat /sc minute /mo 5

AGENDAMENTOS CRON

Um heartbeat simples espera um sinal a cada N segundos, o que nao serve para um trabalho que corre por calendario: um backup so em dias uteis parece ter 65 horas de atraso todos os domingos. Defina antes uma expressao cron e o prazo passa a ser a proxima execucao agendada mais a tolerancia - nada esta atrasado ate algo ter sido esperado. Escolha o fuso horario onde o trabalho corre: o agendamento e avaliado ai, o que mantem um trabalho das 03:00 as 03:00 quando a hora muda. A expressao tambem define o custo, porque determina quantas execucoes por hora esperamos. O URL de ingestao nao muda; so muda quando esperamos o sinal.

# Give the monitor the same schedule the job runs on.
0 3 * * 1-5      # 03:00, weekdays only
*/15 * * * *     # every 15 minutes
0 3 1 * *        # 03:00 on the 1st of the month
@daily           # midnight

# Pick the zone the job runs in, not the server's: that is
# what keeps 03:00 at 03:00 when the clocks change.

CÓDIGOS DE SAÍDA

Acrescenta o código de saída da tua tarefa ao URL e o beat comunica-se sozinho: 0 é sucesso, qualquer outro valor é uma falha. É melhor do que encadear com && , que não envia nada quando a tarefa falha - assim o monitor só fica em baixo mais tarde, quando a janela é falhada, em vez de no momento em que a tarefa parte. O código fica guardado no beat, por isso uma condição de acionador pode encaminhar consoante o tipo de falha: payload.exit_code == 137 (terminado por memória) pode abrir uma indisponibilidade enquanto payload.exit_code == 1 apenas notifica. Os códigos têm de estar entre 0 e 255; se não tiveres um código à mão, também podes usar /fail.

# $? is the exit status of the job that just ran
0 2 * * * /usr/bin/backup.sh; curl -fsS https://keepitalive.dev/heartbeat/{token}/$?

# Send the job output too, so the alert says why it failed.
# Capture it first: in a pipeline $? is the last command's status,
# not the job's.
0 2 * * * out=$(/usr/bin/backup.sh 2>&1); \
  curl -fsS --data-binary "$out" https://keepitalive.dev/heartbeat/{token}/$?

DURAÇÃO DA EXECUÇÃO

Faça ping a /start quando o trabalho começa e envie um sinal normal quando termina, e o tempo decorrido fica guardado no sinal como duration_ms, permitindo alertar sobre execuções lentas - payload.duration_ms > 300000 apanha uma cópia de segurança que demorou mais de cinco minutos ainda que tenha terminado bem. O /start é totalmente opcional: um único sinal final já é um relatório completo, e a deteção de falhas e os códigos de saída funcionam sem ele. Enviá-lo dá exatamente duas coisas - a duração registada e a deteção de uma execução que nunca termina. Um /start sozinho não reporta nada nem altera o estado do monitor: um trabalho que arranca e bloqueia tem de continuar a falhar a sua janela. Um segundo /start enquanto uma execução está aberta é recusado, porque dois arranques sem fim pelo meio significam que o primeiro nunca reportou; a recusa termina assim que essa execução excede o prazo. Execuções abertas há mais de 24 horas são descartadas.

# /start is optional. Without it you still get miss detection
# and the exit status - just no duration and no stuck-run alert:
0 2 * * * /usr/bin/backup.sh; curl -fsS https://keepitalive.dev/heartbeat/{token}/$?

# With it, the run is timed and a job that never finishes is caught:
0 2 * * * curl -fsS https://keepitalive.dev/heartbeat/{token}/start; \
  /usr/bin/backup.sh; \
  curl -fsS https://keepitalive.dev/heartbeat/{token}/$?

EXECUÇÕES ENCRAVADAS

Se uma tarefa chama /start e depois fica pendurada, ainda não há nada atrasado: o início não renovou nada, por isso o monitor parece bem até à hora em que o próximo beat seria devido. Essa lacuna é precisamente o problema de cronometrar uma tarefa: uma execução encravada é exatamente a falha que querias apanhar. Por isso uma execução que não enviou o beat final fica em baixo assim que ultrapassa o intervalo mais a janela de tolerância, com um erro a indicar há quanto tempo está a correr. Não há uma definição separada de duração máxima: um beat atrasado e uma execução encravada são a mesma pergunta — quanto tempo esperamos — por isso a tolerância que já definiste responde às duas.

PAYLOADS

Faz POST de JSON para o teu URL de heartbeat para reportar métricas do sistema ou campos arbitrários. O card Último Relatório na página de detalhe do monitor apresenta o payload mais recente como JSON formatado quando possível, com recurso a texto simples.

curl -fsS -X POST https://keepitalive.dev/heartbeat/{token} \
  -H 'Content-Type: application/json' \
  -d '{"job":"nightly-backup","status":"ok","rows":42850}'

RECETOR DE EVENTOS: MANUTENÇÃO CI/CD

O modo Recetor de eventos é útil para pipelines de implementação. Cria um trigger de payload com a condição payload.status == "maintenance" e classificação de incidente maintenance. Envia um payload de manutenção antes da implementação e um payload running/ok num passo final if: always(). O incidente abre enquanto a expressão corresponde e fecha quando o próximo payload aceite a limpa.

- name: Start maintenance
  run: |
    curl -fsS -X POST "$KEEPITALIVE_HEARTBEAT_URL" \
      -H "Content-Type: application/json" \
      -d '{"status":"maintenance","source":"github-actions","sha":"${{github.sha}}"}'

- name: Deploy
  run: ./deploy.sh

- name: End maintenance
  if: always()
  run: |
    curl -fsS -X POST "$KEEPITALIVE_HEARTBEAT_URL" \
      -H "Content-Type: application/json" \
      -d '{"status":"running","source":"github-actions","sha":"${{github.sha}}"}'

Os recetores de eventos limitam os payloads aceites pelo intervalo do monitor. Para tarefas de implementação muito curtas, usa o menor intervalo que o teu plano permite ou atrase o payload final até o intervalo ter decorrido. Se a origem ficar em silêncio, o KEEPitALIVE não assume a recuperação.

#!/bin/bash
URL="https://keepitalive.dev/heartbeat/{token}"
CPU=$(top -bn1 | grep "Cpu" | awk '{print $2}')
RAM=$(free -m | awk '/Mem/{printf "%.1f", $3/$2*100}')
DISK=$(df -h / | awk 'NR==2{print $5}')
curl -fsS -X POST $URL \
  -H "Content-Type: application/json" \
  -d "{\"hostname\":\"$(hostname)\",\"cpu\":\"$CPU%\",\"ram\":\"$RAM%\",\"disk\":\"$DISK\"}"

$url = "https://keepitalive.dev/heartbeat/{token}"
$os  = Get-CimInstance Win32_OperatingSystem
$body = @{
  hostname = $env:COMPUTERNAME
  cpu      = "{0:N1}%" -f (Get-CimInstance Win32_Processor).LoadPercentage
  ram      = "{0:N1}%" -f ((1 - $os.FreePhysicalMemory / $os.TotalVisibleMemorySize) * 100)
} | ConvertTo-Json
Invoke-RestMethod -Uri $url -Method POST -Body $body -ContentType "application/json"