Introdução
Um guia passo a passo para ajudar você a abrir, usar e validar a tela Query Regressions — o detector de regressões de desempenho e anomalias integrado ao NoSqlStudio. Siga do Passo 1 até o fim, em ordem. Cada passo informa o que fazer e o que você verá.
Como ler este manual
Cada passo tem:
- Faça — a ação exata (clicar, digitar, executar tal e tal comando).
- Veja — o que deve acontecer na tela. Este é o seu “passou / falhou”.
- Por quê — contexto adicional, apenas quando ajuda (pule se estiver com pressa).
O que é o Query Regressions
Conceito
Um fingerprint estável, como o sql_id do Oracle
Cada formato de consulta recebe um fingerprint estável que nunca muda entre execuções — a mesma ideia do sql_id do Oracle. O NoSqlStudio aprende um baseline móvel para cada fingerprint e dispara um alerta quando a mesma consulta começa a custar mais: tempo de relógio (wall-clock) mais lento, mais documentos examinados, mais RU ou um plano pior (por exemplo IXSCAN → COLLSCAN).
Conceito
Uma tela, três engines
A mesma tela funciona no MongoDB, no Azure Cosmos DB (Mongo API) e no AWS DocumentDB. A captura é abrangente a toda a instância — ela enxerga consultas lentas de todos os clientes e todos os bancos de dados, não apenas os que você executa pelo NoSqlStudio. É isso que captura uma mudança não declarada durante uma janela de manutenção.
Conceito
Cinco níveis de análise de causa raiz
Cada alerta é explicado em camadas: L1 métricas antes/depois · L2 o diff do plano · L3 investigadores (índices, estatísticas de coleção, cardinalidade) · L4 eventos de DDL/deploy correlacionados em uma janela de ±5 min (“o que mudou logo antes de isto ficar lento”) · L5 uma narrativa de IA.
Antes de começar
Você pode explorar toda a interface com dados de demonstração e sem nenhum banco de dados (Etapas 1–3). A captura ao vivo (Etapas 4–6) precisa de uma conexão, e a fonte de dados depende do engine:
- 1MongoDB — lê o log de consultas lentas do servidor via
getLog:'global'. Funciona em replica sets auto-hospedados e em clusters dedicados do Atlas. Não está disponível nos tiers compartilhados do Atlas (M0/M2/M5), que bloqueiam ogetLog. - 2Cosmos DB — lê logs de diagnóstico do Azure Log Analytics. Requer o Log Analytics configurado em Cloud Credentials (Cosmos Optimizer).
- 3DocumentDB — lê o stream do profiler do DocDB a partir do Amazon CloudWatch Logs. Requer o profiler habilitado no parameter group do cluster, exportado para o CloudWatch, e credenciais AWS definidas em Cloud Credentials.
- 4Uma segunda aba onde você possa executar comandos de shell — o Scratchpad ou o Mongo Shell — para gerar consultas lentas.
Tempo estimado para o passo a passo completo: ~25 minutos.
Abrir a tela (nenhum banco de dados necessário)
Abra a tela e carregue a demonstração integrada para aprender o layout antes de conectar uma fonte ao vivo.
Abrir o Query Regressions
Na barra de ferramentas, escolha Monitoring ▼ → Query Regressions (atalho de teclado Ctrl+Alt+Shift+Q).
Uma nova aba abre com o cabeçalho Query Regressions à esquerda, uma lista mestre e um painel de detalhes à direita.
Carregar os dados de demonstração
Se a lista estiver vazia, clique em Load demo data no estado vazio.
Dois alertas de exemplo aparecem sob um grupo SHOP: uma Plan regression — shop.orders e um Selectivity collapse — shop.events. O cabeçalho mostra um badge vermelho 2 CRITICAL.
A demonstração roda inteiramente em memória — sem servidor, sem permissões. É a forma mais rápida de aprender o que cada seção de um card significa.
Selecionar um alerta
Clique no card Plan regression — shop.orders na lista.
O painel de detalhes é preenchido. O cabeçalho mostra um badge CRIT, o título e, abaixo dele, o fingerprint (um hash estável), o namespace e a contagem de ocorrências.
Anatomia de um alerta
Leia cada seção do painel de detalhes de cima para baixo — este é o mesmo layout para todos os engines.
WHAT CHANGED (Nível 1)
Uma tabela com Signal · Baseline · Now · Δ. Para MongoDB/DocumentDB a métrica é a duração p95 (ms); para o Cosmos é a RU. Uma segunda linha mostra docs examinados / retornados. As colunas “Now” e “Δ” ficam destacadas quando houve regressão (por exemplo 2.6 → 197 = 75.8×).
Esta é a manchete: a mesma consulta agora é muito mais cara do que o seu próprio baseline aprendido.
HOW IT CHANGED — o diff do plano (Nível 2)
O plano antes/depois, por exemplo IXSCAN { userId:1, status:1 } ⇩ COLLSCAN. Um índice removido ou uma entrada ruim no plan-cache aparece aqui imediatamente.
WHY — causa raiz (Nível 3)
Achados em tópicos vindos dos investigadores: quais índices existem na coleção, se o plano mudou, se a chave do plan-cache mudou. Cada tópico é colorido de verde (ok) ou âmbar (suspeito).
WHAT CHANGED NEARBY (Nível 4)
Uma linha do tempo de eventos de DDL e deploy dentro de ±5 minutos da detecção — por exemplo 2m before · dropIndex · shop.orders · idx_user_status.
Esta é a resposta para “o que mudou logo antes de isto ficar lento”. Um índice removido dois minutos antes de uma virada de plano para COLLSCAN é uma causa raiz quase certa.
QUERY SHAPE e AI Root Cause (Nível 5)
O formato canônico (op, campos de filter, campos de sort), seguido de um painel AI Analysis com um seletor de modelo e um botão Run analysis.
Clique em Run analysis.
O botão brilha enquanto o modelo trabalha e, em seguida, surge uma narrativa concisa de causa raiz + remediação, escrita a partir da ficha de fatos deste alerta.
Abrir o modal de detalhes
Clique no botão ··· no canto superior direito do painel de detalhes.
Um modal abre com um cabeçalho fixo (severidade + título + fingerprint) e um corpo rolável: o comando realmente executado, um botão Explain plan e uma seção de IA.
Conceito
O Command é o comando real capturado da fonte de consultas lentas — não uma reconstrução — então o Explain executa o formato real da consulta.
Remediação sugerida
Na parte inferior: Clear plan cache (habilitado para alertas de mudança de plano no MongoDB), Acknowledge e Snooze 24h.
Clique em Acknowledge, depois em Snooze 24h, e observe o status do alerta mudar na lista.
Atenção
Clear plan cache grava no servidor ao vivo. Ele sempre pede confirmação primeiro — leia o diálogo antes de confirmar, especialmente em produção.
Escopo e a proteção contra mudanças não declaradas
Alternar o escopo
Na barra SCOPE, clique em um chip de banco de dados (ou em All databases).
A lista é filtrada para os bancos de dados selecionados. All databases é o padrão e é o que você quer durante uma janela de manutenção.
A detecção sempre roda abrangendo toda a instância. O escopo apenas filtra o que você vê — ele nunca impede o engine de observar todos os bancos de dados.
O banner de crítico fora do escopo
Se você restringir o escopo e uma regressão crítica disparar em um banco de dados fora do seu filtro, um banner de aviso aparece: “N critical regression(s) in databases outside your filter”.
Esta é a proteção contra o incidente clássico: uma mudança diz que toca o banco de dados X, mas um script oculto altera um banco de dados Y não declarado. O banner traz o Y à tona mesmo quando você não estava olhando para ele.
Captura ao vivo no MongoDB
Agora conecte uma fonte real. O MongoDB não precisa de configuração de credencial — ele lê o log de consultas lentas do servidor diretamente.
Conectar um replica set ou cluster dedicado do Atlas
Conecte o NoSqlStudio a um replica set MongoDB ou a um cluster dedicado do Atlas, depois abra o Query Regressions nessa conexão.
O cabeçalho mostra o status ao vivo como live (verde).
Atenção
Os tiers compartilhados do Atlas (M0/M2/M5) bloqueiam o comando administrativo getLog, então o status ao vivo aparecerá como unavailable. Use um cluster dedicado ou um replica set auto-hospedado.
Gerar um scan obviamente ruim
Em uma aba de shell, execute um scan lento de coleção em um campo que não tem índice — ordenar por um campo sem índice força um COLLSCAN sobre toda a coleção:
use <database>
db.<collection>.find({}).sort({ <unindexedField>: -1 }).limit(25).toArray()A consulta leva bem mais de 100 ms e varre toda a coleção.
Ver o card New slow query
Volte para a aba Query Regressions e aguarde alguns segundos (o log de lentidão é consultado a cada ~5 s).
Um card WARN intitulado New slow query — <namespace> (código Q7) aparece, com plano COLLSCAN e uma alta contagem de docs examinados.
Uma consulta nunca antes vista que já é um grande COLLSCAN é sinalizada na primeira aparição — sem necessidade de baseline. Esta é a proteção para mudanças que entram durante uma janela de manutenção.
Provar que o fingerprint é estável (dedup)
Execute a mesma consulta exata mais algumas vezes.
Nenhum card novo aparece. As repetições são agrupadas no mesmo alerta — mesmo fingerprint = mesma identidade.
Este é todo o objetivo do fingerprint estável: reexecutar uma consulta nunca enche de alertas duplicados. Uma consulta = uma identidade, como o sql_id.
Provar que um formato diferente é um novo alerta
Execute um COLLSCAN com um formato diferente — ordene por um campo sem índice diferente:
use <database>
db.<collection>.find({}).sort({ <anotherUnindexedField>: -1 }).limit(25).toArray()Um segundo card, distinto, aparece com um fingerprint diferente. Formato diferente = nova identidade = novo alerta.
Captura ao vivo no Cosmos DB (modo RU)
O Cosmos não tem log de consultas lentas para consultar, então a captura lê os logs de diagnóstico do Azure Log Analytics. A métrica é RU, não milissegundos.
Configurar o Log Analytics em Cloud Credentials
Em uma conexão Cosmos DB (Mongo API), abra o Cosmos Optimizer (Ctrl+Alt+Shift+O) → Configuration → Cloud Credentials e preencha a seção Azure: o Resource ID da conta Cosmos e o Log Analytics workspace ID. Clique em Save.
Uma confirmação verde aparece (credentials saved … MetricsBridge promoted).
Atenção
O Log Analytics é um tier pago (ingestão + retenção). É o único caminho que enxerga consultas de outros clientes — o caminho gratuito de header só enxerga o que o próprio NoSqlStudio executa, o que não é suficiente para o cenário de mudança não declarada.
Confirmar o status ao vivo e gerar uma consulta cara
Abra o Query Regressions na conexão Cosmos; confirme que o status aparece como live. Em seguida execute uma consulta cross-partition ou sem índice que consuma RU.
Depois que o Log Analytics ingerir a linha (minutos de atraso), um card aparece com a RU antes/depois como a métrica de manchete.
Conceito
O Explain não está disponível no modo RU do Cosmos — o modal informa isso e o direciona para a métrica de RU e para o painel de Index Policy em vez disso.
Captura ao vivo no DocumentDB
O DocumentDB não suporta getLog, então a captura lê o stream do profiler do DocDB a partir do CloudWatch Logs. Ele precisa do profiler habilitado e de credenciais AWS.
Habilitar o profiler do DocDB
Na AWS, crie um parameter group de cluster personalizado com profiler = enabled e um profiler_threshold_ms baixo (por exemplo 50), aplique-o (um reboot é necessário) e adicione profiler aos Log exports to CloudWatch do cluster.
Operações lentas começam a chegar no grupo de logs do CloudWatch /aws/docdb/<cluster>/profiler.
Definir as credenciais AWS em Cloud Credentials
Na conexão DocumentDB, abra o Cosmos Optimizer (Ctrl+Alt+Shift+O) → Configuration → Cloud Credentials e preencha a seção AWS DocumentDB: Region, DocDB cluster identifier e, opcionalmente, um AWS profile (deixe vazio para usar a cadeia de credenciais padrão da máquina). Role para baixo e clique em Save credentials.
A seção exibe um badge verde CONFIGURED, e o MetricsBridge aws-documentdb é registrado para esta conexão.
Conceito
Este painel é compartilhado entre AWS DocumentDB e Azure Cosmos e é por conexão — preencha a seção AWS na conexão DocumentDB, a seção Azure em uma conexão Cosmos. Cada conexão carrega sua própria region/cluster, então múltiplos clusters DocDB em regiões diferentes são tratados de forma independente.
Abrir a tela e gerar um scan lento
Abra o Query Regressions na conexão DocumentDB (confirme o status live), depois execute um COLLSCAN lento em uma aba de shell:
use <database>
db.<collection>.find({}).sort({ <unindexedField>: -1 }).limit(25).toArray()Em ~15 s um card New slow query aparece, com plano COLLSCAN e uma contagem de docs examinados derivada.
Atenção
O DocumentDB não emite docsExamined diretamente, então o valor é derivado do estágio de scan do execStats do profiler — exato para scans sem filtro, um limite inferior quando um filtro de estágio exclui linhas. Uma contagem eficiente somente por índice (IXONLYSCAN) intencionalmente não é sinalizada, mesmo que seja um pouco lenta — apenas COLLSCANs que examinam muitos docs são.
Persistência e comportamentos
O status sobrevive a uma reabertura
Faça acknowledge ou snooze em um alerta, depois feche e reabra a aba Query Regressions.
O status de acknowledged/snoozed e a sua seleção de escopo ainda estão lá.
A mesma tela, todos os engines
Abra a tela em uma conexão MongoDB, uma Cosmos e uma DocumentDB, uma de cada vez. O layout, os cards, os cinco níveis de RCA e o painel de IA são idênticos — apenas a métrica de manchete (ms vs RU) e a disponibilidade do Explain diferem.
Limpeza (quando você terminar)
Remova quaisquer coleções de teste descartáveis que você criou:
use <database>
db.<collection>.drop()Para o DocumentDB, se o profiler foi habilitado apenas para este teste, você pode desabilitá-lo no parameter group e excluir o grupo de logs do CloudWatch para parar os custos de ingestão. Para o Cosmos, reduza ou desabilite as diagnostic settings do Log Analytics se você não precisar de captura contínua.
Os dados de teste sumiram e quaisquer tiers pagos da nuvem que você habilitou para o teste estão desativados.
Resumo do que você validou
| Etapa | Recurso |
|---|---|
| 1 | Abrir o Query Regressions e carregar dados de demonstração sem nenhum banco de dados |
| 2 | Ler um alerta: métricas L1, diff de plano L2, achados L3, eventos próximos L4, IA L5, modal de detalhes, remediação |
| 3 | Filtro de escopo e o banner de crítico fora do escopo (proteção contra mudanças não declaradas) |
| 4 | Captura ao vivo no MongoDB: New slow query, dedup por fingerprint estável, novo formato = novo alerta |
| 5 | Captura ao vivo no Cosmos DB via Log Analytics, com RU como métrica |
| 6 | Captura ao vivo no DocumentDB via o stream do profiler do CloudWatch |
| 7 | Persistência de status/escopo e uma tela consistente nos três engines |