DBA handbook — Cosmos Optimizer step-by-step

§2 Per-pane walkthroughs

One section per pane. Each has: screenshot (when available), what it shows, step-by-step test, expected result on a busy production cluster, and troubleshooting notes for common issues.

Live view of RU/s consumed by your Cosmos account vs the budget you set. Holt-Winters forecast for 24h. Recommendation card comparing manual / autoscale / serverless / reserved.

Test steps

1. Set RU/s budget to your account's provisioned throughput (e.g. 5000 for a 5k RU/s database-level provisioning).
2. Click Refresh.
3. Observe Consumed (avg): should be non-zero on an active cluster. Compare against the value you see in the Azure Portal under Metrics → NormalizedRUConsumption.
4. Check Utilisation badge color: green = under 65%, yellow = 65–85%, red = over 85%. Red means urgent scale-up consideration.
5. Read the Recommendation card. Common outputs: RESERVED-3Y for steady workloads, AUTOSCALE for spiky ones, SERVERLESS for low-volume bursts.
6. Scroll to Per collection (preview). With Azure Monitor only, you see a single instance row aggregating everything — per namespace requires Log Analytics (PAID tier).

Captures the x-ms-request-charge response header from every query you run through NoSqlStudio. Zero Azure API calls — pure client-side instrumentation, always available.

Test steps

1. Open a Shell or Query tab against the Cosmos collection.
2. cosmosSite.dbaHandbook.queryCost.step2
3. Return to the Query Cost tab. Top query shapes should populate with the shape, total RU, average RU, p95, max, and count.
4. Run the same shape 5+ times to populate the count and p95 properly.
5. Use the filter input top-right to narrow to ns or shape substring.

Active probe that groups documents by your partition key and ranks the resulting partitions by doc count. Spots skew (one partition holding 40%+ of docs) before it becomes a 429 throttle storm.

Test steps

1. Fill Namespace: db.coll format, e.g. catalog.products.
2. Fill Partition key path: the field name you used as shardKey when creating the collection, e.g. tenantId.
3. Click Scan. This runs a $group aggregation on Cosmos — costs RU proportional to collection size. On a 200 GB collection expect 100-500 RU.
4. Read the spread badge in the top-right: green = even distribution, yellow = moderate skew, red = severe skew (top partition > 40% of docs).
5. Use the heatmap to spot specific hot partitions. Hover any cell for the exact key value + doc count.

Cosmos indexes every property by default — each write costs 1 RU per indexed property. Excluding never-queried paths can cut write RU consumption 30-70% on document-heavy collections.

Test steps

1. Fill Namespace, e.g. catalog.products.
2. Click Sample schema. NoSqlStudio reads 100 docs and builds a tree of all field paths.
3. Uncheck any field that NEVER appears in a WHERE / filter clause — think imageBase64, fullText, metadata.audit.*, etc.
4. Click Save draft. JSON preview updates with the proposed indexingPolicy.
5. cosmosSite.dbaHandbook.indexPolicy.step5

Classifies your workload (STEADY / SPIKY / CYCLIC / RAMP) from the last 15 min of metrics, then simulates monthly bill across the 5 Cosmos billing modes side-by-side. Reserved Capacity quote at the bottom.

Test steps

1. Click Refresh at top-right.
2. Read the Workload classification card. Common outputs: STEADY (low variance, CV < 0.4), SPIKY (CV > 0.8, recommend autoscale), CYCLIC (predictable daily peaks, recommend reserved with scheduled scale).
3. Compare the 5 Monthly bill cards. The cheapest with RECOMMENDED badge is the algorithm's pick.
4. Look for THROTTLED red banner on the manual card: indicates your current p95 exceeds the simulated tier and would cause 429s.
5. Scroll to Reserved capacity quote: concrete RU/s number to commit to + monthly savings vs manual.

Counts 429 (rate-limited) responses in the recent window via Azure Monitor, then correlates each burst with queries captured in the Query Cost ring buffer. Surfaces the query shape with highest cumulative RU during the 429 window — the likely culprit.

Test steps

1. Click Refresh. Read Total 429s, 429 events, and Peak / interval.
2. Set the Window ± minutes input (default 5). Lower it for tighter correlation, raise it if no queries fell in the window.
3. Scroll to Suspect queries. Each row = one 429 burst with the most expensive query shape that ran ± window minutes from the burst, with a confidence score (0-1).
4. If empty: open the Query Cost Inspector tab and run traffic. Without query captures, RCA has nothing to correlate.

10 ready-made Kusto queries against the Cosmos Diagnostic Logs in your Log Analytics workspace. Requires the PAID tier (Diagnostic Settings enabled, Log Analytics workspace ID configured).

Test steps

1. Verify the AZURE MONITOR banner shows upgrade available: Log Analytics. If you haven't plugged in the workspace ID, this pane shows NO SOURCE and the Run in app button is disabled.
2. Click any template card (e.g. Slow queries — last 1 hour) to load its KQL into the editor.
3. Click Edit to tweak the KQL inline (e.g. change ago(1h) to ago(24h)).
4. Click Run in app. Results table renders below within 2-5 seconds.
5. For long-form analysis, click Open in portal to deep-link the query into the Azure Portal KQL editor.

Watches the Query Cost ring buffer, identifies query shapes touching 2+ fields without a corresponding composite index, projects ~60% RU savings, emits the JSON snippet to paste into Cosmos's indexingPolicy.

Test steps

1. Set Min queries to consider = 5 (default). Threshold for considering a shape worth recommending.
2. cosmosSite.dbaHandbook.compositeIndex.step2
3. Return here. The Recommendations list fills with shape + projected RU saving + JSON snippet.
4. Click Copy JSON on any recommendation, paste into your Cosmos collection's indexingPolicy via collMod.

Disaster-recovery wizard. Picks a point in the Cosmos continuous-backup window (7 or 30 days depending on configured policy), generates the az cosmosdb restore CLI command, optionally executes it via the host shell.

Test steps

1. Fill Account (the Cosmos account name).
2. Set the Restore timestamp via slider or ISO-8601 input. Default: now minus 1 hour.
3. Fill Target account name (must be new — cannot overwrite source) and Region.
4. Click Validate plan. NoSqlStudio runs az cosmosdb show-backup-information to confirm a backup exists at that timestamp. Returns green check or red error.
5. Click Run via host shell (az-cli) when ready. Restore takes 30-90 minutes for typical collections.

Bidirectional migration assistant. Picks source + target (Atlas → Cosmos or Cosmos → Atlas), shows translation matrix (features that become unsupported), projects monthly bill on the destination, generates the mongosh script.

Test steps

1. Choose Source and Target: Atlas → Cosmos or vice-versa.
2. Read the Translation matrix: features that don't survive the move (e.g. Atlas Search → Cosmos: works via NoSqlStudio multi-DB engines locally, not natively; Cosmos PITR → Atlas: replaced by Atlas cluster snapshots).
3. Check Bill projection: estimated monthly cost on the target based on your current workload.
4. Click Generate script. Outputs a mongosh script with insertMany batches and progress reporting.
5. For real migration, dry-run on a test collection first (Cosmos charges write RU for inserts during migration!).

The control panel for what data sources feed every other pane. Three tiers: TIER C local (always on), TIER B Azure Monitor (FREE), TIER A Log Analytics (PAID).

Test steps

1. Confirm the TIER B card shows CONFIGURED badge if you saved credentials.
2. Sensitive fields (Resource ID, Tenant ID, Client ID, Client Secret, Workspace ID) appear masked as •••••••XXXX with an Edit button. Click Edit to reveal + change, then Mask to hide again.
3. After Save: source-mode banner on every metrics pane flips to AZURE MONITOR within < 100 ms (via internal event), or up to 15 s (via poll fallback).
4. Clear button (red) wipes credentials for this connection from disk + removes the bridge — everything reverts to NO SOURCE / Local samples.