ट्रबलशूटिंग

AWR में कुछ आपकी अपेक्षा के अनुसार व्यवहार नहीं कर रहा। यह गाइड लक्षणों से उपायों तक काम करती है: पहले स्वास्थ्य जाँच, फिर डेटाबेस समस्याएँ, फिर आपकी स्रोत फ़ाइलों में बाधित बदलाव। हर सेक्शन चलाने के लिए सटीक कमांड और आउटपुट पढ़ने का तरीका देता है। रोज़मर्रा के कमांड के लिए दैनिक वर्कफ़्लो और CLI संदर्भ देखें।

पहला कदम: स्वास्थ्य जाँच चलाएँ

AWR में Doctor नामक अंतर्निहित डायग्नोस्टिक कमांड आता है, दो स्तरों पर:

awr --json doctor --database-only
awr --json doctor

--database-only स्वयं SQLite डेटाबेस की जाँच करता है: अखंडता, फ़ॉरेन की, स्कीमा संस्करण, माइग्रेशन पहचान, और AWR-स्वामित्व स्कीमा ऑब्जेक्ट।
पूर्ण doctor आपकी चुनी गई स्रोत फ़ाइलों और रनटाइम रिकॉर्ड व डिस्क पर फ़ाइलों के बीच बाइंडिंग का भी निरीक्षण करता है।

Doctor डेटाबेस को केवल-पढ़ने के लिए खोलता है। यह स्कीमा माइग्रेट नहीं करता, स्रोत रीइंडेक्स नहीं करता, लंबित म्यूटेशन लागू नहीं करता, क्लेम समाप्त नहीं करता, और न अनाथ फ़ाइलें हटाता है — इसलिए इसे चलाना हमेशा सुरक्षित है, यहाँ तक कि क्षतिग्रस्त प्रोजेक्ट पर भी।

Doctor के निष्कर्ष पढ़ना

Doctor समस्याओं को अनुमान लगाने के बजाय स्पष्ट निष्कर्षों के रूप में रिपोर्ट करता है:

schema_issues — बंडल किए गए माइग्रेशन के सापेक्ष जाँची गई, गायब या बदली हुई AWR-स्वामित्व तालिकाएँ, कॉलम, इंडेक्स या ट्रिगर। अतिरिक्त ऑब्जेक्ट साथ रह सकते हैं; Doctor परिभाषाएँ सुधारेगा नहीं और न उनका SQL प्रिंट करेगा।
foreign_key_check_error — कोई विकृत संदर्भ SQLite को उसकी फ़ॉरेन-की जाँच भी चलाने से रोक देता है। यदि आपको यह फ़ील्ड दिखे, तो डेटाबेस अस्वस्थ है, और रिपोर्ट की गई शून्य उल्लंघनों का अर्थ है "हम उन्हें गिन नहीं पाए", न कि "सब ठीक है"।
सक्रिय सत्र — केवल सूचनात्मक; पुराना रिकॉर्ड यह साबित नहीं करता कि प्रोसेस मर चुकी है।
गायब निर्भरताएँ, लटकती एज, अनुपलब्ध स्रोत, बाधित सेव, और क्षतिग्रस्त या अपंजीकृत आर्टिफ़ैक्ट — हर एक निष्कर्ष के रूप में रिपोर्ट होता है। अपठनीय पेज या विदेशी (गैर-AWR) डेटाबेस स्पष्ट त्रुटियाँ देते हैं, न कि भ्रामक स्थिति।

लक्षण: "AWR ने मेरी स्रोत फ़ाइल अस्वीकार कर दी"

जब किसी YAML स्रोत फ़ाइल में सिंटैक्स त्रुटि या गलत प्रकार का फ़ील्ड होता है, तो AWR त्रुटि कोड InvalidInput और संरचित विवरण के साथ विफल होता है:

{
  "location": {
    "locator": "file:///project/work.yaml",
    "pointer": "/work_items/0/title",
    "line": 3,
    "column": 10
  },
  "rule": "ledger.string",
  "repair": "Use a quoted string or a YAML block scalar (|) for multiline text."
}

इसे कैसे पढ़ें: pointer आपकी स्रोत फ़ाइल की अपनी शब्दावली (कॉन्फ़िगर किए गए चीनी फ़ील्ड नामों सहित) का उपयोग करके दोषपूर्ण फ़ील्ड का नाम बताता है; line और column एक-आधारित हैं। शुद्ध सिंटैक्स त्रुटियों में केवल पार्सर निर्देशांक हो सकते हैं, और कुछ लुकअप (जैसे YAML एलियास) पॉइंटर को null निर्देशांक के साथ रखते हैं — इससे अन्यथा मान्य फ़ाइल अस्वीकृत नहीं होती। rule विफल अपेक्षा का नाम बताता है; repair अपेक्षित संरचना बताता है। यह कभी फ़ाइल संपादित नहीं करता और न अस्वीकृत मान को वापस इको करता है।

एक सामान्य मामला: आपने title: [Draft, Review] लिखा, जिसे YAML सूची के रूप में पार्स करता है, लेकिन फ़ील्ड को स्ट्रिंग चाहिए। यदि अल्पविराम शाब्दिक था:

title: "Draft, Review"

बहु-पंक्ति विवरण के लिए YAML ब्लॉक स्केलर (|) इस्तेमाल करें; मान्य चीनी टेक्स्ट और स्पेस वाले पथ पूर्ण समर्थित हैं।

लक्षण: "मेरे बदलाव क्वेरी में नहीं दिखते"

आपने स्रोत फ़ाइल संपादित की लेकिन AWR अभी भी पुराने तथ्य दिखाता है। रीइंडेक्स चलाएँ:

awr source reindex

फिर रिपोर्ट के दोनों भाग जाँचें: ऑपरेशन सफलता और प्रोजेक्शन पूर्णता। स्कैन सफल हो सकता है जबकि प्रोजेक्शन अधूरा रहता है, क्योंकि स्कैनिंग स्रोतों को देखती है लेकिन उनके बदले हुए तथ्य आयात नहीं करती। यही रिपोर्ट --json के साथ JSON के रूप में और MCP awr_source_reindex से मिलती है। समकक्ष प्रारंभिक स्नैपशॉट से आउटपुट की तुलना करें; रीइंडेक्सिंग स्वयं स्रोत स्थिति अपडेट करती है।

यदि किसी कार्य-आइटम का साक्ष्य गड़बड़ लगे, तो work show (या MCP awr_work_get) फ़्लैट evidence सूची के साथ evidence_groups रिपोर्ट करता है। हर समूह का एक सटीक लोकेटर होता है; एक ही पथ पर स्रोत संदर्भ और सत्यापित रिपोर्ट अलग रहते हैं, और समूहीकरण कभी रिकॉर्ड के बीच सत्यापन स्थानांतरित नहीं करता।

लक्षण: "डेटाबेस भ्रष्ट है या खो गया है"

आपकी स्रोत फ़ाइलें प्रोजेक्ट तथ्यों के लिए आधिकारिक हैं, लेकिन SQLite डेटाबेस (.awr/state.db) ऐसी स्थिति भी रखता है जो उन फ़ाइलों में नहीं होती: सत्र, क्लेम, चेकपॉइंट, रनटाइम इवेंट, आर्टिफ़ैक्ट पंजीकरण, और म्यूटेशन प्रयास। रीइंडेक्सिंग स्रोतों से प्रोजेक्शन ताज़ा करती है, लेकिन वह रनटाइम इतिहास पुनः नहीं बना सकती — और उन्हीं स्रोतों से नया डेटाबेस इनिशियलाइज़ करना भी नहीं।

सही तरीके से बैकअप लेना

पुनर्प्राप्ति योग्य स्नैपशॉट के लिए, ये सभी एक साथ रखें, और उन्हें इकट्ठा करते समय प्रोजेक्ट लेखकों को रोकें (SQLite का backup API सुसंगत डेटाबेस इमेज देता है, लेकिन आसपास की फ़ाइलों का स्नैपशॉट नहीं लेता):

SQLite के backup API या समकक्ष टूलिंग से बनाया गया .awr/state.db का सुसंगत बैकअप — लेखक सक्रिय होने पर फ़ाइल कॉपी करने से write-ahead लॉग में मौजूद कमिट किए गए रिकॉर्ड छूट सकते हैं।
मेल खाती स्रोत फ़ाइलें, Git रिवीज़न, .awr/project.toml, अधिकृत-रूट कॉन्फ़िगरेशन, और कोई स्पष्ट रूप से अधिकृत बाहरी स्रोत।
प्रबंधित आर्टिफ़ैक्ट फ़ाइलें, प्रबंधित डायरेक्टरी के बाहर पंजीकृत लोकल आर्टिफ़ैक्ट, और लंबित ऑपरेशन द्वारा संदर्भित .awr/mutations रिकवरी जर्नल व स्नैपशॉट।

पुनर्स्थापना

प्रोजेक्ट रोकें।
दर्ज कैनोनिकल रूट पर पुनर्स्थापित करें; विस्थापित स्थिति को हटाने के बजाय सहेजकर रखें।
awr --json doctor --database-only चलाएँ, फिर पूर्ण awr --json doctor।

पुनर्स्थापना किसी आर्टिफ़ैक्ट पंजीकरण को तब भी ठीक कर सकती है जब उसकी फ़ाइल अभी गायब हो — फ़ाइल पुनर्स्थापित करें या निष्कर्ष को अनसुलझा छोड़ें। awr source reindex न तो रनटाइम पुनर्स्थापना है और न डेटाबेस स्थानांतरण टूल।

Doctor नामित मरम्मत कर सकता है, लेकिन केवल वर्तमान प्रोजेक्ट रिवीज़न, चुने गए ऑब्जेक्ट और कारण के साथ; मरम्मतें स्रोत और असंबंधित रनटाइम स्थिति को संरक्षित रखती हैं। यदि डेटाबेस अखंडता टूटी है, तो सुझाई गई रनटाइम मरम्मतें अक्षम होती हैं — कोई स्वचालित पुनर्निर्माण नहीं।

लक्षण: "म्यूटेशन लिखते समय बीच में रुक गया"

AWR स्थायित्व सुरक्षा के साथ आपकी स्रोत फ़ाइलों पर स्वीकृत प्रस्ताव लागू करता है: प्रयास दर्ज होने से पहले अपरिवर्तनीय before/after स्नैपशॉट सहेजे जाते हैं, और सफलता के लिए इच्छित स्रोत बाइट्स, पुनर्निर्मित प्रोजेक्शन, और अंतिम एप्लिकेशन इवेंट आवश्यक हैं। यदि प्रोसेस लिखते समय बीच में मर जाए, तो प्रयास खुला और पुनर्प्राप्ति योग्य रहता है।

यदि आपको write_outcome: pending_recovery के साथ MutationIncomplete मिले, तो पहले निरीक्षण करें:

awr --json doctor
awr --json proposal show PROPOSAL_ID

आउटपुट से वर्तमान project_revision पढ़ें, फिर प्रस्ताव फिर से शुरू करें:

awr --json proposal recover PROPOSAL_ID \
  --actor reviewer \
  --reason "Resume the interrupted report review" \
  --expected-revision CURRENT_REVISION

रिकवरी क्या करती है, यह इस बात पर निर्भर करता है कि प्रयास कितना दूर तक पहुँचा था:

रुकावट के बाद की स्थिति	रिकवरी क्या करती है
स्नैपशॉट मौजूद हैं, कोई एप्लिकेशन जर्नल नहीं	स्रोत अपरिवर्तित है; नया `proposal apply` शुरू हो सकता है।
जर्नल मौजूद है, स्रोत अभी भी "before" से मेल खाता है	स्वामित्व, कॉन्फ़िगरेशन, स्रोत और रिवीज़न पुनः सत्यापित करती है, फिर दर्ज "after" बाइट्स इंस्टॉल करती है।
स्रोत पहले ही "after" से मेल खाता है, प्रोजेक्शन अधूरा	फ़ाइल को दोबारा लिखे बिना प्रोजेक्शन पुनर्निर्मित करती है।
प्रोजेक्शन कमिट हुआ, अंतिम इवेंट अनुपस्थित	प्रोजेक्शन सत्यापित करती है और अंतिम इवेंट कमिट करती है — दूसरा फ़ाइल लेखन नहीं।
अंतिम इवेंट कमिट हुआ, रिस्पॉन्स खो गया	स्थायी रसीद लौटाती है; रिकवरी दोहराने पर `InvalidTransition` के साथ विफलता, कोई डुप्लिकेट इवेंट नहीं।
स्रोत या स्नैपशॉट दर्ज योजना से असहमत	स्रोत संरक्षित रखती है, संघर्ष रिपोर्ट करती है, पूर्णता रोकती है।

सफल पुनः प्रयास recovered रिपोर्ट करता है, मूल प्रयास का नाम बताता है, और अपना resolved_event_id अंतिम इवेंट से बाँधता है।

दो चीज़ें न करें:

परिणाम जबरन निकालने के लिए स्नैपशॉट संपादित न करें। यदि वर्तमान स्रोत किसी भी स्नैपशॉट से मेल नहीं खाता, तो स्रोत संघर्ष सुलझाएँ और नया प्रस्ताव तैयार करें।
यह न मानें कि पुनः प्रयास ने फ़ाइल लिखी। source_write_performed केवल वर्तमान इनवोकेशन का वर्णन करता है — यही कारण है कि रिकवरी पहले पुनः सत्यापित करती है।

समवर्तीता: AWR लेखक प्रति-स्रोत OS लॉक और ट्रांज़ैक्शनल expected_revision जाँचों के माध्यम से समन्वय करते हैं। अलग-अलग स्रोत स्वतंत्र रूप से आगे बढ़ते हैं, लेकिन बीच का प्रोजेक्ट रिवीज़न स्पष्ट रिकवरी पुनः प्रयास माँग सकता है। बाहरी एडिटर लॉक में शामिल नहीं होते; फ़िंगरप्रिंट जाँचें उनके बदलाव पकड़ती हैं।

कब रुकें और मदद माँगें

तदर्थ जुगाड़ करने के बजाय रुकें और एस्केलेट करें जब:

Doctor टूटी डेटाबेस अखंडता रिपोर्ट करता है (foreign_key_check_error, अपठनीय पेज) — रनटाइम मरम्मतें अक्षम हैं, कोई स्वचालित पुनर्निर्माण नहीं।
म्यूटेशन रिकवरी स्रोत/स्नैपशॉट संघर्ष रिपोर्ट करती है — समर्थित मार्ग नया प्रस्ताव है, न कि स्नैपशॉट या जर्नल को हाथ से संपादित करना।
आपके परिदृश्य में मशीन की बिजली कटौती, वितरित लेखक, या अन्य ऑपरेटिंग सिस्टम शामिल हैं — रिकवरी गारंटी लोकल प्रोसेस रुकावट तक सीमित हैं; उससे आगे की बात स्थापित नहीं है।

मदद माँगने या इश्यू दर्ज करने से पहले, स्थिति ताज़ा होते हुए कैप्चर करें:

awr --json doctor --database-only
awr --json doctor
awr --json proposal show PROPOSAL_ID   # if a mutation is involved

विस्थापित डेटाबेस, .awr/mutations जर्नल और संबंधित स्रोत फ़ाइलों को अछूता रखें — वे रिपोर्ट को कार्रवाई योग्य बनाते हैं, और यदि सुधार गलत हो जाए तो वे आपका फ़ॉलबैक हैं।