استكشاف المشكلات وإصلاحها عند استخدام Azure Cosmos DB Java SDK v4 مع واجهة برمجة التطبيقات لحسابات NoSQL

ينطبق على: NoSQL

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

هام

تتناول هذه المقالة استكشاف الأخطاء وإصلاحها لـ Azure Cosmos DB Java SDK v4 فقط. يرجى الاطلاع على ملاحظات الإصدارAzure Cosmos DB Java SDK v4، ومستودع Maven، ونصائح الأداء لمزيد من المعلومات. إذا كنت تستخدم حاليا إصدارا أقدم من v4، فشاهد دليل الترحيل إلى Azure Cosmos DB Java SDK v4 للمساعدة في الترقية إلى الإصدار 4.

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

ابدأ بهذه القائمة:

• ألق نظرة على قسم المشكلات الشائعة والحلول في هذه المقالة.
• انظر إلى Java SDK في مستودع Azure Cosmos DB المركزي، والذي يتوفر مفتوح المصدر على GitHub. يحتوي على قسم مشكلات تتم مراقبته بشكل نشط. تحقق لمعرفة ما إذا تم بالفعل تقديم أي مشكلة مماثلة مع حل بديل. أحد النصائح المفيدة هو تصفية المشكلات حسب العلامة *cosmos:v4-item* .
• راجع نصائح الأداء الخاصة بـ Azure Cosmos DB Java SDK v4، واتبع الممارسات المقترحة.
• اقرأ بقية هذه المقالة، إذا لم تجد حلاً. ثم قم بتسجيل مشكلة GitHub. إذا كان هناك خيار لإضافة علامات إلى مشكلة GitHub، أضف *cosmos:v4-item* علامة.

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

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

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

توضح عينة التعليمات البرمجية التالية كيفية قراءة سجلات التشخيص باستخدام Java V4 SDK:

هام

نوصي بالتحقق من صحة الإصدار الأدنى الموصى به من Java V4 SDK والتأكد من أنك تستخدم هذا الإصدار أو أعلى. يمكنك التحقق من الإصدار الموصى به هنا.

متزامنة

عمليات قاعدة البيانات

CosmosDatabaseResponse databaseResponse = client.createDatabaseIfNotExists(databaseName);
CosmosDiagnostics diagnostics = databaseResponse.getDiagnostics();
logger.info("Create database diagnostics : {}", diagnostics); 

عمليات الحاوية

CosmosContainerResponse containerResponse = database.createContainerIfNotExists(containerProperties,
                  throughputProperties);
CosmosDiagnostics diagnostics = containerResponse.getDiagnostics();
logger.info("Create container diagnostics : {}", diagnostics);

عمليات العنصر

// Write Item
CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()),
                    new CosmosItemRequestOptions());
        
CosmosDiagnostics diagnostics = item.getDiagnostics();
logger.info("Create item diagnostics : {}", diagnostics);
        
// Read Item
CosmosItemResponse<Family> familyCosmosItemResponse = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);
        
CosmosDiagnostics diagnostics = familyCosmosItemResponse.getDiagnostics();
logger.info("Read item diagnostics : {}", diagnostics);

عمليات الاستعلام

String sql = "SELECT * FROM c WHERE c.lastName = 'Witherspoon'";
        
CosmosPagedIterable<Family> filteredFamilies = container.queryItems(sql, new CosmosQueryRequestOptions(),
                    Family.class);
        
//  Add handler to capture diagnostics
filteredFamilies = filteredFamilies.handle(familyFeedResponse -> {
    logger.info("Query Item diagnostics through handle : {}", 
    familyFeedResponse.getCosmosDiagnostics());
});
        
//  Or capture diagnostics through iterableByPage() APIs.
filteredFamilies.iterableByPage().forEach(familyFeedResponse -> {
    logger.info("Query item diagnostics through iterableByPage : {}",
    familyFeedResponse.getCosmosDiagnostics());
});

استثناءات Azure Cosmos DB

try {
  CosmosItemResponse<Family> familyCosmosItemResponse = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);
} catch (CosmosException ex) {
  CosmosDiagnostics diagnostics = ex.getDiagnostics();
  logger.error("Read item failure diagnostics : {}", diagnostics);
}

غير متزامنة

عمليات قاعدة البيانات

Mono<CosmosDatabaseResponse> databaseResponseMono = client.createDatabaseIfNotExists(databaseName);
databaseResponseMono.map(databaseResponse -> {
  CosmosDiagnostics diagnostics = databaseResponse.getDiagnostics();
  logger.info("Create database diagnostics : {}", diagnostics);
}).subscribe();

عمليات الحاوية

Mono<CosmosContainerResponse> containerResponseMono = database.createContainerIfNotExists(containerProperties,
                    throughputProperties);
containerResponseMono.map(containerResponse -> {
  CosmosDiagnostics diagnostics = containerResponse.getDiagnostics();
  logger.info("Create container diagnostics : {}", diagnostics);
}).subscribe();

عمليات العنصر

// Write Item
Mono<CosmosItemResponse<Family>> itemResponseMono = container.createItem(family,
                    new PartitionKey(family.getLastName()),
                    new CosmosItemRequestOptions());
        
itemResponseMono.map(itemResponse -> {
  CosmosDiagnostics diagnostics = itemResponse.getDiagnostics();
  logger.info("Create item diagnostics : {}", diagnostics);
}).subscribe();
        
// Read Item
Mono<CosmosItemResponse<Family>> itemResponseMono = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);

itemResponseMono.map(itemResponse -> {
  CosmosDiagnostics diagnostics = itemResponse.getDiagnostics();
  logger.info("Read item diagnostics : {}", diagnostics);
}).subscribe();

عمليات الاستعلام

String sql = "SELECT * FROM c WHERE c.lastName = 'Witherspoon'";
CosmosPagedFlux<Family> filteredFamilies = container.queryItems(sql, new CosmosQueryRequestOptions(),
                    Family.class);
//  Add handler to capture diagnostics
filteredFamilies = filteredFamilies.handle(familyFeedResponse -> {
  logger.info("Query Item diagnostics through handle : {}",
  familyFeedResponse.getCosmosDiagnostics());
});
        
//  Or capture diagnostics through byPage() APIs.
filteredFamilies.byPage().map(familyFeedResponse -> {
  logger.info("Query item diagnostics through byPage : {}",
  familyFeedResponse.getCosmosDiagnostics());
}).subscribe();

استثناءات Azure Cosmos DB

Mono<CosmosItemResponse<Family>> itemResponseMono = container.readItem(documentId,
                    new PartitionKey(documentLastName), Family.class);

itemResponseMono.onErrorResume(throwable -> {
  if (throwable instanceof CosmosException) {
    CosmosException cosmosException = (CosmosException) throwable;
    CosmosDiagnostics diagnostics = cosmosException.getDiagnostics();
    logger.error("Read item failure diagnostics : {}", diagnostics);
  }
  return Mono.error(throwable);
}).subscribe();

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

تدعم إصدارات Java V4 SDK الإصدار 4.43.0 والإصدارات الأحدث التسجيل التلقائي لتشخيص Cosmos لجميع الطلبات أو الأخطاء إذا كانت تفي بمعايير معينة. يمكن لمطوري التطبيقات تحديد حدود زمن الانتقال (للنقطة (إنشاء أو قراءة أو استبدال أو upsert أو تصحيح) أو العمليات غير المتعلقة بالنقطة (الاستعلام، موجز التغيير، المجمع والدفعة))، رسوم الطلب وحجم الحمولة. إذا تجاوزت الطلبات هذه الحدود المحددة، إصدار تشخيصات cosmos لهذه الطلبات تلقائيا.

بشكل افتراضي، يسجل Java v4 SDK هذه التشخيصات تلقائيا بتنسيق معين. ومع ذلك، يمكن تغيير هذا عن طريق تنفيذ CosmosDiagnosticsHandler الواجهة وتوفير معالج التشخيص المخصص الخاص بك.

يمكن بعد ذلك استخدام هذه CosmosDiagnosticsThresholds و CosmosDiagnosticsHandler في CosmosClientTelemetryConfig الكائن، والذي يجب تمريره إلى CosmosClientBuilder أثناء إنشاء مزامنة أو عميل غير متزامن.

ملاحظة: يتم تطبيق حدود التشخيص هذه عبر أنواع مختلفة من التشخيص بما في ذلك التسجيل والتتبع وبيانات تتبع الاستخدام للعميل.

توضح نماذج التعليمات البرمجية التالية كيفية تعريف حدود التشخيص، ومسجل التشخيص المخصص واستخدامها من خلال تكوين بيانات تتبع الاستخدام للعميل:

متزامنة

تعريف حدود التشخيص المخصصة

//  Create diagnostics threshold
CosmosDiagnosticsThresholds cosmosDiagnosticsThresholds = new CosmosDiagnosticsThresholds();
//  These thresholds are for demo purposes
//  NOTE: Do not use the same thresholds for production
cosmosDiagnosticsThresholds.setPayloadSizeThreshold(100_00);
cosmosDiagnosticsThresholds.setPointOperationLatencyThreshold(Duration.ofSeconds(1));
cosmosDiagnosticsThresholds.setNonPointOperationLatencyThreshold(Duration.ofSeconds(5));
cosmosDiagnosticsThresholds.setRequestChargeThreshold(100f);

تعريف معالج التشخيص المخصص

//  By default, DEFAULT_LOGGING_HANDLER can be used
CosmosDiagnosticsHandler cosmosDiagnosticsHandler = CosmosDiagnosticsHandler.DEFAULT_LOGGING_HANDLER;

//  App developers can also define their own diagnostics handler
cosmosDiagnosticsHandler = new CosmosDiagnosticsHandler() {
    @Override
    public void handleDiagnostics(CosmosDiagnosticsContext diagnosticsContext, Context traceContext) {
        logger.info("This is custom diagnostics handler: {}", diagnosticsContext.toJson());
    }
};

تعريف CosmosClientTelemetryConfig

//  Create Client Telemetry Config
CosmosClientTelemetryConfig cosmosClientTelemetryConfig =
    new CosmosClientTelemetryConfig();
cosmosClientTelemetryConfig.diagnosticsHandler(cosmosDiagnosticsHandler);
cosmosClientTelemetryConfig.diagnosticsThresholds(cosmosDiagnosticsThresholds);

//  Create sync client
CosmosClient client = new CosmosClientBuilder()
    .endpoint(AccountSettings.HOST)
    .key(AccountSettings.MASTER_KEY)
    .clientTelemetryConfig(cosmosClientTelemetryConfig)
    .buildClient();

غير متزامنة

تعريف حدود التشخيص المخصصة

//  Create diagnostics threshold
CosmosDiagnosticsThresholds cosmosDiagnosticsThresholds = new CosmosDiagnosticsThresholds();
//  These thresholds are for demo purposes
//  NOTE: Do not use the same thresholds for production
cosmosDiagnosticsThresholds.setPayloadSizeThreshold(100_00);
cosmosDiagnosticsThresholds.setPointOperationLatencyThreshold(Duration.ofSeconds(1));
cosmosDiagnosticsThresholds.setNonPointOperationLatencyThreshold(Duration.ofSeconds(5));
cosmosDiagnosticsThresholds.setRequestChargeThreshold(100f);

تعريف معالج التشخيص المخصص

//  By default, DEFAULT_LOGGING_HANDLER can be used
CosmosDiagnosticsHandler cosmosDiagnosticsHandler = CosmosDiagnosticsHandler.DEFAULT_LOGGING_HANDLER;

//  App developers can also define their own diagnostics handler
cosmosDiagnosticsHandler = new CosmosDiagnosticsHandler() {
    @Override
    public void handleDiagnostics(CosmosDiagnosticsContext diagnosticsContext, Context traceContext) {
        logger.info("This is custom diagnostics handler: {}", diagnosticsContext.toJson());
    }
};

تعريف CosmosClientTelemetryConfig

//  Create Client Telemetry Config
CosmosClientTelemetryConfig cosmosClientTelemetryConfig =
    new CosmosClientTelemetryConfig();
cosmosClientTelemetryConfig.diagnosticsHandler(cosmosDiagnosticsHandler);
cosmosClientTelemetryConfig.diagnosticsThresholds(cosmosDiagnosticsThresholds);

//  Create async client
CosmosAsyncClient client = new CosmosClientBuilder()
    .endpoint(AccountSettings.HOST)
    .key(AccountSettings.MASTER_KEY)
    .clientTelemetryConfig(cosmosClientTelemetryConfig)
    .buildAsyncClient();

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

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

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

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

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

مشكلات الشبكة، فشل مهلة قراءة Netty، الإنتاجية المنخفضة، زمن الوصول العالي

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

لأفضل أداء:

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

تقييد الاتصال

يمكن أن يحدث تقييد الاتصال إما بسبب حد الاتصال على الجهاز المضيف أو استنفاد منفذ Azure SNAT (PAT).

حد الاتصال في جهاز مضيف

تحتوي بعض أنظمة Linux، مثل Red Hat، على حد أعلى للعدد الإجمالي للملفات المفتوحة. يتم تنفيذ المقابس في Linux كملفات، لذا فإن هذا الرقم يحد من إجمالي عدد الاتصالات أيضاً. قم بتشغيل الأمر التالي.

ulimit -a

يجب أن يكون عدد الملفات المفتوحة القصوى المسموح بها، والتي تم تحديدها على أنها "nofile"، ضعف حجم تجمع الاتصال على الأقل. لمزيد من المعلومات، راجع نصائح أداء Azure Cosmos DB Java SDK v4.

استنفاد منفذ Azure SNAT (PAT)

إذا تم نشر تطبيقك على أجهزة 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 الخاص بك.

لا يمكن الوصول إلى الخدمة - جدار الحماية

ConnectTimeoutException يشير إلى أن SDK لا يمكنه الوصول إلى الخدمة. قد تحصل على فشل مشابه لما يلي عند استخدام الوضع المباشر:

GoneException{error=null, resourceAddress='https://cdb-ms-prod-westus-fd4.documents.azure.com:14940/apps/e41242a5-2d71-5acb-2e00-5e5f744b12de/services/d8aa21a5-340b-21d4-b1a2-4a5333e7ed8a/partitions/ed028254-b613-4c2a-bf3c-14bd5eb64500/replicas/131298754052060051p//', statusCode=410, message=Message: The requested resource is no longer available at the server., getCauseInfo=[class: class io.netty.channel.ConnectTimeoutException, message: connection timed out: cdb-ms-prod-westus-fd4.documents.azure.com/101.13.12.5:14940]

إذا كان لديك جدار حماية يعمل على جهاز التطبيق، فافتح نطاق المنفذ من 10000 إلى 20000، والذي يستخدمه الوضع المباشر. اتبع أيضاً حد الاتصال على جهاز مضيف.

UnknownHostException

UnknownHostException يعني أن إطار عمل Java لا يمكنه حل إدخال DNS لنقطة نهاية Azure Cosmos DB في الجهاز المتأثر. يجب التحقق من أن الجهاز يمكنه حل إدخال DNS أو إذا كان لديك أي برنامج تحليل DNS مخصص (مثل VPN أو الوكيل أو حل مخصص)، تأكد من أنه يحتوي على التكوين الصحيح لنقطة نهاية DNS التي يدعي الخطأ أنه لا يمكن حلها. في حالة استمرار الخطأ، يمكنك التحقق من حل DNS للجهاز من خلال استخدام أمر curl مع نقطة النهاية الموضحة في الخطأ.

وكيل HTTP

إذا كنت تستخدم وكيل HTTP، فتأكد من أنه يمكنه دعم عدد الاتصالات التي تم تكوينها في SDK ConnectionPolicy. خلاف ذلك، ستواجه مشكلات في الاتصال.

نمط الترميز غير صالح: حظر مؤشر ترابط Netty IO

تستخدم SDK مكتبة Netty IO للتواصل مع Azure Cosmos DB. يحتوي SDK على Async API ويستخدم واجهات برمجة تطبيقات IO غير المحظورة لـ Netty. يتم تنفيذ عمل IO الخاص بـ SDK على خيوط IO Netty. تم تكوين عدد خيوط IO Netty ليكون هو نفسه عدد أنوية وحدة المعالجة المركزية لجهاز التطبيق.

من المفترض أن يتم استخدام مؤشرات ترابط Netty IO فقط لأعمال Netty IO غير المحظورة. تعرض SDK نتيجة استدعاء واجهة برمجة التطبيقات في إحدى سلاسل عمليات Netty IO إلى رمز التطبيق. إذا أجرى التطبيق عملية طويلة الأمد بعد أن يتلقى النتائج على مؤشر ترابط Netty، فقد لا يحتوي SDK على سلاسل عمليات إدخال / إخراج كافية لأداء عمل IO الداخلي. قد يؤدي ترميز التطبيق هذا إلى معدل نقل منخفض وزمن انتقال مرتفع وإخفاقات io.netty.handler.timeout.ReadTimeoutException. الحل هو تبديل مؤشر الترابط عندما تعلم أن العملية تستغرق وقتاً.

على سبيل المثال، ألق نظرة على القصاصة البرمجية التالية، التي تضيف عناصر إلى حاوية (ابحث هنا عن إرشادات حول إعداد قاعدة البيانات والحاوية.) قد تقوم بعمل طويل الأمد يستغرق أكثر من بضعة مللي ثانية على مؤشر ترابط Netty. إذا كان الأمر كذلك، يمكنك في النهاية الوصول إلى حالة لا يوجد فيها مؤشر ترابط Netty IO لمعالجة عمل IO. نتيجة لذلك، تحصل على فشل ReadTimeoutException.

Java SDK V4 (Maven com.azure::azure-cosmos) Async API

//Bad code with read timeout exception

int requestTimeoutInSeconds = 10;

/* ... */

AtomicInteger failureCount = new AtomicInteger();
// Max number of concurrent item inserts is # CPU cores + 1
Flux<Family> familyPub =
        Flux.just(Families.getAndersenFamilyItem(), Families.getAndersenFamilyItem(), Families.getJohnsonFamilyItem());
familyPub.flatMap(family -> {
    return container.createItem(family);
}).flatMap(r -> {
    try {
        // Time-consuming work is, for example,
        // writing to a file, computationally heavy work, or just sleep.
        // Basically, it's anything that takes more than a few milliseconds.
        // Doing such operations on the IO Netty thread
        // without a proper scheduler will cause problems.
        // The subscriber will get a ReadTimeoutException failure.
        TimeUnit.SECONDS.sleep(2 * requestTimeoutInSeconds);
    } catch (Exception e) {
    }
    return Mono.empty();
}).doOnError(Exception.class, exception -> {
    failureCount.incrementAndGet();
}).blockLast();
assert(failureCount.get() > 0);

الحل هو تغيير مؤشر الترابط الذي تقوم بتنفيذ العمل الذي يستغرق وقتاً. حدد نسخة مفردة من برنامج الجدولة لتطبيقك.

Java SDK V4 (Maven com.azure::azure-cosmos) Async API

// Have a singleton instance of an executor and a scheduler.
ExecutorService ex  = Executors.newFixedThreadPool(30);
Scheduler customScheduler = Schedulers.fromExecutor(ex);

قد تحتاج إلى القيام بعمل يستغرق وقتاً، على سبيل المثال، عمل ثقيل حسابياً أو حظر الإدخال / الإخراج. في هذه الحالة، قم بتبديل مؤشر الترابط إلى عامل تم توفيره بواسطة customScheduler باستخدام واجهة برمجة التطبيقات .publishOn(customScheduler).

Java SDK V4 (Maven com.azure::azure-cosmos) Async API

container.createItem(family)
        .publishOn(customScheduler) // Switches the thread.
        .subscribe(
                // ...
        );

باستخدام publishOn(customScheduler)، تقوم بتحرير مؤشر ترابط Netty IO والتبديل إلى سلسلة المحادثات المخصصة الخاصة بك والتي يوفرها المجدول المخصص. هذا التعديل يحل المشكلة. لن تحصل على إخفاق io.netty.handler.timeout.ReadTimeoutException بعد الآن.

معدل الطلب كبير جداً

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

• تنفيذ التراجع في الفواصل الزمنية getRetryAfterInMilliseconds

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

معالجة الأخطاء من Java SDK Reactive Chain

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

هام

لا نوصي باستخدام onErrorContinue() عامل التشغيل، لأنه غير مدعوم في جميع السيناريوهات. لاحظ أن onErrorContinue() عامل تشغيل متخصص يمكن أن يجعل سلوك السلسلة التفاعلية غير واضح. إنه يعمل على مشغلي المنبع، وليس مشغلي المصب، ويتطلب دعماً محدداً للمشغل للعمل، ويمكن للنطاق أن ينتشر بسهولة في المنبع في كود المكتبة الذي لم يتوقعه (مما يؤدي إلى سلوك غير مقصود). يرجى الرجوع إلى وثائق onErrorContinue()لمزيد من التفاصيل حول هذا المشغل الخاص.

فشل الاتصال بمحاكي Azure Cosmos DB

شهادة HTTPS لمحاكي Azure Cosmos DB هي شهادة موقعة ذاتياً. لكي تعمل SDK مع المحاكي، قم باستيراد شهادة المحاكي إلى Java TrustStore. لمزيد من المعلومات، راجع تصدير شهادات Azure Cosmos DB Emulator.

مشكلات تعارضات التبعية

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

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

لتحديد أي من تبعيات مشروعك يجلب إصداراً أقدم من شيء يعتمد عليه Azure Cosmos DB Java SDK، قم بتشغيل الأمر التالي مقابل ملف pom.xml الخاص بالمشروع:

mvn dependency:tree

لمزيد من المعلومات، راجع دليل شجرة التبعية المخضرم.

بمجرد أن تعرف أي تبعية لمشروعك تعتمد على إصدار أقدم، يمكنك تعديل التبعية على مكتبة التعليمات البرمجية هذه في ملف pom واستبعاد التبعية متعدية، باتباع المثال أدناه (الذي يفترض أنreactor-core هي التبعية القديمة):

<dependency>
  <groupId>${groupid-of-lib-which-brings-in-reactor}</groupId>
  <artifactId>${artifactId-of-lib-which-brings-in-reactor}</artifactId>
  <version>${version-of-lib-which-brings-in-reactor}</version>
  <exclusions>
    <exclusion>
      <groupId>io.projectreactor</groupId>
      <artifactId>reactor-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

لمزيد من المعلومات، راجع دليل استبعاد التبعية المتعدية.

تمكين تسجيل عميل SDK

يستخدم Azure Cosmos DB Java SDK v4 SLF4j كواجهة تسجيل تدعم تسجيل الدخول إلى أطر تسجيل شائعة مثل log4j وlogback.

على سبيل المثال، إذا كنت تريد استخدام log4j كإطار عمل للتسجيل، فقم بإضافة libs التالية في مسار فئة Java الخاص بك.

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

أضف أيضاً ملف التكوين log4j.

# this is a sample log4j configuration

# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

لمزيد من المعلومات، راجع دليل تسجيل sfl4j.

إحصائيات شبكة نظام التشغيل

قم بتشغيل الأمر netstat للتعرف على عدد الاتصالات الموجودة في حالات مثل ESTABLISHED وCLOSE_WAIT.

في نظام Linux، يمكنك تشغيل الأمر التالي.

netstat -nap

في نظام التشغيل Windows، يمكنك تشغيل نفس الأمر بعلامات وسيطة مختلفة:

netstat -abn

قم بتصفية النتيجة إلى الاتصالات بنقطة نهاية Azure Cosmos DB فقط.

لا يمكن أن يكون عدد الاتصالات بنقطة نهاية Azure Cosmos DB في الحالة ESTABLISHED أكبر من حجم تجمع الاتصال الذي تم تكوينه.

قد تكون العديد من الاتصالات بنقطة نهاية Azure Cosmos DB في الحالة CLOSE_WAIT. قد يكون هناك أكثر من 1000. يشير الرقم المرتفع إلى أنه يتم إنشاء الاتصالات وقطعها بسرعة. هذا الموقف يحتمل أن يسبب مشاكل. لمزيد من المعلومات، راجع قسم المشكلات الشائعة والحلول.

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

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

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

• تعرف على إرشادات الأداء ل Java SDK v4
• تعرف على أفضل الممارسات ل Java SDK v4