تمكين Application Insights لتطبيقات ASP.NET Core
توضح هذه المقالة كيفية تمكين Application Insights لتطبيق ASP.NET Core المُوزع كتطبيق ويب Azure. يستخدم هذا التنفيذ نهجا يستند إلى SDK. يتوفر أيضا نهج التبعية التلقائية .
يمكن لـ Application Insights جمع بيانات تتبع الاستخدام التالية من تطبيق ASP.NET Core الخاص بك:
- الطلبات
- التبعيات
- استثناءات
- عدادات الأداء
- رسائل كشف أخطاء الاتصال
- السجلات
بالنسبة إلى نموذج التطبيق، سنستخدم تطبيق ASP.NET Core MVC الذي يستهدف net6.0
. ومع ذلك، يمكنك تطبيق هذه الإرشادات على جميع تطبيقات ASP.NET Core. إذا كنت تستخدم Worker Service، فاستخدم الإرشادات من هنا.
ملاحظة
يتوفر عرض .NET المستند إلى OpenTelemetry . تعرَّف على المزيد.
ملاحظة
في 31 مارس 2025، سينتهي دعم استيعاب مفاتيح الأجهزة. سيستمر استيعاب مفتاح الأجهزة في العمل ولكننا لن نقوم بتوفير تحديثات أو أي دعم للميزة. الانتقال إلى سلاسل الاتصال للاستفادة من الإمكانات الجديدة.
السيناريوهات المدعومة
يمكن لـ Application Insights SDK لـ ASP.NET Core مراقبة تطبيقاتك بغض النظر عن مكان تشغيلها أو كيفية تشغيلها. إذا كان تطبيقك قيد التشغيل ولديه اتصال بالشبكة ب Azure، يمكن ل Application Insights جمع بيانات تتبع الاستخدام منه. يتم دعم مراقبة 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 الخاص به.
لتوفير أسماء فريدة عالميا للموارد، يتم تعيين لاحقة مكونة من ستة أحرف لبعض الموارد. يرجى تدوين هذه اللاحقة لاستخدامها فيما بعد في هذه المقالة.
قم بإنشاء مصدر Application Insights
في مدخل Microsoft Azure، حدد مجموعة موارد application-insights-azure-café .
من قائمة شريط الأدوات العلوية، حدد "+ إنشاء".
في شاشة إنشاء مورد ، ابحث عن Application Insights وحدده في مربع نص البحث في السوق.
في شاشة "نظرة عامة على مورد Application Insights"، حدد "إنشاء".
في شاشة Application Insights، علامة التبويب Basics ، أكمل النموذج باستخدام الجدول التالي، ثم حدد الزر Review + create . قد تحتفظ الحقول التي لم تُحدد في الجدول أدناه بقيمها الافتراضية.
الحقل القيمة الاسم أدخل azure-cafe-application-insights-{SUFFIX}
، واستبدل {SUFFIX} بقيمة اللاحقة المناسبة المُسجلة سابقًا.المنطقة حدد نفس المنطقة التي اخترتها عند توزيع موارد المقالة. مساحة عمل Log Analytics حدد azure-café-log-analytics-workspace. بدلا من ذلك، يمكنك إنشاء مساحة عمل جديدة لتحليلات السجل. بمجرد اجتياز التحقق من الصحة، حدد "إنشاء" لتوزيع المورد.
بمجرد نشر المورد، ارجع إلى
application-insights-azure-cafe
مجموعة الموارد، وحدد مورد Application Insights الذي قمت بنشره.في شاشة Overview لمورد Application Insights، حدد الزر Copy to clipboard لنسخ قيمة سلسلة الاتصال. ستستخدم قيمة سلسلة الاتصال في القسم التالي من هذه المقالة.
تكوين إعداد تطبيق سلسلة اتصال Application Insights في web App Service
ارجع إلى
application-insights-azure-cafe
مجموعة الموارد وافتح مورد Azure-café-web-{SUFFIX} App Service.من القائمة اليسرى، ضمن قسم Settings، حدد Configuration. في علامة التبويب "إعدادات التطبيق"، حدد "+ إعداد تطبيق جديد" ضمن عنوان "إعدادات التطبيق".
في جزء Add/Edit application setting، أكمل النموذج كما يلي وحدد OK.
الحقل القيمة الاسم APPLICATIONINSIGHTS_CONNECTION_STRING القيمة الصق قيمة سلسلة الاتصال Application Insights التي نسختها في القسم السابق. في شاشة "تكوين App Service" حدد زر "حفظ" من قائمة شريط الأدوات. عند مطالبتك بحفظ التغييرات، حدد "متابعة".
تثبيت حزمة NuGet لـ Application Insights
نحتاج إلى تكوين تطبيق ويب ASP.NET Core MVC لإرسال بيانات تتبع الاستخدام. ويتحقق ذلك باستخدام Application Insights لحزمة NuGet لتطبيقات ويب ASP.NET Core.
في Visual Studio، افتح
1 - Starter Application\src\AzureCafe.sln
.في لوحة مستكشف الحلول Visual Studio، انقر بزر الماوس الأيمن فوق ملف مشروع AzureCafe وحدد إدارة حزم NuGet.
حدد علامة التبويب استعراض ثم ابحث عن Microsoft.ApplicationInsights.AspNetCore وحدده. حدد "تثبيت"، واقبل شروط الترخيص. يوصى باستخدام أحدث إصدار مستقر. للحصول على ملاحظات الإصدار الكامل ل SDK، راجع مستودع GitHub مفتوح المصدر.
اترك Visual Studio مفتوحًا للقسم التالي من المقالة.
تمكين بيانات تتبع الاستخدام من جانب الخادم لـ Application Insights
Application Insights لحزمة NuGet لتطبيقات ويب ASP.NET Core يُغلّف الميزات لتمكين إرسال بيانات تتبع الاستخدام من جانب الخادم إلى مورد Application Insights في Azure.
من مستكشف الحلول Visual Studio، افتح ملف Program.cs.
أدرج التعليمات البرمجية التالية قبل العبارة
builder.Services.AddControllersWithViews()
. تقرأ هذه التعليمة البرمجية تلقائيًا قيمة سلسلة اتصال Application Insights من التكوين.AddApplicationInsightsTelemetry
يسجلApplicationInsightsLoggerProvider
الأسلوب مع حاوية حقن التبعية المضمنة التي سيتم استخدامها بعد ذلك لتلبية طلبات تنفيذ ILoggerوILogger<TCategoryName>.builder.Services.AddApplicationInsightsTelemetry();
تلميح
تعرف على المزيد حول خيارات التكوين في ASP.NET Core.
تفعيل التتبع عن بعد من جانب العميل لتطبيقات الويب
الخطوات السابقة كافية لمساعدتك على البدء في جمع التتبع عن بعد من جانب الخادم. يحتوي نموذج التطبيق على مكونات من جانب العميل. اتبع الخطوات التالية لبدء جمع بيانات تتبع الاستخدام.
في Visual Studio مستكشف الحلول، افتح
\Views\_ViewImports.cshtml
.أضف التعليمة البرمجية التالية في نهاية الملف الموجود.
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
لتمكين المراقبة من جانب العميل للتطبيق الخاص بك بشكل صحيح، في Visual Studio مستكشف الحلول، افتح
\Views\Shared\_Layout.cshtml
التعليمات البرمجية التالية وأدرجها مباشرة قبل علامة الإغلاق<\head>
. يجب إدراج قصاصة JavaScript هذه في<head>
قسم كل صفحة من التطبيق الذي تريد مراقبته.@Html.Raw(JavaScriptSnippet.FullScript)
تلميح
بديل لاستخدام
FullScript
هوScriptBody
. استخدمScriptBody
إذا أردت التحكم في علامة<script>
لتعيين نهج أمان المحتوى:<script> // apply custom changes to this script tag. @Html.Raw(JavaScriptSnippet.ScriptBody) </script>
ملاحظة
يوفر حقن JavaScript تجربة تكوين افتراضية. إذا احتجت إلى تكوين يتجاوز تعيين سلسلة الاتصال، فأنت مطالب بإزالة الإدراج التلقائي كما هو موضح أعلاه وإضافة عدة تطوير البرامج JavaScript يدويًا.
تمكين مراقبة استعلامات قاعدة البيانات
عند التحقق من أسباب انخفاض الأداء، من المهم تضمين نتائج تحليلات في استدعاءات قاعدة البيانات. يمكنك تمكين المراقبة عن طريق تكوين وحدة التبعية. يتم تمكين مراقبة التبعية، بما في ذلك SQL، بشكل افتراضي.
اتبع هذه الخطوات لالتقاط نص استعلام SQL الكامل.
ملاحظة
قد يحتوي نص SQL على بيانات حساسة مثل PII وكلمات المرور. فاحذر عند تمكين هذه الميزة.
من مستكشف الحلول Visual Studio، افتح ملف Program.cs.
في الجزء العلوي من الملف، أضف العبارة التالية
using
.using Microsoft.ApplicationInsights.DependencyCollector;
لتمكين أدوات نص أمر SQL، قم بإدراج التعليمات البرمجية التالية مباشرة بعد التعليمات البرمجية
builder.Services.AddApplicationInsightsTelemetry()
.builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
تشغيل تطبيق ويب Azure Cafe
بعد نشر التعليمات البرمجية لتطبيق الويب، سيتدفق القياس عن بعد إلى Application Insights. يجمع Application Insights SDK طلبات الويب الواردة إلى التطبيق تلقائيًا.
من مستكشف الحلول Visual Studio، انقر بزر الماوس الأيمن فوق مشروع AzureCafe وحدد Publish من قائمة السياق.
حدد نشر لترقية التعليمات البرمجية الجديدة إلى Azure App Service.
عند نشر تطبيق ويب Azure Cafe بنجاح، يتم فتح نافذة متصفح جديدة لتطبيق ويب Azure Cafe.
لإنشاء بعض بيانات تتبع الاستخدام، اتبع هذه الخطوات في تطبيق الويب لإضافة مراجعة.
لعرض قائمة Cafe والمراجعات، حدد التفاصيل بجوار Cafe.
لعرض المراجعات وإضافتها، على شاشة مقهى، حدد علامة التبويب مراجعات. حدد الزر Add review لإضافة مراجعة.
في مربع الحوار "إنشاء مراجعة"، أدخل اسمًا وتصنيفًا وتعليقات وحمّل صورة للمراجعة. عند الانتهاء، حدد Add review.
إذا كنت بحاجة إلى إنشاء بيانات تتبع الاستخدام إضافية، فأضف مراجعات إضافية.
المقاييس الحية
يمكنك استخدام Live Metrics للتحقق بسرعة مما إذا تم تكوين مراقبة Application Insights بشكل صحيح. تعرض Live Metrics استخدام وحدة المعالجة المركزية لعملية التشغيل في الوقت الفعلي تقريبا. كما يمكن أن يعرض بيانات تتبع الاستخدام الأخرى مثل الطلبات والتبعيات والتتبعات. لاحظ أنه قد يستغرق ظهور بيانات تتبع الاستخدام في المدخل والتحليلات بضع دقائق.
عرض خريطة التطبيق
يُجري نموذج التطبيق استدعاءات إلى موارد Azure متعددة، بما في ذلك Azure SQL وAzure Blob Storage وخدمة لغة Azure (لمراجعة تحليل التوجه).
يحدد Application Insights بيانات تتبع الاستخدام الواردة وقادرا على إنشاء خريطة مرئية لتكاملات النظام التي يكتشفها.
تسجيل الدخول إلى مدخل Microsoft Azure.
افتح مجموعة الموارد لعينة التطبيق، وهي
application-insights-azure-cafe
.من قائمة الموارد، حدد مورد Application Insights
azure-cafe-insights-{SUFFIX}
.من القائمة اليسرى، أسفل عنوان التحقيق ، حدد خريطة التطبيق. راقب خريطة التطبيق التي أنشأتها.
عرض استدعاءات HTTP ونص أوامر SQL لقاعدة البيانات
في مدخل Microsoft Azure، افتح مورد Application Insights.
في القائمة اليسرى، أسفل رأس التحقيق ، حدد الأداء.
تحتوي علامة التبويب "العمليات" على تفاصيل استدعاءات HTTP التي تلقاها التطبيق. للتبديل بين طرق عرض الخادم والمستعرض (من جانب العميل) للبيانات، استخدم تبديل الخادم/المستعرض.
حدد عملية من الجدول، واختر التنقل لعينة من الطلب.
يتم عرض المعاملة الشاملة للطلب المحدد. في هذه الحالة، تم إنشاء مراجعة، بما في ذلك صورة، لذلك تتضمن استدعاءات إلى Azure Storage وخدمة اللغة (لتحليل التوجه). كما يتضمن استدعاءات قاعدة البيانات إلى SQL Azure لاستمرار المراجعة. في هذا المثال، يعرض "الحدث" المحدد الأول معلومات متعلقة باستدعاء HTTP POST.
حدد عنصر SQL لمراجعة نص أمر SQL الصادر إلى قاعدة البيانات.
اختياريا، حدد طلبات التبعية (الصادرة) إلى Azure Storage أو خدمة اللغة.
ارجع إلى شاشة Performance وحدد علامة التبويب Dependencies للتحقيق في المكالمات في الموارد الخارجية. لاحظ أن جدول "العمليات" يتضمن استدعاءات إلى تحليل التوجه وBlob Storage وAzure SQL.
تسجيل التطبيق باستخدام Application Insights
نظرة عامة على التسجيل
Application Insights هو نوع واحد من موفري التسجيل المتاح ASP.NET تطبيقات Core التي تصبح متاحة للتطبيقات عند تثبيت Application Insights لحزمة ASP.NET Core NuGet وتمكين مجموعة بيانات تتبع الاستخدام من جانب الخادم.
للتذكير، التعليمات البرمجية التالية في 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.LogInformation("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 أعلاه مع نموذج التطبيق ويتواجد في مجلد وحدات التحكم للمشروع.
باستخدام مستعرض إنترنت، افتح نموذج التطبيق. في شريط العناوين، ألحق
/api/Values
واضغط أدخل.في مدخل Microsoft Azure، انتظر بضع لحظات ثم حدد مورد Azure-café-insights-{SUFFIX} Application Insights.
من القائمة اليسرى لمورد Application Insights، ضمن قسم Monitoring، حدد Logs.
في جزء الجداول ، ضمن شجرة Application Insights ، انقر نقرا مزدوجا فوق جدول التتبعات .
عدّل الاستعلام لاسترداد تتبعات وحدة تحكم "القيم" كما يلي، ثم حدد "تشغيل" لتصفية النتائج.
traces | where operation_Name == "GET Values/Get"
تعرض النتائج رسائل التسجيل الموجودة في وحدة التحكم. تشير خطورة السجل 2 إلى مستوى التحذير، وتشير خطورة السجل 3 إلى مستوى الخطأ.
بدلا من ذلك، يمكنك أيضا كتابة الاستعلام لاسترداد النتائج استنادا إلى فئة السجل. بشكل افتراضي، الفئة هي الاسم المؤهل بالكامل للفئة حيث يتم إدخال 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 إلى Error. لذلك، يتم منع تتبع التحذير .
إيقاف تشغيل التسجيل إلى Application Insights
لتعطيل التسجيل باستخدام التكوين، قم بتعيين جميع قيم LogLevel إلى "None".
{
//... 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
إلى None.
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);
SDK مفتوح المصدر
للحصول على آخر التحديثات وإصلاحات الأخطاء، راجع ملاحظات الإصدار.
الخطوات التالية
- استكشف تدفقات المستخدم لفهم كيفية تنقل المستخدمين عبر تطبيقك.
- تكوين مجموعة لقطات لمشاهدة حالة التعليمات البرمجية المصدر والمتغيرات في اللحظة التي يتم فيها طرح استثناء.
- استخدم واجهة برمجة التطبيقات لإرسال أحداثك ومقاييسك للحصول على عرض أكثر تفصيلاً لأداء التطبيق واستخدامه.
- نظرة عامة على التوفر
- حقن التبعية في ASP.NET الأساسية
- تسجيل الدخول ASP.NET الأساسية
- تسجيل الدخول في Application Insights
- التدمير التلقائي ل Application Insights