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¶
- 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 colunasentity_id,tsevaluedo intervalo contíguo daquela métrica. A ordenação por série deixa valores vizinhos parecidos, o que favorece a compressão. - Codecs especializados.
tsusaDoubleDelta+ ZSTD (timestamps regulares viram quase zero) evalueusaGorilla+ ZSTD (XOR de floats consecutivos). As dimensões sãoLowCardinality(String). Medido: 6,0–7,4 bytes/ponto em disco (compressão de 6,3–7,5×), ver Escalabilidade. - MergeTree: inserts em lote viram partes imutáveis que o servidor funde em segundo plano. Não há locks de linha nem vacuum.
- Materialized views calculam rollups no momento do insert, sem jobs de agregação.
- TTL por tabela implementa a retenção em camadas sem rotinas de limpeza.
- 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.attrssem migrações de schema por plataforma (índiceix_entities_attrs). pg_trgm: a busca global (Ctrl+K) usa similaridade trigram ementities.name(ix_entities_name_trgm), tolerante a erros de digitação.- Grafo relacional:
relationscom í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 sobrerelations+identifiers. - Carga eficiente: snapshots com centenas de milhares de volumes entram por
COPYem 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.