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 testeassert_catalogreprova 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 emctx.stateentre ciclos, e reset ou wrap do contador descarta o ponto; native_idestá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 comids.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/quantixem 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; ouQV_COLLECTOR_CONCURRENCYaté a configuração chegar), e há timeout por ciclo: inventáriomax(300 s, 10 × request_timeout_s)e performancemax(60 s, 0,9 × intervalo). Um array lento não atrasa os demais. - Reconciliação. A cada 60 s, ou com uma tarefa
reloaddisparada 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
okno sucesso,warningna 1ª e 2ª falha seguida eerrora partir da 3ª, e guarda a mensagem emlast_errorcom prefixo[inventory]ou[performance]. A engine marca comoofflineo 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)]
- Registre o coletor em Administração › Coletores (gera um token
qvc_…exibido uma vez e o comandodocker run). - Instale com o comando exibido, com o playbook
deploy/ansible/collector.ymlou com o runbook Implantar coletor remoto. Veja Coletor remoto. - Atribua os dispositivos do site ao coletor no cadastro do dispositivo. Com
collection.auto_assignativo, 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.