Cosmos 监控设置

设置时间:~10 分钟。成本:US$ 0/月。影响:生产零影响。覆盖 RU Budget、Throughput Optimizer、Throttling 计数、Hot Partitions(aggregate)、Query Cost(in-app)。

Part A — Azure portal / CLI

1. 创建一个 Service Principal

Portal:Azure Active Directory → App registrations → New registration → 名称 nosqlstudio-cosmos-reader。复制 Application (client) ID、Directory (tenant) ID,并在 Certificates & secrets 下创建 Client Secret。

CLI 等效:

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

2. 分配 Monitoring Reader 角色

最小范围:持有 Cosmos 账户的资源组。如果想覆盖不同 RG 中的多个 Cosmos 账户,在订阅级别分配。

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

3. 复制 Cosmos Resource ID

格式:/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. 在 NoSqlStudio 中连接到您的 Cosmos 账户。
2. 打开 Cosmos Optimizer(Ctrl+Alt+Shift+Y 或 Tools 菜单)。
3. 前往 Cloud Credentials tab。
4. 在 TIER B · FREE — Azure Monitor 中填写:Resource ID、Tenant ID、Client ID、Client secret。
5. 将 TIER A 部分中的 Workspace ID (GUID) 留空 — 您选择退出付费层级。
6. 点击 Save credentials (encrypted)。

Part C — 验证

返回 RU Budget tab。source-mode banner 应显示绿色 Azure Monitor chip + 文本 aggregate only — no per-shape breakdown。点击 Refresh — 数字在 1-2 分钟内填充(Azure 可能需要几分钟才能让新鲜指标可用)。

快速决策表

Troubleshooting — “我创建了 Diagnostic Setting 但没有数据流入”

一个全新的 Diagnostic Setting 有时会拒绝开始发出事件长达 30+ 分钟(或永远不发),即使 management plane 报告它为“active”。这是 Azure Monitor 的一个已知怪癖,发生在同一 resource 上的前一个 setting 最近被删除时,或仅启用了单个 log 类别时。

如何确认您卡在此状态

运行下面的 probe — 在 workspace 的 Logs blade 内(仅 KQL 部分)或通过终端的 az CLI 都可以工作。将 <your-workspace-guid> 替换为您从 Workspace → Overview → Workspace ID 复制的 GUID。如果在账户正积极服务流量时 cnt 保持为 0 超过 10 分钟,您就卡住了。

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

解除卡顿的变通办法

删除 Diagnostic Setting,并以同时启用三个 log 类别而非仅 MongoRequests 重新创建它。额外的类别会激活单类别 setting 未能初始化的诊断 pipeline。

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

重新创建后,重新运行 KQL probe。事件通常在 3–7 分钟内出现。一旦开始流动,您可以保持三个类别全部启用(额外两个会多花一点 ingestion 成本,但能在 CDBQueryRuntimeStatistics 和 CDBDataPlaneRequests 中为您提供 query plan + 原始请求 payloads),或在 pipeline 预热后禁用额外的类别。

当连变通办法也不起作用时

• 确认 Cosmos 账户 API 是 MongoDB(运行 az cosmosdb show --ids "$RID" --query "kind" — 必须打印 MongoDB;MongoRequests 仅对该 API 触发)。
• 确认 workspace 区域与 Cosmos 账户区域匹配(cross-region pipelines 较慢,有时会丢掉第一个小时)。
• 检查 az monitor activity-log list --resource-id "$RID" --offset 1h 是否有任何失败的 diagnostic-setting 操作。
• 最后手段:开一张 Azure 支持工单 — diagnostic pipeline 完全由 Microsoft 托管,我们无法从外部进一步检查它。