Setup de monitoreo Cosmos

Tiempo de setup: ~10 min. Costo: US$ 0/mes. Impacto: cero en producción. Cubre RU Budget, Throughput Optimizer, conteo de Throttling, Hot Partitions (aggregate), Query Cost (in-app).

Parte A — portal Azure / CLI

1. Cree un Service Principal

Portal: Azure Active Directory → App registrations → New registration → nombre nosqlstudio-cosmos-reader. Copie Application (client) ID, Directory (tenant) ID, y cree un Client Secret en Certificates & secrets.

Equivalente CLI:

az ad sp create-for-rbac \
  --name nosqlstudio-cosmos-reader \
  --role "Monitoring Reader" \
  --scopes /subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>

2. Asigne el role Monitoring Reader

Alcance mínimo: el resource group que contiene la cuenta Cosmos. Si quiere cubrir múltiples cuentas Cosmos en RGs diferentes, asigne a nivel de subscription.

az role assignment create \
  --assignee <APP_ID> \
  --role "Monitoring Reader" \
  --scope /subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>

3. Copie el Resource ID del Cosmos

Formato: /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.DocumentDB/databaseAccounts/<account>

az cosmosdb show -n <ACCOUNT_NAME> -g <RG_NAME> --query id -o tsv

Parte B — NoSqlStudio

1. Conéctese a su cuenta Cosmos en NoSqlStudio.
2. Abra Cosmos Optimizer (Ctrl+Alt+Shift+Y o menú Tools).
3. Vaya al tab Cloud Credentials.
4. En TIER B · FREE — Azure Monitor, complete: Resource ID, Tenant ID, Client ID, Client secret.
5. Deje Workspace ID (GUID) en la sección TIER A vacío — está optando por no usar el tier pagado.
6. Haga clic en Save credentials (encrypted).

Parte C — Verifique

Vuelva al tab RU Budget. El banner de source-mode debe mostrar un chip verde Azure Monitor + el texto aggregate only — no per-shape breakdown. Haga clic en Refresh — números pueblan en 1-2 minutos (Azure puede tardar unos minutos para que métricas frescas estén disponibles).

Tabla de decisión rápida

Troubleshooting — “Creé el Diagnostic Setting pero no llega ningún dato”

Un Diagnostic Setting recién creado a veces se niega a empezar a emitir eventos por 30+ minutos (o nunca), aunque el management plane lo reporte como “activo”. Es un quirk conocido de Azure Monitor cuando un setting anterior en el mismo recurso fue eliminado recientemente, o cuando solo una categoría de log está activa.

Cómo confirmar que está atascado en este estado

Corra el probe de abajo — funciona tanto dentro del blade Logs del workspace (solo la parte KQL) como desde su terminal vía az CLI. Reemplace <your-workspace-guid> por el GUID que copió de Workspace → Overview → Workspace ID. Si cnt se queda en 0 por más de 10 minutos mientras la cuenta está sirviendo tráfico activamente, está atascado.

az monitor log-analytics query \
  --workspace <your-workspace-guid> \
  --analytics-query "CDBMongoRequests | where TimeGenerated > ago(10m) | summarize cnt=count()" \
  -o table

El workaround que lo destraba

Elimine el Diagnostic Setting y recréelo con tres categorías de log activadas al mismo tiempo en vez de solo MongoRequests. Las categorías extra inicializan el pipeline de diagnóstico que el setting de categoría única no logró inicializar.

RID="/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.DocumentDB/databaseAccounts/<acct>"
WS="/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.OperationalInsights/workspaces/<ws-name>"

az monitor diagnostic-settings delete --name nosqlstudio-monitoring --resource "$RID"

az monitor diagnostic-settings create \
  --name nosqlstudio-monitoring \
  --resource "$RID" \
  --workspace "$WS" \
  --logs '[{"category":"MongoRequests","enabled":true},{"category":"DataPlaneRequests","enabled":true},{"category":"QueryRuntimeStatistics","enabled":true}]' \
  --metrics '[{"category":"Requests","enabled":true}]' \
  --export-to-resource-specific true

Después del recreate, vuelva a correr el probe KQL. Los eventos típicamente aparecen en 3–7 minutos. Una vez fluyendo, puede dejar las tres categorías activas (las dos extra cuestan un poco más de ingestion pero le dan el query plan + payloads crudos de request en CDBQueryRuntimeStatistics y CDBDataPlaneRequests), o desactivar las extra después de que el pipeline se caliente.

Cuando ni el workaround funciona

• Confirme que la API de la cuenta Cosmos es MongoDB (corra az cosmosdb show --ids "$RID" --query "kind" — debe imprimir MongoDB; MongoRequests solo se dispara para esa API).
• Confirme que la región del workspace coincide con la región de la cuenta Cosmos (los pipelines cross-region son más lentos y a veces pierden la primera hora).
• Revise az monitor activity-log list --resource-id "$RID" --offset 1h por cualquier operación de diagnostic-setting fallida.
• Último recurso: abra un ticket de soporte Azure — el pipeline de diagnóstico es totalmente gestionado por Microsoft y no podemos inspeccionarlo más desde afuera.