Solução de problemas

Guia rápido para diagnosticar uma instalação do Zarv Agent. Salvo indicação em contrário, os comandos abaixo são para a instalação nativa (systemd).

Logs e estado

# Estado do serviço
systemctl status zarv-agent

# Logs (siga em tempo real com -f)
journalctl -u zarv-agent -f

# Logs do boot atual
journalctl -u zarv-agent -b

Os logs são estruturados (JSON por padrão; veja EDGE_AGENT_LOG_FORMAT em Configuração).

No Docker:

docker logs -f zarv-agent

Endpoints de saúde locais

A interface local expõe endpoints úteis para diagnóstico (porta 8088):

Endpoint	O que retorna
GET /api/health	Checagens de subsistemas (banco, disco, memória, conectividade, captores de câmera, goroutines). HTTP 200 saudável/degradado, 503 não-saudável.
GET /api/status	Estado do agente: registered, online, paused, revoked, e status de upload/inferência/telemetria/atualização.
GET /healthz	Liveness simples (sempre 200 se o processo está de pé).
GET /readyz	Readiness (503 se não registrado ou sem sincronizar há muito tempo).

curl -fsS http://127.0.0.1:8088/api/health | jq .
curl -fsS http://127.0.0.1:8088/api/status | jq .

O serviço não inicia

systemctl status zarv-agent
journalctl -u zarv-agent -b | tail -50

• Confirme que o binário existe: /usr/local/bin/zarv-agent.
• Confirme o conffile: /etc/default/zarv-agent.
• O serviço roda como o usuário zarv-agent; o diretório de dados /var/lib/zarv-agent deve pertencer a ele. Reinstalar o pacote corrige a posse automaticamente.

A interface local não abre

• O agente escuta em 0.0.0.0:8088 por padrão (EDGE_AGENT_HTTP_LISTEN).
• Verifique a porta:

curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/   # → 200
ss -lntp | grep 8088

• Se outra aplicação usa a 8088, altere EDGE_AGENT_HTTP_LISTEN em /etc/default/zarv-agent e reinicie.

O agente fica "offline"

O agente precisa de saída HTTPS (porta 443) para collector.zarv.com.

# Resolução de DNS + conectividade
getent hosts collector.zarv.com
curl -fsS -o /dev/null -w "%{http_code}\n" https://collector.zarv.com

• Libere collector.zarv.com:443 no firewall/proxy de saída.
• O estado online é determinado por sondagem periódica de conectividade; após liberar a rede, o agente volta a online automaticamente.

"Registro necessário" / revogado

Se a interface mostrar aviso de registro ou /api/status retornar "revoked": true, o acesso foi cancelado na Zarv. Gere uma nova chave de enrollment e re-registre — veja Registro › Re-registro.

Câmeras não aparecem / sem eventos

• As câmeras são configuradas centralmente pela Zarv; confirme que o edge-server tem câmeras atribuídas no painel.
• O agente precisa de rota até as câmeras (RTSP/ONVIF) dentro do perímetro.
• A interface local mostra a saúde por câmera (conectividade + qualidade de imagem) na visão de câmeras.

Disco cheio

O agente monitora a partição de dados. Acima de ~95% de uso ele entra em modo degradado: recusa novas gravações de blobs e reduz a retenção de eventos pendentes; recupera abaixo de ~80%.

df -h /var/lib/zarv-agent

Libere espaço na partição de /var/lib/zarv-agent (ou aponte EDGE_AGENT_DATA_DIR para um volume maior e reinicie).

A atualização não aplica

• Veja o estado em /api/status (campo de atualização) ou no painel da Zarv.
• Se o estado for waiting_window, há uma janela de manutenção configurada e o agente aplicará a atualização quando a janela abrir.
• error traz a última falha; confira também a conectividade de saída.