Cosmos monitoring setup

Setup time: ~10 min. Cost: US$ 0/month. Impact: zero on production. Covers RU Budget, Throughput Optimizer, Throttling count, Hot Partitions (aggregate), Query Cost (in-app).

Part A — Azure portal / CLI

1. Create a Service Principal

Portal: Azure Active Directory → App registrations → New registration → name nosqlstudio-cosmos-reader. Copy Application (client) ID, Directory (tenant) ID, and create a Client Secret under Certificates & secrets.

CLI equivalent:

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

2. Assign role Monitoring Reader

Minimum scope: the resource group holding the Cosmos account. If you want to cover multiple Cosmos accounts in different RGs, assign at subscription level.

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

3. Copy the Cosmos Resource ID

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

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

Part B — NoSqlStudio

1. Connect to your Cosmos account in NoSqlStudio.
2. Open Cosmos Optimizer (Ctrl+Alt+Shift+Y or menu Tools).
3. Go to the Cloud Credentials tab.
4. In TIER B · FREE — Azure Monitor, fill: Resource ID, Tenant ID, Client ID, Client secret.
5. Leave Workspace ID (GUID) in the TIER A section empty — you are opting out of paid tier.
6. Click Save credentials (encrypted).

Part C — Verify

Go back to the RU Budget tab. The source-mode banner should show a green Azure Monitor chip + the text aggregate only — no per-shape breakdown. Click Refresh — numbers populate within 1–2 minutes (Azure can take a few minutes for fresh metrics to be available).

Quick decision table

Troubleshooting — “I created the Diagnostic Setting but no data is flowing”

A brand-new Diagnostic Setting sometimes refuses to start emitting events for 30+ minutes (or never), even though the management plane reports it as “active”. This is a known quirk of Azure Monitor when a previous setting on the same resource was recently deleted, or when only a single log category is enabled.

How to confirm you are stuck in this state

Run the probe below — works either inside the workspace’s Logs blade (just the KQL part) or from your terminal via az CLI. Replace <your-workspace-guid> with the GUID you copied from Workspace → Overview → Workspace ID. If cnt stays at 0 for more than 10 minutes while the account is actively serving traffic, you are stuck.

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

The workaround that unsticks it

Delete the Diagnostic Setting and recreate it with three log categories enabled at the same time instead of just MongoRequests. The extra categories prime the diagnostic pipeline that the single-category setting failed to initialise.

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

After the recreate, re-run the KQL probe. Events typically appear within 3–7 minutes. Once flowing, you can leave all three categories enabled (the extra two cost a bit more ingestion but give you query plan + raw request payloads in CDBQueryRuntimeStatistics and CDBDataPlaneRequests), or disable the extras after the pipeline warms up.

When even the workaround doesn’t work

• Confirm the Cosmos account API is MongoDB (run az cosmosdb show --ids "$RID" --query "kind" — must print MongoDB; MongoRequests only fires for that API).
• Confirm the workspace region matches the Cosmos account region (cross-region pipelines are slower and sometimes drop the first hour).
• Check az monitor activity-log list --resource-id "$RID" --offset 1h for any failed diagnostic-setting operations.
• Last resort: open an Azure support ticket — the diagnostic pipeline is fully Microsoft-managed and we can’t inspect it further from the outside.