API de alarmes e saúde

O dtvsold verifica o roteador a cada minuto e mantém um registro de alarmes no seu banco de dados: uma linha por condição com falha, identificada por uma chave estável (por exemplo bond0/eno2/link). Um alarme é disparado após 2 verificações com falha seguidas (um serviço crítico parado e o serviço DHCP disparam na hora) e encerrado após 2 verificações boas. Cada disparo e cada encerramento também é gravado como um evento de histórico. Alarmes encerrados e eventos com mais de 90 dias são apagados.

O que é verificado: tudo o que GET /alerts relata (DHCP, VLANs, pools de endereços, clientes desconhecidos, CGNAT, anti-spoofing, o coletor da OLT e os avisos de fibra, a licença) mais o próprio roteador — membros do bond sem link ou fora do agregador LACP, o uplink caído ou sem rota padrão, portas com endereços ou VLANs sem portadora, links oscilando, serviços e timers do roteador com falha ou parados, discos enchendo (aviso em 90 %, crítico em 95 %), CPU, memória, processos encerrados por falta de memória, temperaturas, rastreamento de conexões e erros de porta.

Os dois endpoints são somente leitura e não têm forma /api?action=. O equivalente na CLI é dtvsol alarms. Autenticação e erros: veja a visão geral da API.

Campos do alarme

Campo	Significado
area	olt, onu, network, server ou services (derivado de source).
key	Identificador estável da condição.
source	A verificação: por exemplo link, uplink, bond, interface, nic, cpu, memory, temp, conntrack, disk, service, timer, dhcp, dhcp-pool, stranger, cgnat, spoof, olt, fiber, licence.
level	critical, warning ou info.
text	Descrição legível.
detail	Dados extras da verificação (objeto ou null).
first_seen, last_seen	YYYY-MM-DD HH:MM:SS.
cleared	Quando foi encerrado, ou null enquanto ativo.
count	Inteiro guardado com a linha do alarme.

Alarmes

GET /alarms

Os alarmes ativos, os críticos primeiro e depois os mais antigos. Com all=1, os alarmes encerrados nos últimos 7 dias vêm depois dos ativos. Com history=N, vêm em vez disso os últimos N disparos e encerramentos (os mais recentes primeiro).

Nome	Em	Tipo	Observações
all	query	boolean	1 acrescenta os alarmes encerrados nos últimos 7 dias.
history	query	integer	Retorna os últimos N eventos de disparo/encerramento (1–1.000; 50 quando não é um número positivo). Tem precedência sobre all.

curl -s "http://ROUTER-IP:8880/alarms?all=1" -H "X-API-Key: YOUR_API_KEY"

{
  "count": 1,
  "generated": "2026-09-28 10:40:00",
  "checked": {
    "at": "2026-09-28 10:39:58",
    "took_ms": 412,
    "errors": [],
    "health": {"cpu": {"…": "…"}, "memory": {"…": "…"}, "ports": ["…"]}
  },
  "alarms": [
    {
      "area": "network",
      "key": "bond0/eno2/link",
      "source": "link",
      "level": "warning",
      "text": "bond0: member eno2 has no link",
      "detail": null,
      "first_seen": "2026-09-28 09:12:00",
      "last_seen": "2026-09-28 10:39:58",
      "cleared": null,
      "count": 1
    }
  ]
}

count é o número de alarmes ativos (os encerrados retornados por all=1 não entram na conta). checked descreve a última rodada de verificação (null antes da primeira); checked.errors lista o que ela não conseguiu verificar.

Forma de histórico:

curl -s "http://ROUTER-IP:8880/alarms?history=20" -H "X-API-Key: YOUR_API_KEY"

{
  "count": 2,
  "generated": "2026-09-28 10:40:00",
  "events": [
    {"area": "services", "at": "2026-09-28 10:05:00", "kind": "clear", "level": "warning",
     "key": "dhcp-pool/vlan100", "source": "dhcp-pool", "text": "…"},
    {"area": "services", "at": "2026-09-28 09:30:00", "kind": "raise", "level": "warning",
     "key": "dhcp-pool/vlan100", "source": "dhcp-pool", "text": "…"}
  ]
}

Erros: 405 para qualquer método que não seja GET; 500 com {"ok": false, "code": 500, "error": …} quando o banco de dados não pode ser lido.

Saúde

GET /health

As leituras atuais de cada área, exibidas ao lado dos alarmes dessa área na aba Alarms do monitor. Tudo é lido de dados que o daemon já mantém; nada aqui consulta uma OLT.

Nome	Em	Tipo	Observações
area	query	string	olt, onu, network, server ou services. Omita para todas as áreas.

O que cada área contém:

• server — da última verificação de alarmes: cpu, load, memory, temps, disks, conntrack, uptime_s, units (os serviços do roteador) e measured (quando).
• network — ports (taxas e erros da última verificação), bonds (modo, membros, estado do link, participação no agregador LACP, falhas de link), uplinks (up / portadora) e default_routes.
• olt — por OLT registrada: status do coletor (ok, at, age_s, took_ms, error), número de portas PON, portas em uso, ports_dark (portas PON cujas ONTs estão todas offline), placas, ONTs e ONTs online, erros.
• onu — por OLT: total de ONTs, contagens por estado, causas de offline, luz recebida por faixas (good −8 a −25 dBm, weak −25 a −27 dBm, too_weak abaixo de −27 dBm, too_strong acima de −8 dBm) e as cinco ONTs com sinal mais fraco.
• services — interfaces atendidas por DHCP, número de clientes legados, serviços por estado, CGNAT (enabled, iface, assigned, capacity, free) e anti-spoofing (enabled, mode, pacotes IPv4/IPv6/ARP descartados, last_hour).

curl -s "http://ROUTER-IP:8880/health?area=onu" -H "X-API-Key: YOUR_API_KEY"

{
  "ok": true,
  "generated": "2026-09-28 10:41:00",
  "area": "onu",
  "health": {
    "olts": [
      {
        "olt": "olt-1",
        "at": "2026-09-28 10:40:12",
        "total": 412,
        "states": {"online": 398, "offline": 14},
        "offline_causes": {"power off": 9, "fiber cut": 5},
        "light": {"good": 390, "weak": 6, "too_weak": 2, "too_strong": 0},
        "weakest": [{"fsp": "0/1/3", "ont_id": 12, "rx_dbm": -28.4, "description": "…"}]
      }
    ]
  }
}

Sem area, a resposta é {"ok": true, "generated": …, "areas": {"olt": …, "onu": …, "network": …, "server": …, "services": …}}.

Erros: 400 ("area is one of olt, onu, network, server, services") para uma área desconhecida; 405 para qualquer método que não seja GET.