مشاركة عبر

إمكانية مراقبة Azure Cosmos DB SDK

  • مقالة

ينطبق على: NoSQL

تدعم Azure Cosmos DB .NET وJava SDKs التتبع الموزع لمساعدتك في مراقبة تطبيقاتك. يعد تتبع تدفق الطلبات مفيدا في تصحيح الأخطاء وتحليل زمن الانتقال والأداء وجمع التشخيصات. تتبع الأجهزة للتطبيقات الخاصة بك باستخدام OpenTelemetry، وهو محايد من قبل المورد ولديه مجموعة من الاصطلاحات الدلالية لضمان تنسيق بيانات موحد بغض النظر عن المصدر الذي اخترته، أو استخدام Application Insights SDK أو Azure Monitor OpenTelemetry Distro.

الشروع في العمل

يتوفر التتبع الموزع في SDKs التالية:

SDK إصدار مدعوم ملاحظات
.NET v3 SDK >= 3.36.0 تتوفر هذه الميزة في إصدارات المعاينة وغير المعاينة. بالنسبة للإصدارات غير المعاينة، يتم إيقاف تشغيلها بشكل افتراضي. يمكنك تمكين التتبع عن طريق الإعداد DisableDistributedTracing = false في CosmosClientOptions.CosmosClientTelemetryOptions.
معاينة .NET v3 SDK >= 3.33.0-preview تتوفر هذه الميزة في إصدارات المعاينة وغير المعاينة. بالنسبة لإصدارات المعاينة، يتم تشغيلها بشكل افتراضي. يمكنك تعطيل التتبع عن طريق إعداد DisableDistributedTracing = true في CosmosClientOptions.CosmosClientTelemetryOptions.
Java v4 SDK >= 4.43.0

تتبع السمات

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

السمة النوع الوصف
net.peer.name سلسلة اسم مضيف Azure Cosmos DB.
db.name سلسلة اسم قاعدة بيانات Azure Cosmos DB.
db.system سلسلة معرف خدمة قاعدة البيانات. هو cosmosdb لجميع الطلبات.
db.operation سلسلة اسم العملية، على سبيل المثال. CreateItemAsync.
db.cosmosdb.container سلسلة اسم حاوية Azure Cosmos DB.
db.cosmosdb.client_id سلسلة معرف يمثل مثيل عميل فريد.
db.cosmosdb.operation_type سلسلة نوع العملية، على سبيل المثال. Create.
db.cosmosdb.connection_mode سلسلة وضع اتصال العميل. إما direct أو gateway.
db.cosmosdb.status_code العدد الصحيح رمز الحالة للطلب.
db.cosmosdb.sub_status_code العدد الصحيح رمز الحالة الفرعية للطلب.
db.cosmosdb.request_charge مزدوج وحدات الطلب المستهلكة للعملية.
db.cosmosdb.regions_contacted سلسلة قائمة المناطق التي تم الاتصال بها في حساب Azure Cosmos DB.
user_agent.original سلسلة سلسلة عامل المستخدم الكاملة التي تم إنشاؤها بواسطة Azure Cosmos DB SDK.

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

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

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

CosmosClientOptions options = new CosmosClientOptions()
{
    CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
    {
        DisableDistributedTracing = false,
        CosmosThresholdOptions = new CosmosThresholdOptions()
        {
            PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
            NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
        }
    },
};

يمكنك تكوين مستوى السجل للتحكم في سجلات التشخيص التي تتلقاها.

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

اعتمادا على بيئة التطبيق الخاص بك، هناك طرق مختلفة لتكوين مستوى السجل. فيما يلي نموذج تكوين في appSettings.json:

{ 
    "Logging": {​
        "LogLevel": {​
            "Azure-Cosmos-Operation-Request-Diagnostics": "Information"​
        }​
    }
}

تكوين OpenTelemetry

لاستخدام OpenTelemetry مع Azure Cosmos DB SDKs، أضف المصدر إلى موفر التتبع Azure.Cosmos.Operation . OpenTelemetry متوافق مع العديد من المصدرين الذين يمكنهم استيعاب بياناتك. يستخدم Azure Monitor OpenTelemetry Exporterالنموذج التالي ، ولكن يمكنك اختيار تكوين أي مصدر تريده. اعتمادا على المصدر الذي اخترته، قد ترى تأخيرا في استيعاب البيانات لمدة تصل إلى بضع دقائق.

تلميح

إذا كنت تستخدم الحزمة Azure.Monitor.OpenTelemetry.Exporter ، فتأكد من استخدام الإصدار >= 1.0.0-beta.11. إذا كنت تستخدم ASP.NET Core وAzure Monitor، نوصي باستخدام Azure Monitor OpenTelemetry Distro بدلا من ذلك.

يوضح هذا النموذج كيفية تكوين OpenTelemetry لتطبيق وحدة تحكم .NET. راجع العينة الكاملة على GitHub.

ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(
            serviceName: serviceName,
            serviceVersion: "1.0.0");

// Set up logging to forward logs to chosen exporter
using ILoggerFactory loggerFactory
    = LoggerFactory.Create(builder => builder
                                        .AddConfiguration(configuration.GetSection("Logging"))
                                        .AddOpenTelemetry(options =>
                                        {
                                            options.IncludeFormattedMessage = true;
                                            options.SetResourceBuilder(resource);
                                            options.AddAzureMonitorLogExporter(o => o.ConnectionString = aiConnectionString); // Set up exporter of your choice
                                        }));
/*.AddFilter(level => level == LogLevel.Error) // Filter  is irrespective of event type or event name*/

AzureEventSourceLogForwarder logforwader = new AzureEventSourceLogForwarder(loggerFactory);
logforwader.Start();

// Configure OpenTelemetry trace provider
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
_traceProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.Cosmos.Operation", // Cosmos DB source for operation level telemetry
               "Sample.Application") 
    .AddAzureMonitorTraceExporter(o => o.ConnectionString = aiConnectionString) // Set up exporter of your choice
    .AddHttpClientInstrumentation() // Added to capture HTTP telemetry
    .SetResourceBuilder(resource)
    .Build();

قم بتكوين Application Insights SDK

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

إشعار

استخدم الإصدار >= 2.22.0-beta2 من حزمة Application Insights لبيئة .NET المستهدفة.

يوضح النموذج التالي كيفية تكوين Application Insights لتطبيق وحدة تحكم .NET. راجع العينة الكاملة على GitHub.

IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);

IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

بمجرد استيعاب بيانات التتبع في Application Insights، يمكنك تصورها في مدخل Microsoft Azure لفهم تدفق الطلب في التطبيق الخاص بك. فيما يلي مثال على بيانات التتبع من استعلام التقسيم المتقاطع في بحث المعاملة في التنقل الأيسر من مدخل Microsoft Azure.

لقطة شاشة للتتبع الموزع لاستعلام التقسيم المشترك ل Azure Cosmos DB في البحث عن معاملة Application Insights.

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