Pular para conteúdo

Coleta

Contrato dos plugins

Cada plugin conhece uma interface de uma família de dispositivos, por exemplo REST do Unisphere for PowerMax, CLI SSH do Storage Virtualize ou SDK do vSphere. O contrato está em backend/quantix/collector/plugins/base.py e tem três métodos assíncronos:

Método Retorna Uso
test_connection() TestResult(ok, message, vendor, model, serial, firmware, details) botão “Testar conexão”. Preenche fabricante, modelo, serial e firmware do dispositivo
collect_inventory() Inventory (entidades, relações, identificadores, device_info) snapshot completo a cada inventory_interval_s
collect_performance() PerfBatch (colunar: tipo, id nativo, métrica, valor, ts) a cada perf_interval_s

O plugin nunca fala com banco ou barramento: ele devolve objetos, e o agendador do coletor publica. Isso permite testar cada plugin isoladamente com respostas gravadas.

Regras de normalização (obrigatórias):

  • nomes de tipo de objeto, relação e métrica vêm de quantix/common/catalog.py (catálogo). O teste assert_catalog reprova nomes fora dele;
  • latência em ms, throughput em MB/s decimais (10⁶ bytes), capacidade em bytes;
  • contadores cumulativos viram taxa (ctx.rate) ou delta por intervalo (ctx.delta). O estado fica em ctx.state entre ciclos, e reset ou wrap do contador descarta o ponto;
  • native_id estável (ID interno do fabricante, nunca o nome quando há ID);
  • WWPN/WWNN normalizados com ids.normalize_wwn (16 hex minúsculos) e NAA do LUN com ids.normalize_naa. São eles que permitem a correlação.

Metadados de classe exibidos na GUI (CollectorPlugin.describe()): key, vendor, product, category (storage | san_switch | virtualization | file_object), interface (rest | ssh | sdk | snmp), default_port, option_fields, credential_kinds, min_perf_interval_s e requirements. O passo a passo para criar um plugin está em Criando um plugin.

Ciclo de vida do coletor

stateDiagram-v2
  [*] --> Config: GET /api/v1/collector/config (X-Collector-Token)
  Config --> Agendado: reconcile(devices)
  Agendado --> Inventario: laço de inventário
  Agendado --> Performance: laço de performance (alinhado)
  Inventario --> Publica
  Performance --> Publica
  Publica --> Agendado
  Agendado --> Tarefas: a cada 5 s GET /collector/tasks
  Tarefas --> Agendado: test / collect_now / reload
  Agendado --> Status: a cada 15 s POST /collector/status
  Agendado --> Heartbeat: a cada 30 s POST /collector/heartbeat
  Agendado --> Config: a cada 60 s (recarrega e reconcilia)
  • Credenciais só em memória. A configuração baixada da API traz as credenciais decifradas dos dispositivos atribuídos. Elas trafegam apenas em TLS (no transporte HTTPS) e não são gravadas em disco. O container do coletor roda com sistema de arquivos somente leitura e /var/lib/quantix em tmpfs.
  • Agendamento alinhado. O laço de performance espera a próxima fronteira do intervalo ((t // intervalo + 1) × intervalo). Assim, métricas de dispositivos diferentes caem nos mesmos timestamps (:00, :05, :10…), e comparações e somas entre arrays ficam corretas sem reamostragem.
  • Isolamento por dispositivo. Cada dispositivo tem duas tarefas asyncio independentes. Um semáforo limita a concorrência (collection.max_parallel_devices, padrão 32; ou QV_COLLECTOR_CONCURRENCY até a configuração chegar), e há timeout por ciclo: inventário max(300 s, 10 × request_timeout_s) e performance max(60 s, 0,9 × intervalo). Um array lento não atrasa os demais.
  • Reconciliação. A cada 60 s, ou com uma tarefa reload disparada pela API quando um dispositivo é criado/alterado, o coletor compara uma assinatura (plugin, endereços, porta, opções, TLS, intervalos, credencial, tenant) e reinicia apenas os dispositivos alterados.
  • Status e falhas. Cada ciclo gera um registro de status. A API marca o dispositivo ok no sucesso, warning na 1ª e 2ª falha seguida e error a partir da 3ª, e guarda a mensagem em last_error com prefixo [inventory] ou [performance]. A engine marca como offline o coletor sem heartbeat há mais de 3 min. A listagem da GUI considera online quem enviou heartbeat nos últimos 120 s.

Transporte

Transporte Quando usar Caminho dos dados Portas
nats (padrão do coletor local) coletor na mesma rede da plataforma publica direto no JetStream e no object store 4222 (NATS) + 443/8000 (API)
https sites remotos atrás de firewall POST /api/v1/ingest/metrics e /ingest/inventory (msgpack + zlib); a API repassa ao JetStream somente saída 443 até o servidor

No HTTPS, o nginx aceita corpos de até 200 MB em /api/v1/ingest/ sem bufferizar em disco. O coletor valida o certificado do servidor (verify=True). Uma CA corporativa pode ser montada e apontada em SSL_CERT_FILE (role Ansible collector, variável collector_ca_bundle_src).

Sites remotos

flowchart LR
  subgraph SiteSP["Site remoto (filial)"]
    D1[arrays / switches / vCenter] --> CR[coletor-sp<br/>QV_COLLECTOR_TRANSPORT=https]
  end
  CR -- "443/TCP (TLS)" --> FW{{Firewall}} --> NG[web nginx] --> API[api] --> NATS[(JetStream)]
  1. Registre o coletor em Administração › Coletores (gera um token qvc_… exibido uma vez e o comando docker run).
  2. Instale com o comando exibido, com o playbook deploy/ansible/collector.yml ou com o runbook Implantar coletor remoto. Veja Coletor remoto.
  3. Atribua os dispositivos do site ao coletor no cadastro do dispositivo. Com collection.auto_assign ativo, novos dispositivos vão para o coletor online com menos dispositivos.

Segurança das credenciais

Etapa Proteção
Armazenamento credentials.secret_enc: JSON cifrado com Fernet (AES-128-CBC + HMAC-SHA256) usando a chave mestra QV_MASTER_KEY
API segredos nunca são devolvidos. A GUI recebe apenas secret_fields_set (quais campos estão definidos). Campos vazios na edição mantêm o valor atual
Distribuição ao coletor somente para coletores autenticados por token (hash HMAC-SHA256 com a chave mestra em collectors.token_hash). O coletor recebe só os seus dispositivos
Coletor apenas em memória, com container somente leitura
Automação variáveis extras em arquivo temporário 0600, removido ao final. Tarefas sensíveis dos playbooks usam no_log

Tipos de credencial (kind): userpass, token, ssh_key (chave privada + frase-senha opcional), snmpv3 (estrutura snmp com protocolos e senhas) e none. Cada plugin declara quais aceita (credential_kinds). Exemplos: Pure usa token; Storage Virtualize aceita userpass ou ssh_key.

Validação dos certificados dos dispositivos

verify_tls é desligado por padrão no cadastro do dispositivo, porque a maioria das interfaces de gerência usa certificados autoassinados. Ative-o (e instale a CA no coletor) sempre que possível. O SSH usa known_hosts=None, ou seja, não verifica a chave do host. Em ambientes exigentes, restrinja o acesso de rede do coletor às redes de gerência.