Setup de monitoramento Cosmos

Tempo de setup: ~10 min. Custo: US$ 0/mês. Impacto: zero em produção. Cobre RU Budget, Throughput Optimizer, contagem de Throttling, Hot Partitions (aggregate), Query Cost (in-app).

Parte A — portal Azure / CLI

1. Crie um Service Principal

Portal: Azure Active Directory → App registrations → New registration → nome nosqlstudio-cosmos-reader. Copie Application (client) ID, Directory (tenant) ID, e crie um Client Secret em 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. Atribua a role Monitoring Reader

Escopo mínimo: o resource group que contém a conta Cosmos. Se você quer cobrir múltiplas contas Cosmos em RGs diferentes, atribua no nível de subscription.

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

3. Copie o Resource ID do 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. Conecte-se à sua conta Cosmos no NoSqlStudio.
2. Abra Cosmos Optimizer (Ctrl+Alt+Shift+Y ou menu Tools).
3. Vá para o tab Cloud Credentials.
4. Em TIER B · FREE — Azure Monitor, preencha: Resource ID, Tenant ID, Client ID, Client secret.
5. Deixe Workspace ID (GUID) na seção TIER A vazio — você está optando por não usar o tier pago.
6. Clique em Save credentials (encrypted).

Parte C — Verifique

Volte ao tab RU Budget. O banner de source-mode deve mostrar um chip verde Azure Monitor + o texto aggregate only — no per-shape breakdown. Clique em Refresh — números populam em 1-2 minutos (Azure pode demorar alguns minutos para métricas frescas ficarem disponíveis).

Tabela de decisão rápida

Troubleshooting — “Criei o Diagnostic Setting mas não chega dado”

Um Diagnostic Setting recém-criado às vezes se recusa a emitir eventos por 30+ minutos (ou nunca), mesmo que o management plane reporte como “ativo”. É um quirk conhecido do Azure Monitor quando um setting anterior no mesmo recurso foi deletado recentemente, ou quando só uma categoria de log está ativa.

Como confirmar que você caiu nesse caso

Rode o probe abaixo — funciona tanto na aba Logs do workspace (só a parte KQL) quanto no seu terminal via az CLI. Substitua <your-workspace-guid> pelo GUID que você copiou em Workspace → Overview → ID do Workspace. Se cnt ficar em 0 por mais de 10 minutos enquanto a conta recebe tráfego, você está travado.

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

O workaround que destrava

Delete o Diagnostic Setting e recrie com três categorias de log ativadas ao mesmo tempo em vez de só MongoRequests. As categorias extras inicializam o pipeline de diagnóstico que o setting de categoria única não conseguiu 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

Depois do recreate, re-rode o probe KQL. Eventos costumam aparecer em 3–7 minutos. Quando estiver fluindo, você pode deixar as três categorias ativas (as duas extras custam um pouco mais de ingestão mas dão query plan + payloads brutos em CDBQueryRuntimeStatistics e CDBDataPlaneRequests), ou desativar as extras depois que o pipeline esquentou.

Quando nem o workaround funciona

• Confirme que a API da conta Cosmos é MongoDB (az cosmosdb show --ids "$RID" --query "kind" precisa imprimir MongoDB; MongoRequests só dispara nessa API).
• Confirme que a região do workspace bate com a região da conta Cosmos (pipelines cross-region são mais lentos e às vezes perdem a primeira hora).
• Verifique az monitor activity-log list --resource-id "$RID" --offset 1h por qualquer operação diagnostic-setting falhada.
• Último recurso: abra um ticket de suporte Azure — o pipeline de diagnóstico é totalmente gerenciado pela Microsoft e não dá pra inspecionar mais do lado de fora.