Introducción
Una guía paso a paso para ayudarte a abrir, usar y validar la pantalla Query Regressions —el detector de regresiones de rendimiento y anomalías integrado en NoSqlStudio. Sigue desde el Paso 1 hasta el final, en orden. Cada paso te indica qué hacer y qué verás.
Cómo leer este manual
Cada paso tiene:
- Haz — la acción exacta (haz clic, escribe, ejecuta tal o cual comando).
- Verás — lo que debería ocurrir en pantalla. Este es tu “aprobado / fallido”.
- Por qué — contexto adicional, solo cuando ayuda (sáltalo si tienes prisa).
Qué es Query Regressions
Concepto
Un fingerprint estable, como el sql_id de Oracle
Cada forma de consulta recibe un fingerprint estable que nunca cambia entre ejecuciones —la misma idea que el sql_id de Oracle. NoSqlStudio aprende un baseline móvil para cada fingerprint y genera una alerta cuando la misma consulta empieza a costar más: más lenta en tiempo real, más documentos examinados, más RU o un plan peor (por ejemplo IXSCAN → COLLSCAN).
Concepto
Una pantalla, tres motores
La misma pantalla funciona en MongoDB, Azure Cosmos DB (API de Mongo) y AWS DocumentDB. La captura es a nivel de toda la instancia —ve las consultas lentas de todos los clientes y todas las bases de datos, no solo las que ejecutas desde NoSqlStudio. Eso es lo que detecta un cambio no declarado durante una ventana de mantenimiento.
Concepto
Cinco niveles de análisis de causa raíz
Cada alerta se explica por capas: L1 métricas antes/después · L2 el diff del plan · L3 investigadores (índices, estadísticas de la colección, cardinalidad) · L4 eventos de DDL/despliegue correlacionados en una ventana de ±5 min (“qué cambió justo antes de que esto se volviera lento”) · L5 una narrativa de IA.
Antes de empezar
Puedes explorar toda la interfaz con datos de demostración y sin ninguna base de datos (Etapas 1–3). La captura en vivo (Etapas 4–6) necesita una conexión, y la fuente de datos depende del motor:
- 1MongoDB — lee el log de consultas lentas del servidor mediante
getLog:'global'. Funciona en replica sets autoalojados y clústeres dedicados de Atlas. No está disponible en los niveles compartidos de Atlas (M0/M2/M5), que bloqueangetLog. - 2Cosmos DB — lee los logs de diagnóstico de Azure Log Analytics. Requiere Log Analytics configurado en Cloud Credentials (Cosmos Optimizer).
- 3DocumentDB — lee el flujo del profiler de DocDB desde Amazon CloudWatch Logs. Requiere el profiler habilitado en el grupo de parámetros del clúster, exportado a CloudWatch, y las credenciales de AWS configuradas en Cloud Credentials.
- 4Una segunda pestaña donde puedas ejecutar comandos de shell —el Scratchpad o el Mongo Shell— para generar consultas lentas.
Tiempo estimado del recorrido completo: ~25 minutos.
Abre la pantalla (sin necesidad de base de datos)
Abre la pantalla y carga la demostración integrada para aprender la disposición antes de conectar una fuente en vivo.
Abre Query Regressions
En la barra de herramientas, elige Monitoring ▼ → Query Regressions (atajo de teclado Ctrl+Alt+Shift+Q).
Se abre una nueva pestaña con el encabezado Query Regressions a la izquierda, una lista maestra y un panel de detalle a la derecha.
Carga los datos de demostración
Si la lista está vacía, haz clic en Load demo data en el estado vacío.
Aparecen dos alertas de ejemplo bajo un grupo SHOP: una Plan regression — shop.orders y un Selectivity collapse — shop.events. El encabezado muestra una insignia roja 2 CRITICAL.
La demostración se ejecuta enteramente en memoria —sin servidor, sin permisos. Es la forma más rápida de aprender qué significa cada sección de una tarjeta.
Selecciona una alerta
Haz clic en la tarjeta Plan regression — shop.orders de la lista.
El panel de detalle se rellena. El encabezado muestra una insignia CRIT, el título y, debajo, el fingerprint (un hash estable), el namespace y el número de ocurrencias.
Anatomía de una alerta
Lee cada sección del panel de detalle de arriba abajo —esta es la misma disposición para todos los motores.
WHAT CHANGED (Nivel 1)
Una tabla con Signal · Baseline · Now · Δ. Para MongoDB/DocumentDB la métrica es la duración p95 (ms); para Cosmos es RU. Una segunda fila muestra documentos examinados / devueltos. Las columnas “Now” y “Δ” se resaltan cuando hubo regresión (por ejemplo 2.6 → 197 = 75.8×).
Este es el titular: la misma consulta ahora es mucho más costosa que su propio baseline aprendido.
HOW IT CHANGED — el diff del plan (Nivel 2)
El plan antes/después, por ejemplo IXSCAN { userId:1, status:1 } ⇩ COLLSCAN. Un índice eliminado o una entrada defectuosa del plan-cache aparece aquí de inmediato.
WHY — causa raíz (Nivel 3)
Hallazgos en viñetas de los investigadores: qué índices existen en la colección, si el plan cambió, si la clave del plan-cache cambió. Cada viñeta se colorea de verde (ok) o ámbar (sospechoso).
WHAT CHANGED NEARBY (Nivel 4)
Una línea de tiempo de eventos de DDL y despliegue dentro de ±5 minutos de la detección —por ejemplo 2m before · dropIndex · shop.orders · idx_user_status.
Esta es la respuesta a “qué cambió justo antes de que esto se volviera lento”. Un índice eliminado dos minutos antes de que el plan cambiara a COLLSCAN es una causa raíz casi segura.
QUERY SHAPE y AI Root Cause (Nivel 5)
La forma canónica (campos op, filter, sort), seguida de un panel AI Analysis con un selector de modelo y un botón Run analysis.
Haz clic en Run analysis.
El botón brilla mientras el modelo trabaja, y luego aparece una narrativa concisa de causa raíz + remediación, escrita a partir de la ficha de datos de esta alerta.
Abre el modal de detalles
Haz clic en el botón ··· en la parte superior derecha del panel de detalle.
Se abre un modal con un encabezado fijo (severidad + título + fingerprint) y un cuerpo desplazable: el comando realmente ejecutado, un botón Explain plan y una sección de IA.
Concepto
El Command es el comando real capturado desde la fuente de consultas lentas —no una reconstrucción— de modo que el Explain ejecuta la forma de consulta real.
Remediación sugerida
En la parte inferior: Clear plan cache (habilitado para alertas de cambio de plan en MongoDB), Acknowledge y Snooze 24h.
Haz clic en Acknowledge, luego en Snooze 24h, y observa cómo cambia el estado de la alerta en la lista.
Atención
Clear plan cache escribe en el servidor en vivo. Siempre pide confirmación primero —lee el diálogo antes de confirmar, especialmente en producción.
Alcance y la protección contra cambios no declarados
Cambia el alcance
En la barra SCOPE, haz clic en un chip de base de datos (o en All databases).
La lista se filtra a las bases de datos seleccionadas. All databases es el valor predeterminado y es lo que quieres durante una ventana de mantenimiento.
La detección siempre se ejecuta a nivel de toda la instancia. El alcance solo filtra lo que ves —nunca impide que el motor vigile todas las bases de datos.
El banner crítico fuera de alcance
Si reduces el alcance y se dispara una regresión crítica en una base de datos fuera de tu filtro, aparece un banner de advertencia: “N critical regression(s) in databases outside your filter”.
Esta es la protección contra el incidente clásico: un cambio dice que toca la base de datos X, pero un script oculto altera una base de datos Y no declarada. El banner saca a relucir Y aunque no la estuvieras mirando.
Captura en vivo en MongoDB
Ahora conecta una fuente real. MongoDB no necesita configurar credenciales —lee directamente el log de consultas lentas del servidor.
Conecta un replica set o un clúster dedicado de Atlas
Conecta NoSqlStudio a un replica set de MongoDB o a un clúster dedicado de Atlas, luego abre Query Regressions en esa conexión.
El encabezado muestra el estado en vivo como live (verde).
Atención
Los niveles compartidos de Atlas (M0/M2/M5) bloquean el comando de administración getLog, por lo que el estado en vivo aparecerá como unavailable. Usa un clúster dedicado o un replica set autoalojado.
Genera un escaneo obviamente malo
En una pestaña de shell, ejecuta un escaneo lento de colección sobre un campo que no tenga índice —ordenar por un campo sin índice fuerza un COLLSCAN sobre toda la colección:
use <database>
db.<collection>.find({}).sort({ <unindexedField>: -1 }).limit(25).toArray()La consulta tarda bastante más de 100 ms y escanea toda la colección.
Observa la tarjeta New slow query
Vuelve a la pestaña de Query Regressions y espera unos segundos (el log lento se consulta cada ~5 s).
Aparece una tarjeta WARN titulada New slow query — <namespace> (código Q7), con plan COLLSCAN y un recuento alto de documentos examinados.
Una consulta nunca antes vista que ya es un COLLSCAN grande se marca a la primera —sin necesidad de baseline. Esta es la protección para cambios que entran durante una ventana de mantenimiento.
Demuestra que el fingerprint es estable (dedup)
Ejecuta la misma consulta exacta varias veces más.
No aparece ninguna tarjeta nueva. Las repeticiones se agrupan en la misma alerta —mismo fingerprint = misma identidad.
Este es el objetivo de todo el fingerprint estable: reejecutar una consulta nunca llena la pantalla de alertas duplicadas. Una consulta = una identidad, como sql_id.
Demuestra que una forma diferente es una alerta nueva
Ejecuta un COLLSCAN con una forma diferente —ordena por un campo sin índice distinto:
use <database>
db.<collection>.find({}).sort({ <anotherUnindexedField>: -1 }).limit(25).toArray()Aparece una segunda tarjeta distinta con un fingerprint diferente. Forma diferente = identidad nueva = alerta nueva.
Captura en vivo en Cosmos DB (modo RU)
Cosmos no tiene un log de consultas lentas que consultar, por lo que la captura lee los logs de diagnóstico de Azure Log Analytics. La métrica es RU, no milisegundos.
Configura Log Analytics en Cloud Credentials
En una conexión de Cosmos DB (API de Mongo), abre el Cosmos Optimizer (Ctrl+Alt+Shift+O) → Configuration → Cloud Credentials, y rellena la sección Azure: el Resource ID de la cuenta de Cosmos y el Log Analytics workspace ID. Haz clic en Save.
Aparece una confirmación verde (credentials saved … MetricsBridge promoted).
Atención
Log Analytics es un nivel de pago (ingesta + retención). Es la única vía que ve consultas de otros clientes —la vía gratuita por encabezado solo ve lo que ejecuta el propio NoSqlStudio, lo que no basta para el escenario de cambio no declarado.
Confirma el estado en vivo y genera una consulta costosa
Abre Query Regressions en la conexión de Cosmos; confirma que el estado aparece como live. Luego ejecuta una consulta entre particiones o sin índice que consuma RU.
Tras que Log Analytics ingiera la fila (minutos de retardo), aparece una tarjeta con el RU antes/después como métrica principal.
Concepto
Explain no está disponible en el modo RU de Cosmos —el modal lo indica y te dirige a la métrica de RU y al panel de Index Policy en su lugar.
Captura en vivo en DocumentDB
DocumentDB no admite getLog, por lo que la captura lee el flujo del profiler de DocDB desde CloudWatch Logs. Necesita el profiler habilitado y credenciales de AWS.
Habilita el profiler de DocDB
En AWS, crea un grupo de parámetros de clúster personalizado con profiler = enabled y un profiler_threshold_ms bajo (por ejemplo 50), aplícalo (se requiere un reinicio) y añade profiler a los Log exports to CloudWatch del clúster.
Las operaciones lentas empiezan a llegar al grupo de logs de CloudWatch /aws/docdb/<cluster>/profiler.
Configura las credenciales de AWS en Cloud Credentials
En la conexión de DocumentDB, abre el Cosmos Optimizer (Ctrl+Alt+Shift+O) → Configuration → Cloud Credentials, y rellena la sección AWS DocumentDB: Region, DocDB cluster identifier y, opcionalmente, un AWS profile (déjalo vacío para usar la cadena de credenciales predeterminada de la máquina). Desplázate hacia abajo y haz clic en Save credentials.
La sección muestra una insignia verde CONFIGURED, y el MetricsBridge aws-documentdb queda registrado para esta conexión.
Concepto
Este panel es compartido entre AWS DocumentDB y Azure Cosmos y es por conexión —rellena la sección de AWS en la conexión de DocumentDB y la sección de Azure en una conexión de Cosmos. Cada conexión lleva su propia región/clúster, de modo que varios clústeres de DocDB en regiones diferentes se manejan de forma independiente.
Abre la pantalla y genera un escaneo lento
Abre Query Regressions en la conexión de DocumentDB (confirma el estado live), luego ejecuta un COLLSCAN lento en una pestaña de shell:
use <database>
db.<collection>.find({}).sort({ <unindexedField>: -1 }).limit(25).toArray()En unos ~15 s aparece una tarjeta New slow query, con plan COLLSCAN y un recuento derivado de documentos examinados.
Atención
DocumentDB no emite docsExamined directamente, por lo que el valor se deriva de la etapa de escaneo execStats del profiler —exacto para escaneos sin filtro, una cota inferior cuando un filtro de etapa excluye filas. Un recuento eficiente solo de índice (IXONLYSCAN) intencionadamente no se marca, aunque sea un poco lento —solo se marcan los COLLSCAN que examinan muchos documentos.
Persistencia y comportamientos
El estado sobrevive a una reapertura
Marca una alerta como reconocida o pospuesta, luego cierra y vuelve a abrir la pestaña de Query Regressions.
El estado reconocido/pospuesto y tu selección de alcance siguen ahí.
La misma pantalla, en todos los motores
Abre la pantalla en una conexión de MongoDB, una de Cosmos y una de DocumentDB, una tras otra. La disposición, las tarjetas, los cinco niveles de RCA y el panel de IA son idénticos —solo difieren la métrica principal (ms vs RU) y la disponibilidad de Explain.
Limpieza (cuando hayas terminado)
Elimina las colecciones de prueba desechables que hayas creado:
use <database>
db.<collection>.drop()Para DocumentDB, si el profiler se habilitó solo para esta prueba, puedes deshabilitarlo en el grupo de parámetros y eliminar el grupo de logs de CloudWatch para detener los costes de ingesta. Para Cosmos, reduce o deshabilita la configuración de diagnóstico de Log Analytics si no necesitas captura continua.
Los datos de prueba han desaparecido y los niveles de nube de pago que habilitaste para la prueba quedan desactivados.
Resumen de lo que validaste
| Etapa | Funcionalidad |
|---|---|
| 1 | Abrir Query Regressions y cargar datos de demostración sin base de datos |
| 2 | Leer una alerta: métricas L1, diff del plan L2, hallazgos L3, eventos cercanos L4, IA L5, modal de detalles, remediación |
| 3 | Filtro de alcance y el banner crítico fuera de alcance (protección contra cambios no declarados) |
| 4 | Captura en vivo en MongoDB: New slow query, dedup por fingerprint estable, forma nueva = alerta nueva |
| 5 | Captura en vivo en Cosmos DB vía Log Analytics, con RU como métrica |
| 6 | Captura en vivo en DocumentDB vía el flujo del profiler de CloudWatch |
| 7 | Persistencia del estado/alcance y una pantalla coherente en los tres motores |