Engine de análise¶
A engine (quantix engine, pacote backend/quantix/engine/) transforma métricas e inventário em
saúde, achados priorizados e previsões. Ela roda em ciclos de ~30 s, e em cada ciclo
executa os jobs vencidos:
| Job | Frequência | Módulo | Resultado |
|---|---|---|---|
correlate (+ regras de configuração) |
analytics.correlation_interval_s (900 s) |
correlator.py, config_rules.py |
relações entre fontes; achados de topologia/zoning |
ratings |
analytics.ratings_interval_s (300 s) |
ratings.py |
tabela health, health_history e achados de performance, capacidade, erros e replicação |
applications |
15 min | applications.py |
membros, saúde e métricas agregadas das aplicações |
change |
1 h | change_detection.py |
achados de mudança de workload |
balance |
1 h | balance.py |
achados de desbalanceamento |
forecast |
6 h | forecast.py |
tabela forecasts e achados de esgotamento |
alerts |
1 min | alerts.py |
notificações e runbooks automáticos |
collectors |
1 min | service.py |
marca como offline coletores sem heartbeat há > 3 min |
summary |
diário, a partir de ai.daily_summary_hour |
reports.py |
resumo executivo (engine ou IA) |
housekeeping |
diário | service.py |
retenção de achados, mudanças, auditoria, tarefas e objetos removidos |
Cada job roda dentro de pg_try_advisory_lock(hash(nome)). Com várias réplicas da engine, só
uma executa cada job por vez, e as outras pulam (Alta disponibilidade).
A falha de um job é registrada no log e não interrompe os demais.
Primeiro ciclo
Os intervalos são contados a partir do início do processo, então no primeiro ciclo (~30 s após subir) todos os jobs executam. Change detection e previsão só produzem resultado quando há histórico suficiente (veja abaixo).
Ratings: saúde com thresholds dinâmicos¶
Para cada objeto de storage_system, controller, pool, volume, storage_port, switch_port, vm,
hypervisor, datastore, replication, cluster, file_system, bucket, switch, a engine lê a média
dos últimos 20 min de cada métrica (e a soma/média da última hora para erros de porta) e
classifica a métrica:
nível(v) = crítico se v >= limite_crítico
aviso se v >= limite_aviso
ok caso contrário
score = menor valor entre as métricas avaliadas, com ok = 100, aviso = 60, crítico = 20
O nível do objeto é o pior entre as métricas avaliadas. O que torna os limites “dinâmicos”:
| Métrica | Objetos | Limite | Por quê |
|---|---|---|---|
lat_ms |
volume, pool, sistema, controladora | thresholds.{flash\|hybrid}_latency_{warn,crit}_ms × fator de tamanho de I/O |
mídia vem do atributo media do sistema ou do modelo de capacidade. Blocos grandes demoram mais para transferir: fator = 1 até 32 KiB e 1 + (io_kb − 32)/64 acima (64 KiB → 1,5; 256 KiB → 4,5). Volumes com < 5 IOPS são ignorados, porque a latência medida é instável com pouca carga |
lat_ms |
VM, datastore, cluster, hipervisor | thresholds.vm_latency_* (10/25 ms) |
latência percebida pelo guest inclui a pilha de virtualização |
util_pct |
controladora | modelo de capacidade (abaixo) e o maior entre esse valor e cpu_pct |
“utilização” de controladora não é um número fixo de IOPS |
util_pct |
porta de storage/switch | 100 × max(rx, tx) / (100 × Gbit/s negociado) |
banda útil FC ≈ 100 MB/s por Gbit/s (codificação e overhead) |
cpu_pct, mem_pct |
hipervisor, cluster | CPU: util_warn+10 / util_crit+7 (80/92 %); memória: 90/97 % |
hosts de virtualização operam normalmente mais carregados |
cap_used_pct |
sistema, pool, datastore, file system, bucket, cluster | thresholds.capacity_*_pct (80/90 %) |
— |
port_errors |
porta de switch/storage, HBA | soma de CRC + enc-out + falhas de link + descartes classe 3 na última hora vs thresholds.port_errors_* (10/100) |
erros físicos são cumulativos; a janela de 1 h evita ruído |
bb_credit_zero_ms |
idem | média por intervalo na última hora vs thresholds.bb_credit_zero_*_ms (100/1000) |
indicador primário de slow drain |
repl_lag_s |
replicação | thresholds.repl_lag_*_s (300/1800 s) |
RPO |
cpu_ready_pct |
VM | 5 / 10 % (fixo) | — |
Modelo de capacidade da controladora (capacity_models.py): cada família tem IOPS e MB/s
máximos por controladora (tabela REFERENCE, estimativas conservadoras públicas; por exemplo, PowerMax 8000
1,5 M IOPS/35 GB/s, FlashArray 350 mil/12 GB/s, padrão 200 mil/6 GB/s). Se o coletor informar
max_iops/max_mbps/controllers no sistema, esses valores prevalecem.
util% = max( 100 × (IOPS_leitura + w × IOPS_escrita) / IOPS_máx , 100 × MB/s / MB/s_máx )
w = 2,0 (flash) | 3,0 (híbrido/HDD)
Sem o mix leitura/escrita, assume-se 70/30. O peso de escrita reflete cache espelhado e penalidade de RAID. O máximo entre IOPS e banda captura o limite de blocos grandes.
Agregação hierárquica. Componentes degradados (até 3 níveis acima) colocam o pai
(storage_system, switch, cluster, pool, controller) em aviso, com score ≤ 75 (filho em
aviso) ou ≤ 60 (filho crítico), e a métrica sintética componentes conta os filhos com problema.
Um componente crítico deixa o sistema em aviso, não crítico: um volume lento não deve
pintar o array inteiro de vermelho.
Exceções (thresholds personalizados) são resolvidas na ordem objeto → dispositivo+tipo → tipo e substituem o limite já calculado (no caso da latência, o valor da exceção não é multiplicado pelo fator de I/O). Uma exceção pode trocar limites ou desativar a avaliação (Thresholds).
Saúde sem dados há mais de 1 h é removida (o objeto volta a “sem dados”). Achados de volume são limitados a 100 por ciclo (os mais graves).
Detecção de mudanças (change detection)¶
Compara as últimas 8 h (rollup horário) com a mesma hora do dia nos
analytics.change_baseline_days (14) dias anteriores, com estatística robusta:
em que B_h são os valores da mesma hora h nos dias de referência (no mínimo 3 valores) e
MAD é a mediana dos desvios absolutos. Racional:
- Mediana/MAD não são distorcidos por picos antigos (um backup anômalo na semana passada não “alarga” a linha de base, ao contrário de média e desvio padrão). O fator 1,4826 torna o MAD comparável ao σ.
- Sazonalidade diária: comparar 14h com 14h evita alarmes pelo ciclo normal dia/noite.
- Pisos (5 % da mediana e piso absoluto por métrica, por exemplo 200 IOPS para sistemas e 0,1 ms para latência) evitam z enormes em séries quase constantes.
Um achado só é gerado se o desvio persistir por analytics.change_min_hours (3) horas
consecutivas no mesmo sentido, contadas a partir da hora mais recente. Severidade, com
z_max da sequência: crítico se z_max ≥ change_z_critical (7) e o sentido é ruim;
aviso se o sentido é ruim; info caso contrário. “Sentido ruim” é subir em métricas
higher_is_worse (latência, CPU) e qualquer sentido em IOPS/MB/s (queda de carga pode
indicar aplicação parada). Séries avaliadas: IOPS e latência de sistemas, controladoras, pools,
volumes e VMs; MB/s de portas; IOPS/CPU de hipervisores; IOPS de clusters e datastores. No máximo
150 achados por execução.
Histórico necessário
São necessários pelo menos 3 dias de rollup horário anteriores às últimas 8 h na mesma hora do dia. Com menos histórico, a série é ignorada sem erro.
Previsão de capacidade (Theil-Sen)¶
Para storage_system, pool, datastore, file_system, cluster, bucket, a engine lê o último valor
diário de cap_used_bytes e cap_total_bytes nos últimos analytics.forecast_history_days (90)
dias e ajusta:
inclinação β = mediana, sobre todos os pares de dias i < j, de (y_j − y_i) / (x_j − x_i)
intercepto α = mediana(y − β·x)
dias até p% = (p × capacidade − uso_atual) / β
- Theil-Sen (mediana das inclinações entre todos os pares de dias) é robusto a degraus pontuais, como limpeza de snapshots ou migração. Uma regressão linear comum seria puxada por eles.
- A faixa de incerteza do crescimento usa os percentis 10 e 90 das inclinações. O “cenário pessimista” do achado usa o percentil 90.
- Calcula dias até 80 %, 90 % e 100 % (0 se já atingido; vazio se o crescimento é ≤ 0) e R² como indicador de aderência.
- Mínimo de 5 dias com uso > 0. Achado
capacity_forecastquando o esgotamento previsto ocorre em ≤thresholds.capacity_days_warn(90) dias, e crítico se ≤capacity_days_crit(30).
Balanceamento (coeficiente de variação)¶
Grupos de irmãos que deveriam dividir a carga, avaliados pela média de 24 h (rollup horário):
| Grupo | Métrica | Carga mínima média para avaliar |
|---|---|---|
| controladoras de um sistema | iops |
1.000 IOPS |
| portas front-end de um sistema (porta → controladora → sistema) | mbps |
analytics.balance_min_load_mbps (50 MB/s) |
| hipervisores de um cluster | cpu_pct |
10 % |
Achado se CV ≥ analytics.balance_cv_warning (0,35); crítico se CV ≥ 2 × o limite.
A evidência mostra a participação de cada membro. Por que importa: o componente mais carregado
satura primeiro (capacidade útil menor) e, no failover, o sobrevivente precisa absorver tudo.
Regras de configuração¶
Consultas SQL sobre topologia e identificadores (config_rules.py), executadas junto com a
correlação. A lista completa com condições e severidades está em
Regras da engine: fabric único (host e hipervisor),
datastore com menos de 2 caminhos, volumes órfãos, zonas mortas, login sem zona, zoning
assimétrico e mapeamento sem login.
Correlação entre fontes¶
Cada coletor só enxerga seu equipamento. O correlacionador liga objetos por identificadores
universais gravados pelos plugins na tabela identifiers (kind, value, role):
| Relação criada | Regra | Exemplo |
|---|---|---|
logged_in |
WWPN próprio (role=self) de iniciador, HBA ou porta de array = WWPN logado (role=peer) em porta de switch |
HBA do ESXi → porta 12 do switch |
same_as |
HBA do hipervisor e iniciador do host no array com o mesmo WWPN | HBA vmhba2 ≡ iniciador do host group |
backed_by |
datastore com NAA de backing (role=backing) = NAA do volume (role=self) |
datastore DS01 → LUN 0x1A |
zoned_with |
WWPN membro de zona (role=member) = WWPN próprio de um objeto |
iniciador ↔ zona |
As relações de origem correlator são recalculadas a cada execução (conjunto em tabela
temporária, depois remoção das que sumiram e inserção das novas). Assim, mudanças de zoning,
mapeamento ou migração de datastore se refletem sozinhas. Os identificadores usam o índice
(kind, value), e a operação é de conjunto, sem laços em Python.
Ciclo de vida dos achados e prioridade¶
Cada achado tem um fingerprint = regra:entidade:chave (findings.py). A cada execução de um
job, o FindingSink:
stateDiagram-v2
[*] --> open: detectado
open --> open: reaparece (atualiza evidência e re-notifica se piorar)
open --> acknowledged: usuário reconhece
open --> muted: usuário silencia
open --> resolved: ausente em 2 execuções seguidas (grace) ou usuário resolve
acknowledged --> resolved: ausente em 2 execuções / usuário
resolved --> open: reincidência (novo first_seen)
muted --> muted: nunca resolve sozinho
- Escalonamento: se a severidade sobe, o achado é marcado para notificação de novo, ignorando a janela de deduplicação.
- Preservação: notas, explicação da IA e controle de notificação sobrevivem às atualizações.
- Prioridade (0–100), usada para ordenar todas as listas:
| Termo | Valores |
|---|---|
S_sev |
crítico 70 · aviso 40 · info 10 |
B_cat |
availability 15 · errors 10 · capacity 8 · performance 8 · configuration 5 · change 3 · balance 2 |
m |
magnitude 0–1 definida pela regra (ex.: z/(2·z_crit), CV, valor/limite) |
A_app |
maior criticidade de aplicação que contém o objeto: critical 15 · high 8 · medium 3 · low 0 |
Achados resolvidos são apagados após retention.findings_days (365).
Aplicações¶
A cada 15 min, para cada aplicação: (1) avalia as regras (tipo de objeto + campo name/tag/attr
+ operador contains/equals/starts_with/regex, até 5.000 objetos); (2) sincroniza os membros
de origem rule, preservando os manuais; (3) recria as relações member_of (aplicação → objetos)
usadas na topologia; (4) define a saúde da aplicação como a do pior membro; (5) grava no
ClickHouse as métricas da entidade application dos últimos 10 min: IOPS e MB/s somados e latência
média ponderada por IOPS sobre VMs, volumes, datastores, hosts e volume groups membros.
Resumo executivo diário¶
Na primeira execução do dia a partir de ai.daily_summary_hour (7h, horário do processo da
engine), é gerado um relatório em Markdown com achados por severidade e categoria, os 10 de maior
prioridade, saúde dos sistemas e as 5 previsões mais urgentes. Com ai.enabled e
ai.daily_summary, o material é enviado ao LLM, que investiga com as ferramentas e redige em
linguagem executiva. Se a IA falhar, a versão da engine é mantida. Os relatórios ficam em
Insights › Relatórios executivos.