تمكين Application Insights لتطبيقات ASP.NET Core

توضح هذه المقالة كيفية تمكين Application Insights لتطبيق ASP.NET Core المُوزع كتطبيق ويب Azure. يستخدم هذا التنفيذ نهجًا قائمًا على عدة تطوير البرامج، كما يتوفر نهج الأجهزة التلقائية.

يمكن لـ Application Insights جمع بيانات تتبع الاستخدام التالية من تطبيق ASP.NET Core:

  • الطلبات
  • التبعيات
  • استثناءات
  • عدادات الأداء
  • رسائل كشف أخطاء الاتصال
  • السجلات

سنستخدم مثال تطبيق ASP.NET Core MVC الذي يستهدف net6.0. يمكنك تطبيق هذه التعليمات على كافة تطبيقات ASP.NET Core. إذا كنت تستخدم Worker Service، فاستخدم الإرشادات من هنا.

ملاحظة

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

السيناريوهات المدعومة

يمكن لـ Application Insights SDK لـ ASP.NET Core مراقبة تطبيقاتك بغض النظر عن مكان تشغيلها أو كيفية تشغيلها. إذا كان التطبيق الخاص بك قيد التشغيل ولديه اتصال بالشبكة بـ Azure ، فيمكن جمع بيانات القياس عن بُعد. يتم دعم مراقبة Application Insights في كل مكان يتم دعم NET Core فيه. يغطي الدعم السيناريوهات التالية:

  • نظام التشغيل: Windows أو Linux أو Mac
  • طريقة الاستضافة: في العملية أو خارج العملية
  • طريقة النشر: تعتمد على الإطار أو قائمة بذاتها
  • خادم ويب: IIS (خادم معلومات إنترنت) أو Kestrel
  • منصة الاستضافة: ميزة تطبيقات الويب في Azure App Service وAzure VM وDocker وAzure Kubernetes Service (AKS) وما إلى ذلك
  • إصدار .NET Core: جميع إصدارات .NET Core المدعومة رسميًا والتي ليست في المعاينة
  • IDE: Visual Studio أو Visual Studio Code أو سطر الأوامر

المتطلبات الأساسية

إذا أردت اتباع الإرشادات الواردة في هذه المقالة، فلابد من توفر بعض المتطلبات المسبقة.

  • Visual Studio 2022
  • أحمال عمل Visual Studio: تطوير الويب وASP.NET، وتخزين البيانات ومعالجتها، وتطوير Azure
  • .NET 6.0
  • اشتراك Azure وحساب المستخدم (مع إمكانية إنشاء الموارد وحذفها)

توزيع موارد Azure

يرجى اتباع الإرشادات لتوزيع نموذج التطبيق من مستودع GitHub.

لتوفير أسماء فريدة عالميًا لبعض الموارد، عُيّنت لاحقة مكونة من 5 أحرف. يرجى تدوين هذه اللاحقة لاستخدامها فيما بعد في هذه المقالة.

عرض قائمة موارد Azure المُوزعة مع تمييز اللاحقة المكونة من 5 أحرف.

إنشاء مصدر Application Insights

  1. في مدخل Microsoft Azure، حدد موقع مجموعة موارد "application-insights-azure-cafe" وحددها.

  2. من قائمة شريط الأدوات العلوية، حدد "+ إنشاء".

    عرض مجموعة الموارد

  3. في شاشة "إنشاء مورد"، ابحث عن Application Insights في مربع نص "بحث marketplace" وحدده.

    عرض شاشة

  4. في شاشة "نظرة عامة على مورد Application Insights"، حدد "إنشاء".

    عرض شاشة

  5. في علامة التبويب "أساسيات" لشاشة "Application Insights". أكمل النموذج كما يلي، ثم حدد الزر "مراجعة + إنشاء". قد تحتفظ الحقول التي لم تُحدد في الجدول أدناه بقيمها الافتراضية.

    الحقل القيمة
    الاسم أدخل azure-cafe-application-insights-{SUFFIX}، واستبدل {SUFFIX} بقيمة اللاحقة المناسبة المُسجلة سابقًا.
    المنطقة حدد نفس المنطقة التي اخترتها عند توزيع موارد المقالة.
    مساحة عمل Log Analytics حدد azure-cafe-log-analytics-workspace، بدلًا من ذلك يمكن إنشاء مساحة عمل جديدة لتحليلات السجل هنا.

    عرض علامة التبويب

  6. بمجرد اجتياز التحقق من الصحة، حدد "إنشاء" لتوزيع المورد.

    شاشة

  7. بمجرد اكتمال التوزيع، ارجع إلى مجموعة الموارد application-insights-azure-cafe، وحدد مورد Application Insights المُوزّع.

    عرض مجموعة موارد Azure Cafe مع تمييز مورد Application Insights.

  8. في شاشة "نظرة عامة" لمورد Application Insights، انسخ قيمة "سلسلة الاتصال" لاستخدامها في القسم التالي من هذه المقالة.

    عرض شاشة

تكوين إعداد تطبيق سلسلة اتصال Application Insights في web App Service

  1. ارجع إلى مجموعة الموارد application-insights-azure-cafe، وحدد موقع مورد App Service لـ azure-cafe-web-{SUFFIX} وافتحه.

    عرض مجموعة موارد Azure Cafe مع تمييز مورد azure-cafe-web- {SUFFIX}.

  2. من القائمة اليسرى، أسفل عنوان "الإعدادات"، حدد" التكوين". في علامة التبويب "إعدادات التطبيق"، حدد "+ إعداد تطبيق جديد" ضمن عنوان "إعدادات التطبيق".

    عرض شاشة موارد App Service مع تحديد عنصر

  3. في جزء "إضافة/تحرير من إعدادات التطبيق"، أكمل النموذج كما يلي وحدد "موافق".

    الحقل القيمة
    الاسم APPLICATIONINSIGHTS_CONNECTION_STRING
    القيمة الصق سلسلة اتصال Application Insights التي حصلت عليها في القسم السابق.

    عرض جزء

  4. في شاشة "تكوين App Service" حدد زر "حفظ" من قائمة شريط الأدوات. عند مطالبتك بحفظ التغييرات، حدد "متابعة".

    عرض شاشة

تثبيت حزمة NuGet لـ Application Insights

نحتاج إلى تكوين تطبيق ويب ASP.NET Core MVC لإرسال بيانات تتبع الاستخدام. ويتحقق ذلك باستخدام Application Insights لحزمة NuGet لتطبيقات ويب ASP.NET Core.

  1. باستخدام Visual Studio، افتح 1 - Starter Application\src\AzureCafe.sln.

  2. في لوحة "مستكشف الحلول"، انقر بزر الماوس الأيمن فوق ملف مشروع AzureCafe، وحدد "إدارة حزم NuGet".

    عرض

  3. حدد علامة التبويب "استعراض"، ثم ابحث عن "Microsoft.ApplicationInsights.AspNetCore" وحدده. حدد "تثبيت"، واقبل شروط الترخيص. يوصى باستخدام أحدث إصدار ثابت. ابحث عن ملاحظات الإصدار الكاملة لـ SDK على GitHub repo مفتوح المصدر.

    علامة تبويب

  4. اترك Visual Studio مفتوحًا للقسم التالي من المقالة.

تمكين بيانات تتبع الاستخدام من جانب الخادم لـ Application Insights

Application Insights لحزمة NuGet لتطبيقات ويب ASP.NET Core يُغلّف الميزات لتمكين إرسال بيانات تتبع الاستخدام من جانب الخادم إلى مورد Application Insights في Azure.

  1. من مستكشف الحلول Visual Studio، حدد موقع ملف Program.cs وافتحه.

    عرض مستكشف الحلول Visual Studio مع تمييز

  2. أدرج التعليمات البرمجية التالية قبل العبارة builder.Services.AddControllersWithViews(). تقرأ هذه التعليمة البرمجية تلقائيًا قيمة سلسلة اتصال Application Insights من التكوين. الأسلوب AddApplicationInsightsTelemetry يسجل ApplicationInsightsLoggerProvider مع حاوية إدراج التبعية المُضمنة، والتي ستُستخدم فيما بعد لتلبية طلبات تنفيذ ILogger وILogger<TCategoryName>.

    builder.Services.AddApplicationInsightsTelemetry();
    

    تظهر نافذة تعليمات برمجية مع تمييز القصاصة البرمجية السابقة.

    تلميح

    تعرّف على المزيد حول خيارات التكوين في ASP.NET Core.

تفعيل التتبع عن بعد من جانب العميل لتطبيقات الويب

الخطوات السابقة كافية لمساعدتك على البدء في جمع التتبع عن بعد من جانب الخادم. يحتوي هذا التطبيق على مكونات من جانب العميل، فاتبع الخطوات التالية لبدء جمع بيانات تتبع الاستخدام.

  1. في مستكشف حلول Visual Studio، حدد موقع \Views\_ViewImports.cshtml وافتحه. أضف التعليمة البرمجية التالية في نهاية الملف الموجود.

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    

    ملف

  2. لتمكين المراقبة من جانب العميل لتطبيقك بشكل صحيح، فيجب أن تظهر قصاصة JavaScript البرمجية في قسم <head> لكل صفحة من التطبيق الذي تريد مراقبته. في مستكشف الحلول Visual Studio، حدد موقع \Views\Shared\_Layout.cshtml وافتحه، وأدرج التعليمات البرمجية التالية مباشرة قبل علامة الإغلاق <\head>.

    @Html.Raw(JavaScriptSnippet.FullScript)
    

    ملف

    تلميح

    يتوفر ScriptBody كبديل لاستخدام FullScript. استخدم ScriptBody إذا أردت التحكم في علامة <script> لتعيين نهج أمان المحتوى:

    <script> // apply custom changes to this script tag.
        @Html.Raw(JavaScriptSnippet.ScriptBody)
    </script>
    

ملاحظة

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

تمكين مراقبة استعلامات قاعدة البيانات

عند التحقق من أسباب انخفاض الأداء، من المهم تضمين نتائج تحليلات في استدعاءات قاعدة البيانات. مكّن المراقبة من خلال تكوين وحدة التبعية. تُمكّن مراقبة التبعية، بما في ذلك SQL، بشكل افتراضي. يمكن اتباع الخطوات التالية لتسجيل نص استعلام SQL بأكمله.

ملاحظة

قد يحتوي نص SQL على بيانات حساسة مثل PII وكلمات المرور. فاحذر عند تمكين هذه الميزة.

  1. من مستكشف الحلول Visual Studio، حدد موقع ملف Program.cs وافتحه.

  2. في الجزء العلوي من الملف، أضف العبارة التالية using.

    using Microsoft.ApplicationInsights.DependencyCollector;
    
  3. بعد التعليمات البرمجية builder.Services.AddApplicationInsightsTelemetry() مباشرة، أدرج ما يلي لتمكين أدوات نص أمر SQL.

    builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
    

    تظهر نافذة تعليمات برمجية مع تمييز الرمز السابق.

تشغيل تطبيق ويب Azure Cafe

بعد توزيع التعليمات البرمجية لتطبيق الويب، ستتدفق بيانات تتبع الاستخدام إلى Application Insights. يجمع Application Insights SDK طلبات الويب الواردة إلى التطبيق تلقائيًا.

  1. انقر بزر الماوس الأيمن فوق مشروع AzureCafe في مستكشف الحلول وحدد "نشر" من قائمة السياق.

    مستكشف الحلول Visual Studio مع تحديد مشروع Azure Cafe وتمييز

  2. حدد "نشر" لترقية التعليمات البرمجية الجديدة إلى Azure App Service.

    عرض ملف تعريف

  3. بمجرد نجاح النشر، تفتح نافذة متصفح جديدة لتطبيق ويب Azure Cafe.

    عرض تطبيق ويب Azure Cafe.

  4. نفّذ مختلف الأنشطة في تطبيق الويب لإنشاء بعض بيانات تتبع الاستخدام.

    1. حدد "التفاصيل" بجوار "Cafe" لعرض قائمته ومراجعاته.

      عرض جزء من قائمة Azure Cafe  مع تحديد زر

    2. على شاشة "Cafe" حدد علامة التبويب "مراجعات" لعرض المراجعات وإضافتها. حدد زر "إضافة مراجعة" لإضافة مراجعة.

      عرض شاشة تفاصيل

    3. في مربع الحوار "إنشاء مراجعة"، أدخل اسمًا وتصنيفًا وتعليقات وحمّل صورة للمراجعة. بمجرد الانتهاء، حدد "إضافة مراجعة".

      عرض مربع الحوار

    4. كرر إضافة المراجعات كما ترغب لإنشاء بيانات تتبع الاستخدام إضافية.

المقاييس الحية

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

خريطة التطبيق

يُجري نموذج التطبيق استدعاءات إلى موارد Azure متعددة، بما في ذلك Azure SQL وAzure Blob Storage وخدمة لغة Azure (لمراجعة تحليل التوجه).

عرض بنية نموذج التطبيق Azure Cafe.

يستكشف Application Insights بيانات تتبع الاستخدام الواردة، ويمكنه إنشاء خريطة مرئية لتكاملات النظام المكتشفة.

  1. انتقل إلى مدخل Microsoft Azure وسجّل الدخول.

  2. افتح مجموعة موارد نموذج التطبيق application-insights-azure-cafe.

  3. من قائمة الموارد، حدد مورد Application Insights azure-cafe-insights-{SUFFIX}.

  4. حدد "خريطة التطبيق" من القائمة اليسرى، أسفل العنوان "التحقيق". راقب خريطة التطبيق التي أنشأتها.

    عرض خريطة التطبيق لـ Application Insights.

عرض استدعاءات HTTP ونص أوامر SQL لقاعدة البيانات

  1. في مدخل Microsoft Azure، افتح مورد Application Insights.

  2. أسفل عنوان "التحقيق" في القائمة اليسرى، حدد "الأداء".

  3. تحتوي علامة التبويب "العمليات" على تفاصيل استدعاءات HTTP التي تلقاها التطبيق. يمكنك أيضًا التبديل بين طرق عرض الخادم والمستعرض (من جانب العميل) للبيانات.

    عرض شاشة

  4. حدد عملية من الجدول، واختر التنقل لعينة من الطلب.

    عرض شاشة

  5. تظهر العملية الشاملة للطلب المُحدد. في هذه الحالة، انتهى إنشاء مراجعة بما في ذلك صورة، وبالتالي فإنها تتضمن استدعاءات إلى Azure Storage، وخدمة اللغة (لتحليل التوجه)، بالإضافة إلى استدعاءات قاعدة البيانات إلى SQL Azure لاستمرار المراجعة. في هذا المثال، يعرض "الحدث" المحدد الأول معلومات متعلقة باستدعاء HTTP POST.

    عرض العملية الشاملة مع تحديد استدعاء HTTP Post.

  6. حدد عنصر SQL لمراجعة نص أمر SQL الصادر إلى قاعدة البيانات.

    عرض العملية الشاملة مع تفاصيل أمر SQL.

  7. حدد، إن أردت، طلبات التبعية (الصادرة) إلى Azure Storage أو خدمة اللغة.

  8. ارجع إلى شاشة "الأداء"، وحدد علامة التبويب "التبعيات" للتحقيق في المكالمات في الموارد الخارجية. لاحظ أن جدول "العمليات" يتضمن استدعاءات إلى تحليل التوجه وBlob Storage وAzure SQL.

    عرض شاشة

تسجيل التطبيق باستخدام Application Insights

نظرة عامة على التسجيل

Application Insights هو أحد أنوع موفري التسجيل المتاحة لتطبيقات ASP.NET Core التي ستتاح للتطبيقات عند تثبيت حزمة NuGet لـ Application Insights لـ ASP.NET Core وتمكين مجموعة بيانات تتبع الاستخدام من جانب الخادم. للتذكير، التعليمات البرمجية التالية في Program.csتُسجل ApplicationInsightsLoggerProvider مع حاوية إدراج التبعية المضمنة.

builder.Services.AddApplicationInsightsTelemetry();

مع تسجيل ApplicationInsightsLoggerProvider كموفر تسجيل، يكون التطبيق جاهزًا لتسجيل الدخول إلى Application Insights باستخدام إما إدراج الدالة الإنشائية مع ILogger أو البديل ILogger<TCategoryName> من النوع العام.

ملاحظة

باستخدام الإعدادات الافتراضية، كُوّن موفر التسجيل لتسجيل أحداث السجل تلقائياً مع خطورة من مستوى LogLevel.Warning أو أكبر منها.

يُرجى مراعاة نموذج وحدة التحكم التالية التي توضح إدراج ILogger الذي حُل مع ApplicationInsightsLoggerProvider الذي سُجل في حاوية إدراج التبعية. لاحظ في الأسلوب Get تُسجل رسالة خطأ ورسالة إعلام ورسالة تحذير.

ملاحظة

بشكل افتراضي، لن يُسجل تتبع مستوى "الإعلام". يُسجل مستوى "التحذير" والمستويات الأعلى منه فقط.

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInfo("An example of an Info trace..")
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

لمزيد من المعلومات، راجع تسجيل الدخول ASP.NET Core .

عرض السجلات في Application Insights

يُوزع ValuesController أعلاه مع نموذج التطبيق ويتواجد في مجلد وحدات التحكم للمشروع.

  1. باستخدام مستعرض إنترنت، افتح نموذج التطبيق. في شريط العناوين، ألحق /api/Values واضغط أدخل.

    عرض نافذة المستعرض مع إلحاق /api/Values لعنوان URL في شريط العناوين.

  2. انتظر بضع لحظات، ثم ارجع إلى مورد Application Insights في مدخل Microsoft Azure.

    عرض مجموعة الموارد مع تمييز مورد Application Insights.

  3. من القائمة اليسرى لمورد Application Insights، حدد "السجلات" من أسفل قسم "مراقبة". في جزء "الجداول"، انقر نقرًا مزدوجًا فوق جدول "التتبعات" الموجود أسفل شجرة تسلسل "Application Insights". عدّل الاستعلام لاسترداد تتبعات وحدة تحكم "القيم" كما يلي، ثم حدد "تشغيل" لتصفية النتائج.

    traces 
    | where operation_Name == "GET Values/Get"
    
  4. لاحظ أن النتائج تعرض رسائل التسجيل الموجودة في وحدة التحكم. تشير خطورة السجل 2 إلى مستوى التحذير، وتشير خطورة السجل 3 إلى مستوى الخطأ.

  5. بدلًا من ذلك، يمكن أيضًا كتابة الاستعلام لاسترداد النتائج استنادًا إلى فئة السجل. بشكل افتراضي، الفئة هي الاسم المؤهّل بالكامل للفئة حيث يُدرج ILogger، في هذه الحالة ValuesController (في حالة وجود مساحة اسم مقترنة بالفئة، فسيُسبق الاسم بمساحة الاسم). أعد كتابة الاستعلام التالي وشغّله لاسترداد النتائج استنادًا إلى الفئة.

    traces 
    | where customDimensions.CategoryName == "ValuesController"
    

التحكم في مستوى السجلات المُرسلة إلى Application Insights

تطبيقات ILogger لديها آلية مضمنة لتطبيق تصفية السجل. يتيح لك هذا التصفية التحكم في السجلات التي يتم إرسالها إلى كل موفر مسجل، بما في ذلك موفر Application Insights. يمكنك استخدام التصفية إما في التكوين (باستخدام ملف appsettings.json) أو في التعليمات البرمجية. لمزيد من المعلومات حول مستويات السجل وإرشادات حول الاستخدام المناسب، راجع وثائق مستوى السجل.

توضح الأمثلة التالية كيفية تطبيق قواعد التصفية على ApplicationInsightsLoggerProvider للتحكم في مستوى السجلات المُرسلة إلى Application Insights.

إنشاء قواعد التصفية باستخدام التكوين

سُمي ApplicationInsightsLoggerProvider بالاسم المستعار ApplicationInsights في التكوين. يعيّن القسم التالي من ملف appsettings.json مستوى السجل الافتراضي لجميع الموفرين إلى LogLevel.Warning. تكوين موفر ApplicationInsights خاصة للفئات التي تبدأ بـ "ValuesController" يتجاوز هذه القيمة الافتراضية بـ LogLevel.Error وأعلى.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

سيؤدي توزيع نموذج التطبيق باستخدام التعليمات البرمجية السابقة في appsettings.json فقط إلى توقف إرسال تتبع الخطأ إلى Application Insights عند التفاعل مع ValuesController. ذلك لأن "LogLevel" لفئة "ValuesController" مُعيّن إلى "خطأ"، لذلك يُمنع تتبع "التحذير".

إيقاف تشغيل التسجيل إلى Application Insights

لتعطيل التسجيل باستخدام التكوين، عيّن كافة قيم LogLevel إلى "بلا".

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

بالمثل، ضمن التعليمات البرمجية، عيّن المستوى الافتراضي لـ ApplicationInsightsLoggerProvider ولأي مستويات سجل لاحقة إلى "بلا".

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

المصدر المفتوح SDK

للحصول على آخر التحديثات وإصلاحات الأخطاء، راجع ملاحظات الإصدار.

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