Monitoramento do Cosmos DB — Ativar Azure Log Analytics no NoSqlStudio

• Nome: nosqlstudio-cosmos-monitoring (qualquer nome serve, mas seja consistente entre ambientes).
• Tipos de conta suportados: deixe em Contas apenas neste diretório organizacional.
• URI de redirecionamento: deixe em branco — o NoSqlStudio usa o fluxo OAuth client-credentials, sem redirecionamento no navegador.

• Descrição: qualquer coisa memorável, ex: nosqlstudio-prod-2026.
• Expira em: 24 meses (melhor equilíbrio entre segurança e frequência de rotação). O Azure capa o máximo em 24 meses.

• Aba Papel: busque por `Leitor de Monitoramento` → selecione → clique Próximo.
• Aba Membros: Atribuir acesso a = Usuário, grupo ou principal de serviço → + Selecionar membros → busque nosqlstudio-cosmos-monitoring (o nome do Passo 2) → clique → Selecionar.
• Revisar + atribuir → Revisar + atribuir.

• Subscription + Resource group: os mesmos da conta Cosmos.
• Nome: nosqlstudio-monitoring.
• Região: a mesma região da sua conta Cosmos (minimiza latência de ingestão + zero custo de egress cross-region).

• Papel: busque `Leitor de Log Analytics` → selecione → Próximo.
• Membros: + Selecionar membros → busque `nosqlstudio-cosmos-monitoring` → selecione → Selecionar.
• Revisar + atribuir → Revisar + atribuir.

• Nome: nosqlstudio-monitoring.
• Em Logs, marque MongoRequests apenas. Deixe os outros sem marcar a não ser que tenha lido os limites de custo na Etapa 6 — PartitionKeyRUConsumption e QueryRuntimeStatistics produzem 5-10× mais volume de ingestão.
• Em Detalhes do destino: marque Enviar para o workspace do Log Analytics → selecione sua subscription → selecione nosqlstudio-monitoring (o workspace do Passo 5).
• No seletor Tabela de destino, escolha Específico do recurso, NÃO Diagnóstico do Azure.

• Windows: baixe o MSI em <https://aka.ms/installazurecliwindows>
• macOS: brew install azure-cli
• Debian / Ubuntu: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
• RHEL / Fedora: sudo dnf install azure-cli (depois de adicionar o repo da Microsoft)

az version

{
  "azure-cli": "2.66.0",
  ...
}

• Bash (Linux / macOS / WSL): curl -O https://nosqlstudio.com/scripts/setup-cosmos-monitoring.sh && chmod +x setup-cosmos-monitoring.sh
• PowerShell (Windows): Invoke-WebRequest -OutFile setup-cosmos-monitoring.ps1 -Uri https://nosqlstudio.com/scripts/setup-cosmos-monitoring.ps1

Overrides úteis quando o default não serve:

./setup-cosmos-monitoring.sh \
  --cosmos-resource-id "$RID" \
  --workspace-name      nosqlstudio-prod   \
  --workspace-region    westeurope         \
  --workspace-daily-cap-gb 5                \
  --include-partition-key-ru                \
  --verbose

• --workspace-daily-cap-gb 5 — sobe o teto de 1 GB/dia quando o tráfego é pesado. Custo escala linearmente.
• --include-partition-key-ru / --include-query-runtime-stats — adiciona categorias extras de log. Bem mais volume de ingestão; só ative se realmente precisa.
• --existing-sp-app-id <appId> — reaproveita um SP que o time de plataforma já tem; o script pula os Passos 2/3.
• --verbose — imprime cada resposta az.

• BYO Service Principal: create_service_principal = false + existing_service_principal_object_id = "<obj-id>". O módulo ainda cria o workspace + Diagnostic Setting e concede ambos os papéis ao SP existente. Você fornece o client secret por fora.
• Alerta de orçamento: create_budget_alert = true + budget_monthly_usd = 25 + budget_alert_email = "voce@exemplo.com" cria um budget mensal escopado por subscription que dispara email em 80% real e 100% previsto.
• Múltiplas categorias de log: diagnostic_log_categories = ["MongoRequests", "PartitionKeyRUConsumption"].

• Subscription ID — o GUID do Passo 8 (ou impresso pelo script / Terraform).
• Tenant ID — o Directory (tenant) ID do Passo 2.
• Client ID — o Application (client) ID do Passo 2.
• Client Secret — o Valor do segredo do Passo 3 (aquele que o Azure mostrou uma vez).
• Resource ID — o resource ID completo do Cosmos do Passo 1.
• Log Analytics Workspace ID — o GUID do Passo 5 (NÃO o resource ID).

1. 1O banner amarelo No telemetry captured yet desaparece.
2. 2Os seis gráficos pequenos (RU/s, Throttles, Latency p99, Errors, Cost, Top partition share) começam a se preencher da esquerda pra direita.
3. 3Clique a engrenagem ⚙ na toolbar — o modal diz Connected — recorded snapshots are being mirrored (assumindo que você também configurou o management database; é um toggle separado de única vez).

Com os defaults (só MongoRequests, teto 1 GB/dia, retenção 30 dias):

• Tráfego leve (<10 req/s): ~US$ 0,50 / mês, quase tudo de ingestão Log Analytics no rate PerGB2018.
• Moderado (10-100 req/s): ~US$ 2-3 / mês — SaaS pequeno típico.
• Pesado (> 100 req/s): bate o teto de 1 GB/dia; o workspace para de ingerir até meia-noite UTC. Gráficos ficam quietos. Comportamento intencional — protege contra custo fora de controle.

Se você ativou as categorias opcionais (Etapa 2 Passo 7) — PartitionKeyRUConsumption ou QueryRuntimeStatistics — espere 5-10× mais volume de ingestão. Planeje US$ 10-40 / mês em tráfego típico.

Duas causas comuns:

1. 1Teto diário batido. Abra o workspace → Uso e custos estimados → procure o banner vermelho Limite diário excedido no topo. Ou suba o teto ou espere meia-noite UTC.
2. 2Diagnostic Setting deletado ou desativado. Abra a conta Cosmos → Monitoramento → Configurações de diagnóstico. Se o nosqlstudio-monitoring sumiu, alguém removeu (colega, terraform destroy desviado, Azure Policy). Re-rode a Etapa 2 Passo 7 / seu script CLI / terraform apply pra recriar.

É a mensagem exata do NoSqlStudio quando ele consegue se autenticar no workspace mas acha zero linhas. Três causas, em ordem de probabilidade:

1. 1Diagnostic Setting está roteando pra OUTRO workspace que não o que você colou no NoSqlStudio. Abra Diagnostic Settings na conta Cosmos → verifique o workspace alvo.
2. 2Tabelas resource-specific não foram escolhidas (Etapa 2 Passo 7). Os dados ESTÃO chegando, mas na tabela legada AzureDiagnostics — o NoSqlStudio não consulta essa. Delete + recrie a Diagnostic Setting com Resource specific.
3. 3Setup recente, sem tráfego ainda. Logs precisam ~2-10 minutos de atraso de ingestão. Rode algumas queries na conta Cosmos e espere.

1. Confirme que você travou. Rode o probe — tanto na aba Logs do workspace (só a parte KQL) quanto no terminal. Substitua <your-workspace-guid> pelo GUID em Workspace → Visão Geral → ID do Workspace. Se cnt ficar em 0 por >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

2. 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.

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

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 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 no suporte Azure — o pipeline de diagnóstico é totalmente gerenciado pela Microsoft.

Boa prática é rotacionar o segredo do SP a cada 12-24 meses. Pra rotacionar:

• Portal: App Registration do Passo 2 → Certificados & segredos → + Novo segredo do cliente → copie o novo Valor → cole no Cloud Credentials → Save. Depois delete o segredo VELHO da mesma página.
• Script: re-rode setup-cosmos-monitoring.sh — detecta o SP existente e rotaciona o segredo automaticamente (o antigo continua válido; revogue manualmente se quiser).
• Terraform: o time_rotating tickeia a cada 2 anos, então terraform apply depois disso refresha o segredo. Pra forçar antes: terraform taint module.cosmos_monitoring.time_rotating.secret[0] && terraform apply.