Coletores¶
Coletores executam os plugins perto dos dispositivos e enviam os dados à plataforma. Permissão:
collectors.manage.

Coletor local (padrão)¶
O compose sobe o serviço collector com o token QV_COLLECTOR_TOKEN. No boot, a API registra
(ou reassocia) o coletor coletor-local (“Data center principal”, transporte NATS, marcado
como padrão). Não é preciso fazer nada na GUI.
Registrar um coletor adicional¶
- Registrar coletor: nome (letras, números,
.,-,_), site/localização, transporte (https, recomendado entre sites, só saída 443; ounats, na mesma rede) e tenant opcional. - A tela mostra o token (
qvc_…, exibido uma única vez) e o comandodocker runpronto:
docker run -d --name quantix-collector --restart unless-stopped \
-e QV_API_URL=https://quantix.empresa.local -e QV_COLLECTOR_TOKEN=qvc_... \
-e QV_COLLECTOR_NAME=coletor-sp -e QV_COLLECTOR_TRANSPORT=https \
quantix/quantix-vision-backend:8.3.0 collector
QV_API_URL vem de general.base_url (Configurações › Geral). Se estiver vazio, o comando mostra
um marcador <endereco-da-plataforma>. Alternativas: playbook Ansible collector.yml ou runbook
Implantar coletor remoto (Coletor remoto).
- Atribua dispositivos ao coletor (campo Coletor no cadastro do dispositivo).
Instalar em um host remoto (sem docker run manual)¶
O botão Instalar em host remoto (e a ação de mesmo nome em cada linha) abre um assistente que implanta o coletor em um host Linux remoto inteiramente pela interface, via SSH, usando o runbook Implantar coletor remoto (Automação). Restrito a superadministradores.
- Coletor: registre um novo coletor (nome, site, transporte) ou escolha um já cadastrado. Em ambos os casos a implantação gera um token novo, entregue somente ao host de destino.
- Host remoto: informe host/IP de destino, usuário SSH e a credencial SSH (do tipo chave SSH ou usuário/senha, cadastrada em Credenciais). Clique em Implantar via SSH.
- Progresso: o assistente acompanha o job de automação em tempo real (estado e saída do Ansible). O runbook instala o Docker (se necessário) e sobe o container. Se o runbook exigir aprovação (risco médio), o job fica aguardando aprovação em Automação › Execuções até que um segundo usuário decida (segregação de funções). Ao concluir, o coletor aparece Online em até ~30 s.
O comando
docker runcontinua disponível como alternativa dentro do próprio assistente (seção Instalação manual) e na tela de token ao registrar o coletor.
Colunas e estados¶
| Coluna | Origem |
|---|---|
| Status | Online se houve heartbeat nos últimos 120 s; Pendente se nunca conectou; Offline caso contrário (a engine também marca offline após 3 min) |
| Versão, Host | enviados no heartbeat (a cada ~30 s) |
| Utilização | indicador de saúde do coletor (seção abaixo) |
| Dispositivos | quantidade atribuída |
| Ciclos ok / erro, Linhas publicadas | estatísticas acumuladas desde o início do processo coletor |
Ações: Editar, Gerar novo token (o anterior deixa de valer imediatamente; atualize o container) e Excluir (só sem dispositivos atribuídos).
Indicador de utilização¶
Cada coletor mede a própria carga numa janela deslizante de 15 minutos e a envia no heartbeat. A coluna Utilização mostra o maior destes indicadores (o primeiro recurso a saturar define a capacidade); passe o mouse sobre a barra para ver o detalhe:
| Indicador | Como é calculado | O que significa perto de 100% |
|---|---|---|
| Slots de coleta | segundos de slot ocupados ÷ (janela × concorrência collection.max_parallel_devices) |
dispositivos esperam na fila para serem coletados |
| Duração dos ciclos | p95 de (duração do ciclo de performance ÷ intervalo de performance), incluindo a espera pelo slot | o ciclo não cabe no intervalo: amostras atrasam ou estouram o timeout |
| CPU do processo | tempo de CPU do processo ÷ tempo decorrido ÷ número de CPUs do host | o host do coletor está pequeno |
| Memória do processo | memória residente ÷ RAM do host (quando o sistema informa) | risco de OOM no container |
Níveis (configuráveis em Configurações › Coleta):
- Normal: abaixo de
collection.collector_utilization_warn_pct(padrão 70%). - Alta: a partir desse limite; a tela exibe no topo um cartão sugerindo criar mais coletores, com o número recomendado, o botão Criar coletor (abre o registro e, em seguida, o comando de instalação) e o link para o guia Coletor remoto.
- Saturado: a partir de
collection.collector_utilization_critical_pct(padrão 90%). - —: coletor offline ou aguardando o primeiro contato (sem medição atual).
O número de coletores sugeridos considera a soma da utilização dos coletores online, visando deixar cada um abaixo de ~85% do limite. Quando outros coletores têm folga, o cartão indica que redistribuir dispositivos (campo Coletor no cadastro do dispositivo) também resolve.
Coletores de versões anteriores não reportam a carga: a utilização é estimada (marcada como
estimada) pelo número de dispositivos ativos, ponderado pelo intervalo de performance (um switch a
60 s pesa ~2,2 dispositivos de 5 min), contra collection.collector_device_capacity (padrão 25).
Atualize o coletor para obter a medição real.
Atalhos: /admin/coletores?novo=1 abre a tela já com o registro de coletor aberto; a tela
Sistema também mostra um aviso quando há coletores acima do limite. A API expõe o resumo em
GET /api/v1/collectors/health (permissão de leitura) e o objeto health em cada item de
GET /api/v1/collectors.
Dimensionamento¶
Um coletor de 4 vCPU/4 GB com concorrência 64 atende ~25 dispositivos ou ~10 mil portas SAN. O limite prático costuma ser o número de sessões simultâneas aceitas pela gerência de cada array. Use um coletor por site ou fabric. Veja Escalabilidade.