O que detector-de-silêncio faz?
Captura a falha que o monitoramento baseado em erros não consegue ver: um processo que simplesmente fica em silêncio. Nenhuma exceção, nenhuma falha — ele para de emitir, e você descobre dias depois.
Quando usar
- Você tem um fluxo de timestamps de emissão (um logger, heartbeat, job cron, loop de agente, feed de dados) e uma cadência esperada, e quer saber se ele parou.
- Você deseja uma verificação verificável e determinística que pode ser integrada a uma varredura diária de integridade.
Como funciona (um único parâmetro)
SILENT quando o sinal mais recente é mais antigo que expected_interval_sec * multiplier (padrão multiplier = 3.0 → aproximadamente três batidas perdidas). Um fluxo vazio é SILENT. O multiplicador equilibra latência de detecção (menor = detecta morte real mais rápido) contra falsos alarmes em cadências irregulares (maior = mais tolerante). Defina expected_interval_sec para a lacuna típica do fluxo; se a cadência for irregular, defina-o próximo ao p95 da lacuna e documente isso.
Execute
echo '{"now": 1750000000, "expected_interval_sec": 60,
"timestamps": [1749999940, 1749999990]}' > input.json
python3 detector.py input.json # exit 0 = saudável, exit 1 = silencioso (alertável)
Ou importe-o: from detector import detect; detect(now, timestamps, expected_interval_sec, multiplier=3.0).
Saída
{ "status": "silent", "reason": "last signal 19880s old vs threshold 180s",
"last_age_sec": 19880, "threshold_sec": 180.0 }
Limitações conhecidas (medidas, não afirmadas — consulte BENCHMARK.md)
Em um conjunto rotulado de 105 casos, a skill obteve 83,8% de precisão (TPR 81,8% / TNR 86,0%). Todo erro está na 'zona cinzenta' de 2 a 4x perto do limite; casos claros estão 100% corretos. Dois modos de falha honestos: (1) falsos alarmes em fluxos ativos mas momentaneamente lentos que cruzaram 3x por acaso; (2) uma latência de detecção de uma janela em um fluxo que acabou de morrer. Ajuste multiplier para sua preferência entre latência e falsos alarmes. A avaliação é reproduzível — execute-a novamente e verifique os números você mesmo.