Ir al contenido
NoSqlStudio
← workspace Cosmos

Manual del DBA — Cosmos Optimizer paso a paso

Walkthrough de cada pane del Cosmos Optimizer con un cluster de producción real. Para cada pantalla: qué muestra, cómo probarla, qué esperar, y cómo hacer troubleshooting cuando algo está fuera.

§0 Prerrequisitos·§1 Smoke test de 5 min·§2 Walkthroughs por pane·§3 Matriz de troubleshooting

§0 Prerrequisitos

Antes de abrir el Optimizer, termine la guía de setup. Sin credenciales, cada pane de métricas muestra NO SOURCE y cae a Local samples (solo lo que el propio NoSqlStudio querió).

  1. Siga el setup de monitoreo del Cosmos end-to-end: Service Principal, role assignment RBAC, Resource ID, Cloud Credentials. Setup de monitoreo Cosmos.
  2. Verifique con az login --service-principal y az monitor metrics list que el SP puede leer métricas de su cuenta Cosmos.
  3. Abra NoSqlStudio → conéctese a la cuenta Cosmos → abra Tools → Cosmos DB → Cosmos Optimizer (o Ctrl+Alt+Shift+O).

§1 Smoke test de 5 minutos — confirma que todo está conectado

Objetivo: en 5 minutos, confirmar que Azure Monitor está alimentando datos reales a NoSqlStudio. Si algún paso falla, salte a §3 Troubleshooting. §3 Troubleshooting.

  1. Conéctese a su cuenta Cosmos en NoSqlStudio. Confirme que ve el árbol de databases en la sidebar.
  2. Abra el Cosmos Optimizer. El banner de intro debe mostrar el botón CONFIGURE DATA SOURCES si las credenciales están faltando, o el contenido del pane directamente si están guardadas.
  3. Vaya a RU Budget. El banner de source-mode debe mostrar AZURE MONITOR — aggregate only en verde dentro de 2 segundos. Haga clic en Refresh. En 1-2 minutos debe ver Consumed (avg) diferente de cero.
  4. Haga clic en cada tab (Query Cost, Hot Partitions, Index Policy, Throughput Optimizer, Throttling RCA, Diagnostic Logs, Composite Index, PITR Restore, Migration Wizard). Ninguno debe mostrar error rojo.
  5. Abra el console DevTools (F12) — NO debe contener ChainedTokenCredential authentication failed o monitor client is null.
Esperado
Todos los diez panes cargan, RU Budget muestra RU/s reales en 2 minutos, sin auth errors en el console. Si sí, está production-ready.

§2 Walkthroughs por pane

Una sección por pane. Cada una tiene: screenshot (cuando disponible), qué muestra, prueba paso a paso, resultado esperado en un cluster de producción ocupado, y notas de troubleshooting para problemas comunes.

§2.1

RU Budget

FREE TIER
Pane RU Budget: consumo en vivo, utilización, proyección 24h, tabla per-collection
Pane RU Budget: consumo en vivo, utilización, proyección 24h, tabla per-collection

Vista en vivo de RU/s consumido por su cuenta Cosmos vs el budget que definió. Forecast Holt-Winters de 24h. Card de Recommendation comparando manual / autoscale / serverless / reserved.

Pasos de la prueba

  1. Defina RU/s budget al throughput provisionado de su cuenta (ej.: 5000 para un provisioning de 5k RU/s a nivel de database).
  2. Haga clic en Refresh.
  3. Observe Consumed (avg): debe ser diferente de cero en un cluster activo. Compare contra el valor que ve en el Azure Portal en Metrics → NormalizedRUConsumption.
  4. Verifique el color del badge Utilisation: verde = bajo 65%, amarillo = 65-85%, rojo = arriba 85%. Rojo significa consideración urgente de scale-up.
  5. Lea el card de Recommendation. Salidas comunes: RESERVED-3Y para workloads steady, AUTOSCALE para los spiky, SERVERLESS para bursts de bajo volumen.
  6. Desplácese a Per collection (preview). Con solo Azure Monitor, ve una única fila de instancia agregando todo — per namespace requiere Log Analytics (PAID tier).
Esperado
En un cluster ocupado: 495 RU/s consumido avg, 9.9% utilisation del budget de 5000, badge WITHIN BUDGET en verde. Recommendation: RESERVED-3Y con ahorro proyectado de $32.9K/mo.
Troubleshoot
0 RU/s con banner AZURE MONITOR verde = cluster genuinamente ocioso en la ventana de 15 min O mapping del adapter retorna métrica errónea. Confirme con az monitor metrics list --metric TotalRequestUnits — si CLI muestra non-zero, abra bug en NoSqlStudio. Banner NO SOURCE = credenciales no registradas. Reload (Ctrl+R) el app, reabra Cloud Credentials, haga clic en Save de nuevo.
§2.2

Query Cost Inspector

ALWAYS-ON
Pane Query Cost: ring buffer de RU costs per-query capturados del x-ms-request-charge
Pane Query Cost: ring buffer de RU costs per-query capturados del x-ms-request-charge

Captura el response header x-ms-request-charge de cada query que corre por NoSqlStudio. Cero llamadas a la Azure API — instrumentación puramente client-side, siempre disponible.

Pasos de la prueba

  1. Abra una tab Shell o Query contra la collection Cosmos.
  2. Corra una query pesada, ej.: db.Deals.find({ status: 'closed' }).limit(100) o db.Deals.aggregate([{$match:{}}, {$group:{_id:'$status', n:{$sum:1}}}]).
  3. Vuelva al tab Query Cost. Top query shapes debe poblar con el shape, RU total, RU promedio, p95, max, y count.
  4. Corra el mismo shape 5+ veces para poblar el count y p95 correctamente.
  5. Use el input de filter en el top-right para restringir a ns o substring de shape.
Esperado
Cada nueva query aparece inmediatamente (sin delay del Azure). El ring buffer queda capado en 500 entries (la más vieja se descarta) y sobrevive hasta el restart del app — no se persiste a disco.
Troubleshoot
Queries corren pero no aparecen: confirme que está corriendo la query por NoSqlStudio (no por mongosh en otra ventana o por el código del app). El hook de captura solo está en el DataService de NoSqlStudio.
§2.3

Hot Partition Detector

ALWAYS-ON
Pane Hot Partitions: heatmap de doc count por partition key + detección de skew
Pane Hot Partitions: heatmap de doc count por partition key + detección de skew

Probe activo que agrupa documentos por su partition key y ranquea las partitions resultantes por doc count. Detecta skew (una partition teniendo 40%+ de los docs) antes que se vuelva tormenta de throttle 429.

Pasos de la prueba

  1. Complete Namespace: formato db.coll, ej.: catalog.products.
  2. Complete Partition key path: el nombre del campo que usó como shardKey al crear la collection, ej.: tenantId.
  3. Haga clic en Scan. Esto corre una aggregation $group en Cosmos — cuesta RU proporcional al tamaño de la collection. En una collection de 200 GB espere 100-500 RU.
  4. Lea el badge spread en el top-right: verde = distribución uniforme, amarillo = moderate skew, rojo = severe skew (top partition > 40% de los docs).
  5. Use el heatmap para detectar partitions hot específicas. Hover en cualquier celda para el key value exacto + doc count.
Esperado
Para una collection tenant-sharded con cientos de tenants: spread verde (ningún tenant domina). Para una collection org-sharded donde un cliente grande es 60% de los datos: badge rojo, una celda rojo-oscuro en el heatmap.
Troubleshoot
No DataService bound = conexión perdida o plugin no cargado para esta conexión. Reconecte. Scan da error 16500: TooManyRequests = su collection no tiene RU suficiente para correr la aggregation ahora. Aumente RU temporalmente o haga scan en bajo tráfico.
§2.4

Visual Index Policy Editor

ALWAYS-ON
Editor Index Policy: árbol de schema con checkboxes include/exclude + preview JSON
Editor Index Policy: árbol de schema con checkboxes include/exclude + preview JSON

Cosmos indexa todas las propiedades por default — cada write cuesta 1 RU por propiedad indexada. Excluir paths nunca queryados puede cortar consumo de write RU en 30-70% en collections document-heavy.

Pasos de la prueba

  1. Complete Namespace, ej.: catalog.products.
  2. Haga clic en Sample schema. NoSqlStudio lee 100 docs y construye un árbol de todos los field paths.
  3. Desmarque cualquier field que NUNCA aparece en una cláusula WHERE / filter — piense en imageBase64, fullText, metadata.audit.*, etc.
  4. Haga clic en Save draft. JSON preview actualiza con la indexingPolicy propuesta.
  5. Copie el JSON, aplique vía shell: db.runCommand({collMod: 'products', indexingPolicy: <paste>}).
Esperado
En una collection de products de e-commerce típica (50+ campos, solo 5 queryados) puede dropar indexación en ~40 paths. Costo de write cae de ~50 RU/insert a ~10 RU/insert.
Troubleshoot
Sample schema retorna árbol vacío = collection está vacía (sin documentos para inferir schema). Inserte un doc representativo primero.
§2.5

Throughput Optimizer + Bill Simulator

FREE TIER
Throughput Optimizer: classifier de workload + comparación de bill en 5 modes + quote de Reserved Capacity
Throughput Optimizer: classifier de workload + comparación de bill en 5 modes + quote de Reserved Capacity

Clasifica su workload (STEADY / SPIKY / CYCLIC / RAMP) de los últimos 15 min de métricas, luego simula bill mensual en los 5 modes de facturación Cosmos lado-a-lado. Quote de Reserved Capacity en la base.

Pasos de la prueba

  1. Haga clic en Refresh en el top-right.
  2. Lea el card Workload classification. Salidas comunes: STEADY (low variance, CV < 0.4), SPIKY (CV > 0.8, recomienda autoscale), CYCLIC (peaks diarios predecibles, recomienda reserved con scheduled scale).
  3. Compare los 5 cards Monthly bill. El más barato con badge RECOMMENDED es la elección del algoritmo.
  4. Busque el banner rojo THROTTLED en el card manual: indica que su p95 actual excede el tier simulado y causaría 429s.
  5. Desplácese a Reserved capacity quote: número concreto de RU/s para comprometerse + ahorro mensual vs manual.
Esperado
STEADY workload (CV=0.27, p95=962 RU/s) → RESERVED-3Y recomendado a $38.14/mo vs manual $58.68/mo → $134/yr de ahorro. Para un SaaS de 1000 tenants es margen real.
Troubleshoot
Bug conocido (May 2026): card de autoscale a veces muestra total misformatado (ej.: $41.9K/mo) debido a un error de unidad en el simulator. Los otros 4 cards están correctos. Fix pendiente — track en el project board.
§2.6

Throttling RCA

FREE TIER
Throttling RCA: conteo de 429, peaks, sparkline + queries suspect correlacionadas
Throttling RCA: conteo de 429, peaks, sparkline + queries suspect correlacionadas

Cuenta respuestas 429 (rate-limited) en la ventana reciente vía Azure Monitor, luego correlaciona cada burst con queries capturadas en el ring buffer del Query Cost. Surface la query shape con mayor RU cumulativo durante la ventana de 429 — el probable culpable.

Pasos de la prueba

  1. Haga clic en Refresh. Lea Total 429s, 429 events, y Peak / interval.
  2. Defina el input Window ± minutos (default 5). Bájelo para correlation más apretada, súbalo si ninguna query cayó en la ventana.
  3. Desplácese a Suspect queries. Cada fila = un burst de 429 con la query shape más cara que corrió ± window minutos del burst, con un confidence score (0-1).
  4. Si vacío: abra el tab Query Cost Inspector y corra tráfico. Sin captures de query, el RCA no tiene nada para correlacionar.
Esperado
Un cluster de producción ocupado mostrando 372.9K 429s total en 15 eventos (peak 41.7K) está significativamente throttled. Después de correr queries representativas por ~5 minutos debe ver Suspect queries poblado con confidence > 0.5 para al menos una shape.
Troubleshoot
429 count alto pero Suspect queries vacío = tráfico está yendo por los servidores del app (no por NoSqlStudio). O corra la query known-bad en el Shell para capturarla, O haga upgrade a Log Analytics (PAID) para RCA per-shape completo vía KQL.
§2.7

Diagnostic Logs (KQL templates)

PAID TIER
Diagnostic Logs: 10 templates KQL listos contra la tabla MongoRequests
Diagnostic Logs: 10 templates KQL listos contra la tabla MongoRequests

10 queries Kusto listas contra los Cosmos Diagnostic Logs en su workspace Log Analytics. Requiere el tier PAID (Diagnostic Settings activado, workspace ID del Log Analytics configurado).

Pasos de la prueba

  1. Verifique si el banner AZURE MONITOR muestra upgrade available: Log Analytics. Si no enchufó el workspace ID, este pane muestra NO SOURCE y el botón Run in app queda disabled.
  2. Haga clic en cualquier card de template (ej.: Slow queries — last 1 hour) para cargar su KQL en el editor.
  3. Haga clic en Edit para ajustar el KQL inline (ej.: cambie ago(1h) a ago(24h)).
  4. Haga clic en Run in app. Tabla de resultados renderiza abajo en 2-5 segundos.
  5. Para análisis long-form, haga clic en Open in portal para deep-link de la query en el editor KQL del Azure Portal.
Esperado
Template Slow queries retorna 50 filas de los Mongo requests más lentos con columna durationMs. Top entries usualmente correlacionan con las mismas shapes en Throttling RCA.
Troubleshoot
Resultados vacíos a pesar de carga conocida = Diagnostic Settings en la cuenta Cosmos pueden no tener categoría de log MongoRequests activada, O < 5 min de delay desde activación. 403 Forbidden = SP necesita role Log Analytics Reader en el workspace.
§2.8

Composite Index Recommender

ALWAYS-ON
Composite Index: detecta shapes de query multi-field sin compound indexes + generador de snippet JSON
Composite Index: detecta shapes de query multi-field sin compound indexes + generador de snippet JSON

Observa el ring buffer del Query Cost, identifica query shapes que tocan 2+ campos sin un composite index correspondiente, proyecta ~60% de ahorro de RU, emite el JSON snippet para pegar en la indexingPolicy del Cosmos.

Pasos de la prueba

  1. Defina Min queries to consider = 5 (default). Threshold para considerar una shape valer la recomendación.
  2. Corra queries representativas por NoSqlStudio por ~5 minutos. Ejemplos de filter multi-campo: {tenantId: X, status: Y}, {userId: A, createdAt: {$gte: ...}}.
  3. Vuelva aquí. La lista Recommendations se llena con shape + RU saving proyectado + JSON snippet.
  4. Haga clic en Copy JSON en cualquier recomendación, pegue en la indexingPolicy de su collection Cosmos vía collMod.
Esperado
Para un app de e-commerce filtrando por {tenantId, status, createdAt} 5+ veces: 1 recomendación, ~60% reducción de RU por query, JSON snippet listo para pegar.
Troubleshoot
Ningún pattern multi-field capturado aún = ring buffer del Query Cost está vacío o solo shapes single-field fueron capturadas. Corra queries más diversas.
§2.9

Point-in-Time Restore

WIZARD
Wizard PITR Restore: formulario para account / timestamp / target / region + preview CLI
Wizard PITR Restore: formulario para account / timestamp / target / region + preview CLI

Wizard de disaster-recovery. Elige un punto en la ventana continuous-backup del Cosmos (7 o 30 días dependiendo de la política configurada), genera el comando CLI az cosmosdb restore, opcionalmente lo ejecuta vía host shell.

Pasos de la prueba

  1. Complete Account (el nombre de la cuenta Cosmos).
  2. Defina el Restore timestamp vía slider o input ISO-8601. Default: ahora menos 1 hora.
  3. Complete Target account name (debe ser nuevo — no puede sobrescribir el source) y Region.
  4. Haga clic en Validate plan. NoSqlStudio corre az cosmosdb show-backup-information para confirmar que un backup existe en ese timestamp. Retorna check verde o error rojo.
  5. Haga clic en Run via host shell (az-cli) cuando esté listo. Restore tarda 30-90 minutos para collections típicas.
Esperado
Para un DR drill real: validate plan tiene éxito en 5 segundos, muestra confirmación de tamaño de backup + timestamp. Restore real corre async — monitoree en el portal.
Troubleshoot
Account does not have continuous backup enabled = tiene modo de backup periódico. PITR requiere --backup-policy-type Continuous en la creación de la cuenta O una migración a modo continuous.
§2.10

Migration Wizard Atlas ↔ Cosmos

WIZARD
Migration Wizard: Atlas ↔ Cosmos bidireccional con translation matrix + generador de script
Migration Wizard: Atlas ↔ Cosmos bidireccional con translation matrix + generador de script

Asistente de migración bidireccional. Elige source + target (Atlas → Cosmos o Cosmos → Atlas), muestra translation matrix (features que se vuelven unsupported), proyecta bill mensual en el destino, genera el script mongosh.

Pasos de la prueba

  1. Elija Source y Target: Atlas → Cosmos o viceversa.
  2. Lea el Translation matrix: features que no sobreviven al cambio (ej.: Atlas Search → Cosmos: funciona vía engines multi-DB locales del NoSqlStudio, no nativamente; Cosmos PITR → Atlas: reemplazado por snapshots de cluster Atlas).
  3. Verifique Bill projection: costo mensual estimado en el target basado en su workload actual.
  4. Haga clic en Generate script. Salida es un script mongosh con batches insertMany y reporting de progress.
  5. Para migración real, haga dry-run en una collection de prueba primero (¡Cosmos cobra write RU por inserts durante la migración!).
Esperado
Translation matrix lista ~5-10 features con status (funciona/dropped/replaced). Bill projection dentro de ±30% del real en workloads simples.
Nota
Para migraciones multi-TB, use Azure Data Factory o la herramienta nativa de migración del Cosmos — este wizard tiene como objetivo migraciones más pequeñas / puntuales y escenarios DR.
§2.11

Cloud Credentials

ALWAYS-ON
Cloud Credentials: AWS DocDB + Azure Service Principal + workspace ID Log Analytics
Cloud Credentials: AWS DocDB + Azure Service Principal + workspace ID Log Analytics

El panel de control de qué fuentes de datos alimentan cada otro pane. Tres tiers: TIER C local (siempre on), TIER B Azure Monitor (FREE), TIER A Log Analytics (PAID).

Pasos de la prueba

  1. Confirme que el card TIER B muestra badge CONFIGURED si guardó las credenciales.
  2. Fields sensibles (Resource ID, Tenant ID, Client ID, Client Secret, Workspace ID) aparecen enmascarados como •••••••XXXX con un botón Edit. Haga clic en Edit para revelar + cambiar, luego Mask para esconder de nuevo.
  3. Después de Save: banner de source-mode en cada pane de métricas vira AZURE MONITOR en < 100 ms (vía evento interno), o hasta 15 s (vía poll fallback).
  4. Botón Clear (rojo) limpia credenciales para esta conexión del disco + remueve la bridge — todo revierte a NO SOURCE / Local samples.
Esperado
El panel Cloud Credentials muestra puntos verdes junto a cada credencial guardada, y el Operations Center puede comunicarse con Log Analytics + Azure Monitor sin errores.
Nota
Credenciales se almacenan encriptadas vía Electron safeStorage (OS keychain en macOS, DPAPI en Windows, libsecret en Linux). El archivo está en %APPDATA%/NoSqlStudio Dev Local/CloudCredentials/&lt;connectionId&gt;.bin.

§3 Matriz de troubleshooting

SíntomaCausa probableFix
Banner NO SOURCE en RU BudgetBridge no registrada para esta conexión (reload del renderer después del save de la credencial).Abra Cloud Credentials, haga clic en Save de nuevo. Lazy-register dispara automáticamente en el mount del workspace en operación normal; force vía re-save cuando necesario.
Banner verde AZURE MONITOR pero 0 RU/sAuth chain falló silenciosamente (fallback DefaultAzureCredential) O bug de mapping de métrica.Abra DevTools (F12). Busque los logs [azure-cosmos-adapter]. Si ve ChainedTokenCredential failed: Client Secret está vacío en Cloud Credentials, complete. Si ve metrics.list 401/403: SP no tiene el role Monitoring Reader.
Toast verde de Save en Cloud Credentials, pero RU Budget continúa mostrando NO SOURCE después del reloadPaquetes del adapter SDK (@azure/arm-monitor, @azure/monitor-query) faltando en node_modules.Verifique con node -e "require('@azure/arm-monitor')". Si faltan, corra npm install --no-save @azure/arm-monitor @azure/monitor-query en el repo Compass (declarados como optionalDependencies, así que npm a veces los salta).
Error Cannot find module 'semver/preload' en build-timeMismatch Node 24 × semver 6.x en hadron-build / @mongodb-js/devtools-github-repo.Cree shim: node_modules/semver/preload.js con module.exports = require('./semver.js'). O haga downgrade a Node 22.21.1 (la versión contra la cual los workflows del Compass testean).
Diagnostic Logs (KQL) muestra NO SOURCEWorkspace ID del Log Analytics no configurado (tier PAID no conectado).Decida: ¿necesita KQL per-shape? Si sí, active Diagnostic Settings en el Cosmos → stream a Log Analytics, pegue el GUID del workspace en Cloud Credentials. Si no, acepte que este pane está bloqueado — Throttling RCA y RU Budget aún funcionan vía Azure Monitor.
Query Cost / Composite Index vacíosNinguna query corrió por NoSqlStudio aún (o todas las queries fueron vía mongosh fuera del app).Corra queries reales contra su collection dentro de NoSqlStudio (Shell o tab Query). El hook de cost capture vive en el DataService de NoSqlStudio — solo ve lo que pasa por él.
Card de Autoscale muestra número sin sentido como $41.9K/moBug conocido en el cálculo de autoscale del bill simulator.Otros 4 cards (manual / serverless / reserved-1y / reserved-3y) están correctos. Ignore el número de autoscale — fix planeado para el próximo release.
Todos los panes tienen scroll cortando en medio del contenidoLeafyGreen &lt;Tab&gt; no propaga height — era un bug de layout antes del 25 mayo 2026.Actualice al último build de NoSqlStudio — fix está en scrollStyles con maxHeight: calc(100vh - 320px) explícito.
Scan de Hot Partitions retorna 16500: TooManyRequestsAggregation throttled porque el cluster no tiene RU headroom ahora.Aumente RU/s temporalmente, corra el scan, escale de vuelta. O programe el scan para ventana off-peak.
Throttling RCA "Suspect queries" vacío a pesar de 429 count altoTráfico viene de los app servers / otros clients, no del NoSqlStudio.O replay queries known-bad en el shell del NoSqlStudio para poblar el ring buffer, O haga upgrade a Log Analytics (PAID) para correlation per-shape completa vía KQL.
← Volver al workspace CosmosGuía de setup →