Pular para conteúdo

Armazenamento

O Quantix separa os dados em dois bancos, cada um escolhido pelo padrão de acesso:

ClickHouse (qv.*) PostgreSQL (quantix)
Dados pontos de métrica (append-only), rollups, último valor, histórico de saúde inventário, topologia, identificadores, configuração, usuários, achados, auditoria
Volume no porte alvo ~1,04 × 10⁹ linhas/dia ~200 mil–3 milhões de objetos/relações
Padrão escrita em lote contínua; leitura analítica (agregações, top-N, séries) leitura/atualização transacional, joins de grafo, busca textual
Código common/tsdb.py, common/query.py common/models.py, common/db.py, ingestor/inventory.py

Por que ClickHouse para métricas

  1. Colunar, ordenado por (tenant, entity_type, metric, entity_id, ts). Uma consulta “latência de todos os volumes nas últimas 24 h” lê apenas as colunas entity_id, ts e value do intervalo contíguo daquela métrica. A ordenação por série deixa valores vizinhos parecidos, o que favorece a compressão.
  2. Codecs especializados. ts usa DoubleDelta + ZSTD (timestamps regulares viram quase zero) e value usa Gorilla + ZSTD (XOR de floats consecutivos). As dimensões são LowCardinality(String). Medido: 6,0–7,4 bytes/ponto em disco (compressão de 6,3–7,5×), ver Escalabilidade.
  3. MergeTree: inserts em lote viram partes imutáveis que o servidor funde em segundo plano. Não há locks de linha nem vacuum.
  4. Materialized views calculam rollups no momento do insert, sem jobs de agregação.
  5. TTL por tabela implementa a retenção em camadas sem rotinas de limpeza.
  6. Escala horizontal com ReplicatedMergeTree + Distributed (cluster).

O backend chdb (ClickHouse embutido no processo) executa o mesmo SQL e é usado no laboratório e nos testes automatizados.

Schema

DDL gerado por schema_statements() e aplicado (idempotente) no boot da API, do ingestor e da engine:

Tabela Engine Partição Chave de ordenação TTL (variável da GUI) Conteúdo
metrics MergeTree toYYYYMMDD(ts) (tenant, entity_type, metric, entity_id, ts) retention.raw_days (35) pontos brutos tenant, device_id, entity_id, entity_type, metric, ts, value
metrics_1h AggregatingMergeTree toYYYYMM(ts) idem retention.hourly_days (400) estados avg, min, max, sum, quantileTDigest(0.95), argMax (último), count por hora
metrics_1d AggregatingMergeTree toYear(ts) idem retention.daily_days (1830) idem por dia
metrics_latest AggregatingMergeTree — (tenant, entity_type, metric, entity_id) sem TTL último valor (argMax) e max(ts) por série
health_history MergeTree toYYYYMM(ts) (tenant, entity_type, entity_id, ts) retention.hourly_days score e nível de saúde por ciclo (sistemas, controladoras, pools, portas, switches, hipervisores, clusters, datastores, replicações, aplicações)

Views: metrics_1h_mv, metrics_1d_mv e metrics_latest_mv (TO as tabelas acima).

Correção do valor last nos rollups

No SELECT das views, o alias ts (balde) sombreia a coluna original. Por isso o argMax usa src.ts (timestamp bruto). Instalações com views antigas são migradas automaticamente no boot (_migrate_rollup_views: views sem src.ts são recriadas).

Alterar a retenção na GUI executa ALTER TABLE … MODIFY TTL nas quatro tabelas com TTL (apply_retention), ON CLUSTER quando em cluster.

Escolha automática de resolução

O QueryEngine (common/query.py) escolhe a tabela pelo tamanho da janela e limita cada série a ~1.500 pontos para o navegador:

Janela consultada Tabela Passo
≤ 2 dias metrics múltiplo de 60 s (ex.: 24 h → 60 s)
≤ 120 dias metrics_1h múltiplo de 3.600 s
> 120 dias metrics_1d 86.400 s

Agregações (avg | max | min | p95 | sum | last) são mapeadas para a função bruta ou para o *Merge do estado correspondente. A agregação padrão vem do catálogo (capacidade usa last, erros usam sum). Nenhum texto do usuário é concatenado ao SQL: tipo e métrica são validados contra o catálogo, a agregação contra uma lista fechada, e os valores vão como parâmetros (server-side binding no ClickHouse; escape de literais no chdb).

Sharding e replicação

Com QV_CH_CLUSTER definido, o mesmo código cria tabelas locais qv_local.* com Replicated*MergeTree (ON CLUSTER), views locais e tabelas Distributed(cluster, qv_local, <tabela>, cityHash64(entity_id)) em qv.*. A aplicação continua usando os mesmos nomes. Como o sharding é feito por entidade, rollups, argMax e percentis de uma série são sempre calculados inteiros em um único shard. Detalhes em ClickHouse em cluster.

Por que PostgreSQL para inventário e configuração

  • Integridade: chaves estrangeiras com ON DELETE CASCADE (excluir um dispositivo remove suas entidades, relações e identificadores), unicidades (uq_device_tenant_name, uq_relation, uq_identifier) e transações. O snapshot de um dispositivo é aplicado de forma atômica.
  • JSONB + GIN: atributos específicos de cada fabricante ficam em entities.attrs sem migrações de schema por plataforma (índice ix_entities_attrs).
  • pg_trgm: a busca global (Ctrl+K) usa similaridade trigram em entities.name (ix_entities_name_trgm), tolerante a erros de digitação.
  • Grafo relacional: relations com índices por origem e por destino permite percorrer a topologia em largura (common/topology.py). As regras de configuração SAN são consultas SQL sobre relations + identifiers.
  • Carga eficiente: snapshots com centenas de milhares de volumes entram por COPY em tabelas temporárias, seguido de merge SQL. Medido: 202 mil objetos e 402 mil relações em 22,6 s (primeiro snapshot) e 28,8 s (snapshot incremental com diff), no sandbox de 2 vCPU.

O schema é criado por Base.metadata.create_all no boot (idempotente) junto com CREATE EXTENSION IF NOT EXISTS pg_trgm. Migrações incrementais futuras usarão Alembic (dependência já declarada). Na v1.0.0 não há scripts de migração, porque o schema inicial é criado por completo.

Modelo relacional principal

erDiagram
  tenants ||--o{ devices : "tenant_id"
  tenants ||--o{ user_roles : "escopo"
  users ||--o{ user_roles : ""
  roles ||--o{ user_roles : ""
  users ||--o{ api_tokens : ""
  directories ||--o{ users : "directory_id"
  credentials ||--o{ devices : "credential_id"
  collectors ||--o{ devices : "collector_id"
  collectors ||--o{ collector_tasks : ""
  devices ||--o{ entities : "device_id"
  entities ||--o{ identifiers : "WWPN, NAA, IQN, serial"
  entities ||--o{ relations : "src_id / dst_id"
  entities ||--o| health : "estado atual"
  entities ||--o| forecasts : "capacidade"
  entities ||--o{ findings : "entity_id"
  applications ||--o{ application_members : ""
  entities ||--o{ application_members : ""
  playbooks ||--o{ automation_jobs : ""
  findings ||--o{ automation_jobs : "finding_id"
  alert_rules }o--o{ alert_channels : "channel_ids[]"
  users ||--o{ dashboards : "owner_id"
  users ||--o{ chat_sessions : ""
  entities {
    uuid id PK "UUID5(device, tipo, id nativo)"
    uuid device_id FK
    text type
    text native_id
    text name
    uuid parent_id
    jsonb attrs
    text_arr tags
    timestamptz deleted_at "remoção lógica"
  }
  relations {
    bigint id PK
    uuid src_id FK
    uuid dst_id FK
    text kind "contains, maps_to, logged_in..."
    text origin "collector, correlator, application"
  }
  findings {
    uuid id PK
    text fingerprint UK "regra:entidade:chave"
    text category
    text rule
    text severity
    float score "prioridade 0-100"
    text status "open, acknowledged, muted, resolved"
    jsonb evidence
  }

Outras tabelas: settings (variáveis da GUI; segredos cifrados), config_changes (trilha de mudanças), threshold_overrides, reports (resumo executivo), audit_log.

Ciclo de vida de objetos removidos: um objeto ausente do snapshot recebe deleted_at (some das telas e da topologia). A limpeza diária (housekeeping) apaga em definitivo os removidos há mais de 30 dias.

Retenção — resumo

Dado Onde Controle Padrão
métricas brutas qv.metrics retention.raw_days 35 dias
rollup horário e histórico de saúde qv.metrics_1h, qv.health_history retention.hourly_days 400 dias
rollup diário qv.metrics_1d retention.daily_days 1830 dias
achados resolvidos e mudanças de configuração PostgreSQL retention.findings_days 365 dias
auditoria PostgreSQL retention.audit_days 730 dias
tarefas de coletor PostgreSQL fixo 2 dias
objetos removidos PostgreSQL fixo 30 dias
buffer do barramento JetStream QV_DATA código (ensure_streams) 6 h / 20 GiB

Retenção e disco

Os rollups ocupam mais espaço por linha que os pontos brutos, porque o estado do percentil quantileTDigest é grande. Com os padrões (400 e 1830 dias), os rollups dominam o disco no longo prazo. Veja a projeção e a recomendação em Escalabilidade.