تشخيص واستكشاف المشكلات وإصلاحها عند استخدام Azure Cosmos DB .NET SDK

ينطبق على: NoSQL

• Java SDK v4
• Async Java SDK v2
• NET.
• Python SDK

تتناول هذه المقالة المشكلات الشائعة والحلول وخطوات التشخيص والأدوات عند استخدام .NET SDK مع Azure Cosmos DB لحسابات NoSQL. يوفر .NET SDK تمثيلا منطقيا من جانب العميل للوصول إلى Azure Cosmos DB ل NoSQL. توضح هذه المقالة الأدوات والأساليب التي تساعدك في حالة مواجهة أي مشكلات.

قائمة مراجعة لاستكشاف المشكلات وإصلاحها

ضع في اعتبارك القائمة المرجعية التالية قبل نقل تطبيقك إلى الإنتاج. سيؤدي استخدام قائمة التحقق إلى منع العديد من المشكلات الشائعة التي قد تراها. يمكنك أيضاً التشخيص بسرعة عند حدوث مشكلة:

• استخدم أحدث SDK. يجب عدم استخدام معاينة SDKs للإنتاج. سيمنع هذا الوصول إلى المشكلات المعروفة التي تم إصلاحها بالفعل.
• راجع نصائح الأداء، واتبع الممارسات المقترحة. سيساعد هذا في منع القياس ووقت الاستجابة ومشكلات الأداء الأخرى.
• قم بتمكين تسجيل SDK لمساعدتك في استكشاف المشكلة وإصلاحها. قد يؤثر تمكين التسجيل على الأداء، لذا من الأفضل تمكينه فقط عند استكشاف المشكلات وإصلاحها. يمكنك تمكين السجلات التالية:
  • مقاييس السجل باستخدام مدخل Microsoft Azure. تعرض مقاييس المدخل القياس عن بعد Azure Cosmos DB، وهو أمر مفيد لتحديد ما إذا كانت المشكلة تتوافق مع Azure Cosmos DB أو ما إذا كانت من جانب العميل.
  • سجل سلسلة التشخيص من العمليات و/أو الاستثناءات.

ألق نظرة على قسم المشكلات الشائعة والحلول في هذه المقالة.

راجع قسم مشكلات GitHub الذي تتم مراقبته بشكل نشط. تحقق لمعرفة ما إذا تم بالفعل تقديم أي مشكلة مماثلة مع حل بديل. إذا لم تجد حلاً، فقم بتقديم مشكلة GitHub. يمكنك فتح علامة دعم للمشكلات العاجلة.

تسجيل التشخيص

تتضمن جميع الاستجابات في SDK على CosmosExceptionخاصية التشخيصDiagnostics. تسجل هذه الخاصية كل المعلومات المتعلقة بالطلب المفرد بما في ذلك إذا كانت هناك إعادة محاولة أو أي فشل مؤقت.

يتم إرجاع التشخيصات كسلسلة. تتغير السلسلة مع كل إصدار كما يتم العمل على تحسينها لاستكشاف أفضل سيناريوهات اكتشاف الأخطاء وإصلاحها. مع كل إصدار من SDK، يكون للسلسة تغيرات جذرية في التنسيق. تجنب توزيع السلسلة حتى تتجنب التغيرات الجذرية. توضح عينة التعليمات البرمجية التالية كيفية قراءة السجلات الخاصة بالتشخيص باستخدام SDK.NET:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

المشكلات الشائعة والحلول

اقتراحات عامة

• اتبع أي aka.ms ارتباط مضمن في تفاصيل الاستثناء.
• قم بتشغيل تطبيقك في نفس منطقة Azure مثل حساب Azure Cosmos DB الخاص بك، كلما أمكن ذلك.
• قد تواجه مشكلات في الاتصال/التوفر بسبب عدم وجود موارد على جهاز العميل. نوصي بمراقبة استخدام وحدة المعالجة المركزية الخاصة بك على العقد التي تقوم بتشغيل عميل Azure Cosmos DB، والتوسيع / ​​التدرج إذا كانت تعمل بأحمال عالية.

تحقق من مقاييس المدخل

سيساعد التحقق من مقاييس المدخل في تحديد ما إذا كانت مشكلة من جانب العميل أو إذا كانت هناك مشكلة في الخدمة. على سبيل المثال، إذا كانت المقاييس تحتوي على معدل مرتفع للطلبات محدودة المعدل (رمز حالة HTTP 429) مما يعني أنه يتم تقييد الطلب، فتحقق من قسم معدل الطلب كبير جداً.

أعد محاولة التصميم

راجع دليلنا لتصميم تطبيقات مرنة باستخدام Azure Cosmos DB SDKs للحصول على إرشادات حول كيفية تصميم التطبيقات المرنة ومعرفة دلالات إعادة المحاولة ل SDK.

SNAT

إذا تم نشر تطبيقك على أجهزة Azure الظاهرية دون عنوان IP عام، فبشكل افتراضي، تنشئ منافذ Azure SNAT اتصالات بأي نقطة نهاية خارج الجهاز الظاهري الخاص بك. عدد الاتصالات المسموح بها من الجهاز الظاهري لنقطة نهاية Azure Cosmos DB محدود بواسطة تكوين Azure SNAT. يمكن أن يؤدي هذا الموقف إلى تقييد الاتصال أو إغلاق الاتصال أو انتهاء مهلة الطلبالمذكورة أعلاه.

يتم استخدام منافذ Azure SNAT فقط عندما يكون للجهاز الظاهري عنوان IP خاص متصل بعنوان IP عام. هناك حلان لتجنب قيود Azure SNAT (بشرط أنك تستخدم بالفعل مثيل عميل واحد عبر التطبيق بأكمله):

• أضف نقطة نهاية خدمة Azure Cosmos DB إلى الشبكة الفرعية لشبكة Azure Virtual Machines الخاصة بك. لمزيد من المعلومات، راجع نقاط نهاية خدمة الشبكة الظاهرية Azure.

  عند تمكين نقطة نهاية الخدمة، لن يتم إرسال الطلبات من عنوان IP عام إلى Azure Cosmos DB. بدلاً من ذلك، يتم إرسال هوية الشبكة الافتراضية والشبكة الفرعية. قد يؤدي هذا التغيير إلى سقوط جدار الحماية إذا تم السماح بعناوين IP العامة فقط. إذا كنت تستخدم جدار حماية، فعند تمكين نقطة نهاية الخدمة، أضف شبكة فرعية إلى جدار الحماية باستخدام Virtual Network ACLs.

• قم بتعيين IP عام لجهاز Azure VM الخاص بك.

زمن انتقال مرتفع للشبكة

راجع دليل استكشاف أخطاء زمن الانتقال وإصلاحها للحصول على تفاصيل حول استكشاف أخطاء زمن الانتقال وإصلاحها.

فشل مصادقة الوكيل

إذا رأيت أخطاء تظهر على أنها HTTP 407:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

لا يتم إنشاء هذا الخطأ بواسطة SDK ولا يأتي من خدمة Azure Cosmos DB. هذا خطأ يتعلق بتكوين الشبكة. من المرجح أن الخادم الوكيل في تكوين الشبكة الخاص بك يفتقد مصادقة الوكيل المطلوبة. إذا كنت لا تتوقع استخدام وكيل، فتواصل مع فريق الشبكة. إذا كنت تستخدم وكيلًا، فتأكد من إعداد تكوين WebProxy الصحيح على CosmosClientOptions.WebProxy عند إنشاء مثيل العميل.

مشاكل الاستعلام الشائعة

تساعد مقاييس طلب البحث في تحديد المكان الذي يقضي فيه طلب البحث معظم الوقت. من مقاييس الاستعلام، يمكنك معرفة مقدار ما يتم إنفاقه على النهاية الخلفية مقابل العميل. تعرّف على المزيد حول دليل أداء الاستعلام.

إذا واجهت الخطأ التالي: Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: وكنت تستخدم Windows، فيجب الترقية إلى أحدث إصدار من Windows.

الخطوات التالية

• تعرف على إرشادات الأداء الخاصة بـ .NET SDK
• تعرف على أفضل الممارسات الخاصة بـ .NET SDK