IoT Sentinel — Monitoramento Real-Time: Saiba Quando Algo Cai

iot homelab monitoring real-time

IoT Sentinel — Monitoramento Real-Time: Saiba Quando Algo Cai

Este post é o sétimo de uma série de oito partes sobre o IoT Sentinel. Aqui falo sobre monitoramento de status, uptime e notificações.

Monitoramento automático

Registrar dispositivos e organizá-los é importante, mas não serve de muita coisa se você não sabe quando um deles cai. O IoT Sentinel resolve isso com um worker Python que roda em background, executando health checks periodicamente em todas as redes configuradas.

O processo é simples. O worker consulta a API para obter a lista de redes que precisam ser verificadas, junto com o intervalo configurado. Para cada rede, ele faz um scan do tipo status_check — basicamente um ping ou verificação de conexão — e publica o resultado via Redis para que a API processe as mudanças de status. Todo esse ciclo se repete automaticamente no intervalo definido.

O intervalo é dinâmico. Você configura uma vez e pode ajustar depois sem reiniciar nada — o worker busca o intervalo atualizado da API a cada ciclo. Se o intervalo muda de 60 para 30 segundos, o próximo ciclo já usa o novo valor.

O ponto principal é que isso funciona sozinho. Subiu o Sentinel, o health checker já está rodando. Não tem cron para configurar, não tem script para agendar. O loop roda enquanto o serviço estiver de pé, com tratamento de erros para reconectar ao Redis se a conexão cair.

Status em tempo real

De nada adianta o worker verificar o status dos dispositivos se você precisa ficar atualizando a página para ver o resultado. O Sentinel usa WebSocket (via Socket.IO) para empurrar atualizações para o browser no momento em que acontecem.

Quando o health checker detecta que um dispositivo mudou de status — de online para offline, ou vice-versa — a API emite um evento thing:status_changed pelo WebSocket. O frontend recebe esse evento e atualiza o badge de status do dispositivo na hora, sem reload. Você está olhando a lista de dispositivos e vê o badge mudar de verde para vermelho em tempo real.

Os badges seguem uma convenção simples: verde para online, vermelho para offline, cinza para unknown. O estado unknown é o inicial — quando você registra um dispositivo mas ele ainda não passou por nenhum health check. Depois do primeiro ciclo bem-sucedido, ele transita para online ou offline e nunca mais volta para unknown (a não ser que você limpe o histórico manualmente).

O WebSocket também entrega eventos de scan e notificações novas. A conexão é autenticada via JWT — o mesmo token que o frontend usa para as chamadas REST.

Histórico de status

Saber que um dispositivo está offline agora é útil. Saber quando ele ficou offline, quanto tempo ficou, e se isso é um padrão recorrente — isso sim é informação de verdade.

Cada transição de status gera um registro no banco. O StatusHistoryService recebe o ID do dispositivo e o novo status, e persiste um StatusEvent com o timestamp exato da mudança. Esses eventos ficam ordenados cronologicamente e formam uma timeline visual: você vê exatamente quando o dispositivo passou de online para offline, quando voltou, e quanto tempo ficou em cada estado.

A consulta aceita um parâmetro de range — 24h, 7d ou 30d — e retorna todos os eventos dentro do período. Para calcular a duração de cada estado, o serviço busca o último evento antes do range para determinar o estado inicial, soma o tempo em cada estado e divide pelo total.

Os dados são retidos por 30 dias. Eventos mais antigos são limpos automaticamente via TTL no banco. Para a maioria dos casos de uso em homelab, 30 dias é mais do que suficiente para identificar padrões e tomar decisões.

Métricas de uptime

A partir do histórico de status, o Sentinel calcula métricas de uptime para cada dispositivo. Você pode ver a porcentagem de tempo online em três períodos: 24 horas, 7 dias e 30 dias.

O cálculo é direto. O serviço percorre os eventos de status no período selecionado, acumula o tempo em que o dispositivo esteve online e divide pelo total do período. O resultado é uma porcentagem com uma casa decimal — algo como “99.2% de uptime nos últimos 30 dias” ou “87.5% nas últimas 24 horas”.

Existe também uma métrica de uptime médio, que agrega todos os dispositivos que tiveram eventos no período. Se o uptime médio de 30 dias está em 98%, as coisas estão bem. Se caiu para 85%, algo está errado e vale investigar.

Na prática, as métricas de uptime são o jeito mais rápido de identificar dispositivos problemáticos. Aquele sensor que parece funcionar mas tem 72% de uptime provavelmente está com problema de alimentação ou de sinal Wi-Fi.

Notificações

O Sentinel tem um sistema de notificações in-app que aparece em um dropdown no header. Cada evento relevante gera uma notificação: dispositivo ficou offline (thing_offline), dispositivo voltou (thing_online), novo dispositivo descoberto (new_discovery), scan falhou (scan_failed).

As notificações são persistidas no banco com status de lida/não lida. O dropdown mostra a contagem de notificações não lidas e você pode marcar individualmente ou todas de uma vez como lidas. Novas notificações chegam em tempo real via WebSocket — o mesmo canal que atualiza os status dos dispositivos.

Além das notificações automáticas, existe o conceito de notification rules. Você pode criar regras específicas — por exemplo, “me notifique quando qualquer dispositivo novo for descoberto na rede da VLAN de IoT”. As regras têm um target opcional (uma rede específica) e uma condição (como new_discovery). Quando a condição é atendida, a regra dispara e gera a notificação.

Por enquanto as notificações são apenas in-app. A ideia para o futuro é adicionar canais como e-mail e webhook, mas para um homelab a notificação na interface já resolve.

Cenário real

Vou contar um caso que ilustra bem por que tudo isso importa.

Tenho um Sonoff que controla uma automação e ele vivia “sumindo” da rede. Eu não percebia na hora — só quando ia acionar e não respondia. Abri o Sentinel e estava tudo lá na timeline: o dispositivo ficava alternando entre online e offline várias vezes ao dia. Às vezes caía por 5 minutos, às vezes por uma hora.

O que tornou isso realmente útil foi olhar o histórico de 30 dias. O uptime estava em 72% — ou seja, quase um terço do tempo o Sonoff estava fora. O padrão ficou claro: o problema era a antena Wi-Fi fraca do dispositivo. Reposicionei o Sonoff para um local com melhor sinal e o uptime subiu para 93%. Não resolveu 100%, mas sem o IoT Sentinel eu jamais teria identificado que esse dispositivo específico estava intermitente na rede — acharia que era problema do roteador ou da internet.

Esse é o tipo de insight que só aparece com monitoramento contínuo. Sem o histórico e as métricas, eu provavelmente levaria meses para perceber o padrão.

Próximo passo

O monitoramento cuida de manter você informado sobre o que acontece na rede. Mas ainda falta a visão consolidada: o dashboard com métricas gerais, o mapa de rede que mostra a topologia dos dispositivos, e o backup que garante que você não perca tudo se precisar reinstalar.

Tudo isso está na Parte 8 — Dashboard, Network Map e Backup.