DBA handbook — Cosmos Optimizer step-by-step
real production cluster के साथ Cosmos Optimizer के हर pane का Walkthrough। प्रत्येक screen के लिए: यह क्या दिखाता है, इसका परीक्षण कैसे करें, क्या अपेक्षित है, और जब कुछ off है तो troubleshooting कैसे करें।
§0 Prerequisites
Optimizer खोलने से पहले, setup guide पूरा करें। Credentials के बिना, हर metrics pane NO SOURCE दिखाता है और Local samples पर fall back करता है (केवल वही जो NoSqlStudio ने स्वयं queried)।
- End-to-end Cosmos monitoring setup का अनुसरण करें: Service Principal, RBAC role assignment, Resource ID, Cloud Credentials। Cosmos monitoring setup.
- az login --service-principal और az monitor metrics list के साथ verify करें कि SP आपके Cosmos account के लिए metrics पढ़ सकता है।
- NoSqlStudio खोलें → Cosmos account से कनेक्ट करें → Tools → Cosmos DB → Cosmos Optimizer खोलें (या Ctrl+Alt+Shift+O)।
§1 5-मिनट smoke test — पुष्टि करता है कि सब कुछ wired है
लक्ष्य: 5 मिनटों में, पुष्टि करें कि Azure Monitor NoSqlStudio को real data feed कर रहा है। यदि कोई step विफल होता है, §3 Troubleshooting पर जाएँ। §3 Troubleshooting.
- NoSqlStudio में अपने Cosmos account से कनेक्ट करें। पुष्टि करें कि आप sidebar में database tree देखते हैं।
- Cosmos Optimizer खोलें। यदि credentials गायब हैं तो intro banner CONFIGURE DATA SOURCES बटन दिखाना चाहिए, या यदि वे सहेजी गई हैं तो सीधे pane content।
- RU Budget पर जाएँ। Source-mode banner को 2 सेकंड के भीतर हरे में AZURE MONITOR — aggregate only पढ़ना चाहिए। Refresh पर क्लिक करें। 1-2 मिनट में आपको non-zero Consumed (avg) देखना चाहिए।
- हर tab (Query Cost, Hot Partitions, Index Policy, Throughput Optimizer, Throttling RCA, Diagnostic Logs, Composite Index, PITR Restore, Migration Wizard) पर क्लिक करें। किसी को भी red error नहीं फेंकना चाहिए।
- DevTools console (F12) खोलें — इसमें ChainedTokenCredential authentication failed या monitor client is null नहीं होना चाहिए।
§2 Per-pane walkthroughs
प्रति pane एक section। प्रत्येक में: screenshot (जब उपलब्ध), यह क्या दिखाता है, step-by-step test, busy production cluster पर अपेक्षित परिणाम, और सामान्य मुद्दों के लिए troubleshooting नोट्स।
RU Budget

आपके सेट budget बनाम आपके Cosmos account द्वारा consumed RU/s का live view। 24h के लिए Holt-Winters forecast। Manual / autoscale / serverless / reserved की तुलना करने वाला Recommendation card।
Test steps
- RU/s budget को अपने account के provisioned throughput पर सेट करें (जैसे database-level provisioning के लिए 5000 = 5k RU/s)।
- Refresh पर क्लिक करें।
- Consumed (avg) देखें: एक active cluster पर non-zero होना चाहिए। Azure Portal में Metrics → NormalizedRUConsumption में आप जो मान देखते हैं उससे तुलना करें।
- Utilisation badge का रंग जाँचें: हरा = 65% से नीचे, पीला = 65-85%, लाल = 85% से ऊपर। लाल का अर्थ है scale-up पर तत्काल विचार।
- Recommendation card पढ़ें। सामान्य outputs: steady workloads के लिए RESERVED-3Y, spiky के लिए AUTOSCALE, low-volume bursts के लिए SERVERLESS।
- Per collection (preview) तक scroll करें। केवल Azure Monitor के साथ, आप एक एकल instance row देखते हैं जो सब कुछ aggregate करती है — per namespace के लिए Log Analytics (PAID tier) चाहिए।
Query Cost Inspector

NoSqlStudio के माध्यम से आप जो भी query चलाते हैं उसका x-ms-request-charge response header capture करता है। शून्य Azure API calls — पूर्णतः client-side instrumentation, हमेशा उपलब्ध।
Test steps
- Cosmos collection के विरुद्ध Shell या Query tab खोलें।
- एक heavy query चलाएँ, जैसे db.Deals.find({ status: 'closed' }).limit(100) या db.Deals.aggregate([{$match:{}}, {$group:{_id:'$status', n:{$sum:1}}}])।
- Query Cost tab पर वापस जाएँ। Top query shapes shape, total RU, average RU, p95, max, और count के साथ populate होने चाहिए।
- Count और p95 को सही ढंग से populate करने के लिए वही shape 5+ बार चलाएँ।
- ns या shape substring तक संकीर्ण करने के लिए top-right में filter input का उपयोग करें।
Hot Partition Detector

Active probe जो आपके partition key द्वारा documents को समूहीकृत करती है और परिणामी partitions को doc count द्वारा रैंक करती है। 429 throttle storm बनने से पहले skew (एक partition में docs का 40%+ होना) पकड़ती है।
Test steps
- Namespace भरें: db.coll format, जैसे catalog.products।
- Partition key path भरें: collection बनाते समय आपने shardKey के रूप में जिस field name का उपयोग किया, जैसे tenantId।
- Scan पर क्लिक करें। यह Cosmos पर एक $group aggregation चलाता है — collection size के आनुपातिक RU खर्च करता है। 200 GB collection पर 100-500 RU की उम्मीद करें।
- Top-right में spread badge पढ़ें: हरा = समान वितरण, पीला = moderate skew, लाल = severe skew (top partition > 40% docs)।
- विशिष्ट hot partitions को spot करने के लिए heatmap का उपयोग करें। सटीक key value + doc count के लिए किसी भी cell पर hover करें।
Visual Index Policy Editor

Cosmos डिफ़ॉल्ट रूप से हर property को index करता है — प्रत्येक write प्रति indexed property 1 RU खर्च करता है। कभी-न-queried paths को exclude करना document-heavy collections पर write RU consumption को 30-70% कम कर सकता है।
Test steps
- Namespace भरें, जैसे catalog.products।
- Sample schema पर क्लिक करें। NoSqlStudio 100 docs पढ़ता है और सभी field paths का एक tree बनाता है।
- ऐसा कोई भी field uncheck करें जो WHERE / filter clause में कभी नहीं आता — imageBase64, fullText, metadata.audit.*, आदि सोचें।
- Save draft पर क्लिक करें। JSON preview proposed indexingPolicy के साथ update होता है।
- JSON कॉपी करें, shell के माध्यम से लागू करें: db.runCommand({collMod: 'products', indexingPolicy: <paste>})।
Throughput Optimizer + Bill Simulator

पिछले 15 मिनट के metrics से आपके workload को वर्गीकृत करता है (STEADY / SPIKY / CYCLIC / RAMP), फिर 5 Cosmos billing modes में monthly bill side-by-side simulate करता है। नीचे Reserved Capacity quote।
Test steps
- Top-right में Refresh पर क्लिक करें।
- Workload classification card पढ़ें। सामान्य outputs: STEADY (low variance, CV < 0.4), SPIKY (CV > 0.8, autoscale सुझाता है), CYCLIC (अनुमानित दैनिक peaks, scheduled scale के साथ reserved सुझाता है)।
- 5 Monthly bill cards की तुलना करें। RECOMMENDED badge के साथ सबसे सस्ता algorithm की पसंद है।
- Manual card पर लाल THROTTLED banner देखें: इंगित करता है कि आपका वर्तमान p95 simulated tier से अधिक है और 429s का कारण बनेगा।
- Reserved capacity quote तक scroll करें: commit करने के लिए ठोस RU/s number + manual के मुक़ाबले मासिक बचत।
Throttling RCA

Azure Monitor के माध्यम से recent window में 429 (rate-limited) responses की गणना करता है, फिर हर burst को Query Cost ring buffer में captured queries के साथ correlate करता है। 429 window के दौरान highest cumulative RU वाली query shape को surface करता है — probable culprit।
Test steps
- Refresh पर क्लिक करें। Total 429s, 429 events, और Peak / interval पढ़ें।
- Window ± minutes input सेट करें (default 5)। Tighter correlation के लिए कम करें, यदि कोई query window में नहीं गिरी तो बढ़ाएँ।
- Suspect queries तक scroll करें। प्रत्येक row = एक 429 burst burst से ± window minutes में चलने वाली सबसे महँगी query shape के साथ, confidence score (0-1) के साथ।
- यदि खाली: Query Cost Inspector tab खोलें और traffic चलाएँ। Query captures के बिना, RCA के पास correlate करने के लिए कुछ नहीं है।
Diagnostic Logs (KQL templates)

आपके Log Analytics workspace में Cosmos Diagnostic Logs के विरुद्ध 10 ready-made Kusto queries। PAID tier की आवश्यकता है (Diagnostic Settings सक्रिय, Log Analytics workspace ID configured)।
Test steps
- Verify करें कि AZURE MONITOR banner upgrade available: Log Analytics दिखाता है। यदि आपने workspace ID plug नहीं किया है, यह pane NO SOURCE दिखाता है और Run in app बटन disabled होता है।
- Editor में अपना KQL load करने के लिए किसी भी template card (जैसे Slow queries — last 1 hour) पर क्लिक करें।
- Edit पर क्लिक करके KQL को inline tweak करें (जैसे ago(1h) को ago(24h) में बदलें)।
- Run in app पर क्लिक करें। Results table 2-5 सेकंड में नीचे render होती है।
- Long-form analysis के लिए, Azure Portal KQL editor में query को deep-link करने के लिए Open in portal पर क्लिक करें।
Composite Index Recommender

Query Cost ring buffer देखता है, corresponding composite index के बिना 2+ fields को छूने वाले query shapes की पहचान करता है, ~60% RU savings का projection करता है, Cosmos indexingPolicy में paste करने के लिए JSON snippet emit करता है।
Test steps
- Min queries to consider = 5 (default) सेट करें। एक shape को recommend करने योग्य मानने के लिए threshold।
- ~5 मिनटों के लिए NoSqlStudio के माध्यम से representative queries चलाएँ। Multi-field filter उदाहरण: {tenantId: X, status: Y}, {userId: A, createdAt: {$gte: ...}}।
- यहाँ वापस आएँ। Recommendations सूची shape + projected RU saving + JSON snippet के साथ भरती है।
- किसी भी recommendation पर Copy JSON पर क्लिक करें, collMod के माध्यम से अपने Cosmos collection की indexingPolicy में paste करें।
Point-in-Time Restore

Disaster-recovery wizard। Cosmos continuous-backup window में एक point चुनता है (configured policy के आधार पर 7 या 30 दिन), az cosmosdb restore CLI command उत्पन्न करता है, वैकल्पिक रूप से host shell के माध्यम से इसे execute करता है।
Test steps
- Account भरें (Cosmos account का नाम)।
- Slider या ISO-8601 input के माध्यम से Restore timestamp सेट करें। Default: अभी माइनस 1 घंटा।
- Target account name (नया होना चाहिए — source को overwrite नहीं कर सकता) और Region भरें।
- Validate plan पर क्लिक करें। NoSqlStudio यह पुष्टि करने के लिए कि उस timestamp पर एक backup मौजूद है, az cosmosdb show-backup-information चलाता है। हरा check या लाल error लौटाता है।
- तैयार होने पर Run via host shell (az-cli) पर क्लिक करें। सामान्य collections के लिए Restore 30-90 मिनट लेता है।
Migration Wizard Atlas ↔ Cosmos

Bidirectional migration assistant। Source + target चुनता है (Atlas → Cosmos या Cosmos → Atlas), translation matrix (unsupported होने वाली features) दिखाता है, destination पर monthly bill का projection करता है, mongosh script उत्पन्न करता है।
Test steps
- Source और Target चुनें: Atlas → Cosmos या vice-versa।
- Translation matrix पढ़ें: features जो move में नहीं बचतीं (जैसे Atlas Search → Cosmos: NoSqlStudio multi-DB engines के माध्यम से locally काम करता है, natively नहीं; Cosmos PITR → Atlas: Atlas cluster snapshots से बदला गया)।
- Bill projection जाँचें: आपके current workload के आधार पर target पर estimated monthly cost।
- Generate script पर क्लिक करें। Output insertMany batches और progress reporting के साथ एक mongosh script है।
- Real migration के लिए, पहले एक test collection पर dry-run करें (Cosmos migration के दौरान inserts के लिए write RU charge करता है!)।
Cloud Credentials

हर अन्य pane को कौन से data sources feed करते हैं इसके लिए control panel। तीन tiers: TIER C local (हमेशा on), TIER B Azure Monitor (FREE), TIER A Log Analytics (PAID)।
Test steps
- पुष्टि करें कि TIER B card CONFIGURED badge दिखाता है यदि आपने credentials सहेजे हैं।
- संवेदनशील fields (Resource ID, Tenant ID, Client ID, Client Secret, Workspace ID) Edit बटन के साथ •••••••XXXX के रूप में masked दिखाई देते हैं। प्रकट करने + बदलने के लिए Edit पर क्लिक करें, फिर फिर से छुपाने के लिए Mask।
- Save के बाद: हर metrics pane पर source-mode banner < 100 ms में AZURE MONITOR में flip हो जाता है (internal event के माध्यम से), या 15 s तक (poll fallback के माध्यम से)।
- Clear बटन (लाल) इस connection के credentials को disk से मिटा देता है + bridge को हटा देता है — सब कुछ NO SOURCE / Local samples पर वापस आ जाता है।
§3 Troubleshooting matrix
| लक्षण | संभावित कारण | Fix |
|---|---|---|
| RU Budget पर NO SOURCE banner | इस connection के लिए Bridge registered नहीं है (credential save के बाद renderer reload)। | Cloud Credentials खोलें, Save पर फिर से क्लिक करें। सामान्य operation में workspace mount पर Lazy-register स्वचालित रूप से fire करता है; आवश्यकता होने पर re-save के माध्यम से force करें। |
| AZURE MONITOR हरा banner लेकिन 0 RU/s | Auth chain silently fail हुई (DefaultAzureCredential fallback) या metric mapping bug। | DevTools (F12) खोलें। [azure-cosmos-adapter] logs देखें। यदि आप ChainedTokenCredential failed देखते हैं: Cloud Credentials में Client Secret खाली है, इसे भरें। यदि आप metrics.list 401/403 देखते हैं: SP के पास Monitoring Reader role नहीं है। |
| Cloud Credentials में Save हरा toast, लेकिन reload के बाद भी RU Budget NO SOURCE दिखाता है | node_modules में Adapter SDK packages (@azure/arm-monitor, @azure/monitor-query) गायब। | node -e "require('@azure/arm-monitor')" के साथ verify करें। यदि गायब है, Compass repo में npm install --no-save @azure/arm-monitor @azure/monitor-query चलाएँ (optionalDependencies के रूप में declared हैं, इसलिए npm कभी-कभी skip करता है)। |
| Build time पर Cannot find module 'semver/preload' error | hadron-build / @mongodb-js/devtools-github-repo में Node 24 × semver 6.x mismatch। | Shim बनाएँ: node_modules/semver/preload.js जिसमें module.exports = require('./semver.js')। या Node 22.21.1 पर downgrade करें (वह version जिसके विरुद्ध Compass workflows test करते हैं)। |
| Diagnostic Logs (KQL) NO SOURCE दिखाता है | Log Analytics workspace ID configured नहीं (PAID tier unwired)। | निर्णय लें: क्या आपको per-shape KQL चाहिए? यदि हाँ, Cosmos पर Diagnostic Settings सक्रिय करें → Log Analytics पर stream, Cloud Credentials में workspace GUID paste करें। यदि नहीं, स्वीकार करें कि यह pane locked है — Throttling RCA और RU Budget अभी भी Azure Monitor के माध्यम से काम करते हैं। |
| Query Cost / Composite Index खाली | अभी तक NoSqlStudio से कोई query नहीं चली (या सभी queries app के बाहर mongosh के माध्यम से थीं)। | NoSqlStudio के अंदर अपनी collection के विरुद्ध actual queries चलाएँ (Shell या Query tab)। Cost capture hook NoSqlStudio के DataService पर रहता है — केवल वह देखता है जो उससे गुज़रता है। |
| Autoscale card $41.9K/mo जैसा बेतुका दिखाता है | Bill simulator के autoscale calculation में ज्ञात bug। | अन्य 4 cards (manual / serverless / reserved-1y / reserved-3y) सटीक हैं। Autoscale number को नज़रअंदाज़ करें — अगले release के लिए fix योजनाबद्ध। |
| सभी panes का scroll content के बीच में कट जाता है | LeafyGreen <Tab> height propagate नहीं करता — 25 मई 2026 से पहले layout bug था। | नवीनतम NoSqlStudio build पर अपडेट करें — fix scrollStyles में explicit maxHeight: calc(100vh - 320px) के साथ है। |
| Hot Partitions scan 16500: TooManyRequests लौटाता है | Aggregation throttled क्योंकि cluster में अभी RU headroom की कमी है। | RU/s को अस्थायी रूप से बढ़ाएँ, scan चलाएँ, वापस scale करें। या off-peak window के लिए scan schedule करें। |
| उच्च 429 count के बावजूद Throttling RCA "Suspect queries" खाली | Traffic app servers / अन्य clients से आता है, NoSqlStudio से नहीं। | या तो NoSqlStudio shell में known-bad queries replay करें ring buffer populate करने के लिए, या KQL के माध्यम से पूर्ण per-shape correlation के लिए Log Analytics (PAID) पर upgrade करें। |