مشاركة عبر

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

  • مقالة

توضح هذه المقالة كيفية تمكين Application Insights وتكوينه لتطبيق ASP.NET Core.

إشعار

تعتمد الوثائق التالية على واجهة برمجة تطبيقات Application Insights الكلاسيكية. الخطة طويلة الأجل ل Application Insights هي جمع البيانات باستخدام OpenTelemetry. لمزيد من المعلومات، راجع تمكين Azure Monitor OpenTelemetry لتطبيقات .NET Node.js وPython وJava وخريطة طريق OpenTelemetry الخاصة بنا. تتوفر إرشادات الترحيل ل .NET Node.js وPython.

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

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

نستخدم مثال تطبيق MVC. إذا كنت تستخدم خدمة العامل، فاستخدم الإرشادات الموجودة في Application Insights لتطبيقات خدمة العامل.

يتوفر عرض .NET المستند إلى OpenTelemetry. لمزيد من المعلومات، راجع نظرة عامة على OpenTelemetry.

إشعار

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

إشعار

إذا كنت تريد استخدام موفر ILogger مستقل، فاستخدم Microsoft.Extensions.Logging.ApplicationInsight.

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

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

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

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

تحتاج إلى

  • تطبيق ASP.NET Core يعمل. إذا كنت بحاجة إلى إنشاء تطبيق ASP.NET Core، فاتبع هذاالبرنامج التعليمي لـASP.NET Core.
  • مرجع إلى إصدار مدعوم من حزمة Application Insights NuGet.
  • سلسلة اتصال Application Insights صالحة. هذا المفتاح مطلوب لإرسال أيّ بيانات تتبع إلى Application Insights. إذا كنت بحاجة إلى إنشاء مورد Application Insights جديد للحصول على سلسلة اتصال، فراجع إنشاء مورد Application Insights.

تمكين القياس عن بعد من جانب الخادم Application Insights (Visual Studio)

بالنسبة لبرنامج Visual Studio لـMac، استخدم التوجيه اليدوي. يدعم إصدار Windows من Visual Studio فقط هذا الإجراء.

  1. افتح مشروعك في Visual Studio

  2. انتقل إلى Project>Add Application Insights Telemetry.

  3. حدد Azure Application Insights>Next.

  4. اختر اشتراكك ومثيل Application Insights. أو يمكنك إنشاء مثيل جديد باستخدام Create new. حدد التالي.

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

  6. بعد إضافة Application Insights إلى مشروعك، تحقق للتأكد من أنك تستخدم أحدث إصدار ثابت من SDK. انتقل إلى Project>إدارة حزم NuGet>Microsoft.ApplicationInsights.AspNetCore. إذا كنت بحاجة إلى ذلك، فحدد «تحديث».

    لقطة شاشة توضح مكان تحديد حزمة Application Insights للتحديث.

تمكين القياس عن بعد من جانب الخادم Application Insights (بدون Visual Studio)

  1. قم بتثبيت حزمة Application Insights SDK NuGet لـ ASP.NET Core.

    نوصي باستخدام أحدث إصدار ثابت دائمًا. ابحث عن ملاحظات الإصدار الكاملة لـ SDK على GitHub repo مفتوح المصدر.

    يظهر نموذج التعليمات البرمجية التالي التغييرات التي يجب إضافتها إلى ملف مشروعك .csproj :

    <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>

  2. أضف AddApplicationInsightsTelemetry() إلى الصف أو program.cs الخاص بكstartup.cs. يعتمد الاختيار على إصدار .NET Core.

    أضف builder.Services.AddApplicationInsightsTelemetry(); إلى الأسلوب WebApplication.CreateBuilder() في فئة Program الخاصة بك، كما في هذا المثال:

    // This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

  3. تثبيت سلسلة الاتصال.

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

    {
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}

    بدلا من ذلك، حدد سلسلة الاتصال في APPLICATIONINSIGHTS_CONNECTION_STRING متغير البيئة أو ApplicationInsights:ConnectionString في ملف تكوين JSON.

    على سبيل المثال:

    • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
    • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
    • عادة ما APPLICATIONINSIGHTS_CONNECTION_STRING يتم استخدام في تطبيقات الويب. كما يمكن استخدامه في جميع الأماكن التي يتم فيها دعم SDK هذا.

    إشعار

    يفوز سلسلة الاتصال المحدد في التعليمات البرمجية على متغير APPLICATIONINSIGHTS_CONNECTION_STRINGالبيئة ، والذي يفوز على الخيارات الأخرى.

أسرار المستخدم وموفري التكوين الآخرين

إذا كنت ترغب في تخزين سلسلة الاتصال في بيانات مستخدم ASP.NET Core السرية أو استردادها من موفر تكوين آخر، يمكنك استخدام التحميل الزائد مع المعلمة Microsoft.Extensions.Configuration.IConfiguration. معلمة المثال هي services.AddApplicationInsightsTelemetry(Configuration);.

في Microsoft.ApplicationInsights.AspNetCore الإصدار 2.15.0 والإصدارات الأحدث، يقرأ الاتصال services.AddApplicationInsightsTelemetry() تلقائيا سلسلة الاتصال من Microsoft.Extensions.Configuration.IConfiguration التطبيق. ليست هناك حاجة لتوفير IConfigurationبشكل صريح .

إذا قام IConfiguration بتحميل التكوين من موفرين متعددين، فعندئذ يعطي services.AddApplicationInsightsTelemetry الأولوية للتكوين من appsettings.json، بغض النظر عن الترتيب الذي تتم إضافة الموفرين به. services.AddApplicationInsightsTelemetry(IConfiguration) استخدم الأسلوب لقراءة التكوين من IConfiguration دون هذه المعاملة التفضيلية ل appsettings.json.

تشغيل التطبيق الخاص بك

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

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

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

تمكين المقاييس المباشرة باستخدام التعليمات البرمجية لأي تطبيق .NET

إشعار

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

لتكوين المقاييس المباشرة يدويا:

  1. تثبيت حزمة NuGet Microsoft.ApplicationInsights.PerfCounterCollector.
  2. يظهر نموذج التعليمات البرمجية لتطبيق وحدة التحكم التالي إعداد مقاييس مباشرة:
using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

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

سجلات ILogger

التكوين الافتراضي بتجميع سجلاتILoggerWarning وسجلات أكثر شدة. لمزيد من المعلومات، راجع كيف أعمل تخصيص مجموعة سجلات ILogger؟.

التبعيات

يتم تمكين مجموعة التبعية بشكل افتراضي. يشرح تتبع التبعية في Application Insights التبعيات التي يتم جمعها تلقائيا ويحتوي أيضا على خطوات للقيام بالتتبع اليدوي.

عدادات الأداء

دعم عدادات الأداء في ASP.NET Core محدود:

  • تجمع إصدارات SDK 2.4.1 والإصدارات الأحدث عدادات الأداء إذا كان التطبيق قيد التشغيل في Web Apps (Windows).
  • تجمع إصدارات SDK 2.7.1 والإصدارات الأحدث عدّادات الأداء إذا كان التطبيق قيد التشغيل في Windows ويستهدف netstandard2.0 أو إصدارات أحدث.
  • بالنسبة للتطبيقات التي تستهدف .NET Framework، تدعم جميع إصدارات SDK عدادات الأداء.
  • تدعم إصدارات SDK 2.8.0 والإصدارات الأحدث عداد وحدة المعالجة المركزية/الذاكرة في Linux. لا يوجد عدّاد آخر مدعوم في Linux. للحصول على عدادات النظام في Linux والبيئات الأخرى غير Windows، استخدم EventCounters.

EventCounter

يتم تمكينهEventCounterCollectionModule افتراضيًا. لمعرفة كيفية تكوين قائمة العدادات التي سيتم تجميعها، راجع مقدمة EventCounters.

إثراء البيانات من خلال HTTP

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

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

الخطوات السابقة كافية لمساعدتك على البدء في جمع التتبع عن بعد من جانب الخادم. إذا كان التطبيق الخاص بك يحتوي على مكونات من جانب العميل، فاتبع الخطوات التالية لبدء جمع بيانات تتبع الاستخدام باستخدام حقن برنامج JavaScript (Web) SDK Loader Script حسب التكوين.

  1. في _ViewImports.cshtml ، أضف الحقن:

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

  2. في _Layout.cshtml ، إدراج في HtmlHelper نهاية القسم ولكن قبل أي برنامج نصي <head> آخر. إذا كنت تريد الإبلاغ عن أي تتبع JavaScript مخصص عن بُعد من الصفحة، فأدخله بعد هذه القصاصة البرمجية:

    @Html.Raw(JavaScriptSnippet.FullScript)
</head>

كبديل لاستخدام FullScript، ScriptBody يتوفر بدءا من Application Insights SDK ل ASP.NET Core الإصدار 2.14. استخدم ScriptBody إذا كنت بحاجة إلى التحكم في العلامة <script> لتعيين نهج أمان المحتوى:

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

أسماء .cshtmlالملفات المشار إليها سابقًا مأخوذة من قالب تطبيق MVC افتراضي. في النهاية، إذا كنت تريد تمكين المراقبة من جانب العميل للتطبيق الخاص بك بشكل صحيح، يجب أن يظهر برنامج JavaScript JavaScript JavaScript (Web) SDK Loader Script في <head> قسم كل صفحة من التطبيق الخاص بك التي تريد مراقبتها. أضف JavaScript JavaScript (Web) SDK Loader Script إلى _Layout.cshtml في قالب تطبيق لتمكين المراقبة من جانب العميل.

إذا لم يتضمن _Layout.cshtmlمشروعك ، فلا يزال بإمكانك إضافة مراقبة من جانب العميل عن طريق إضافة برنامج JavaScript JavaScript (Web) SDK Loader Script إلى ملف مكافئ يتحكم في <head> جميع الصفحات داخل تطبيقك. بدلا من ذلك، يمكنك إضافة برنامج JavaScript (Web) SDK Loader Script إلى صفحات متعددة، ولكننا لا نوصي بذلك.

إشعار

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

قم بتكوين Application Insights SDK

يمكنك تخصيص Application Insights SDK لـ ASP.NET Core لتغيير التكوين الافتراضي. قد يكون مستخدمو Application Insights ASP.NET SDK على دراية بتغيير التكوين باستخدام ApplicationInsights.config أو عن طريق تعديل TelemetryConfiguration.Active. بالنسبة لـASP.NET Core ، قم بإجراء جميع تغييرات التكوين تقريبًا في طريقة ConfigureServices()الفئةStartup.cs، ما لم يتم توجيهك بخلاف ذلك. تقدم الأقسام التالية المزيد من المعلومات.

إشعار

في تطبيقات ASP.NET Core، لا يتمTelemetryConfiguration.Active دعم تغيير التكوين عن طريق التعديل.

استخدام ApplicationInsightsServiceOptions

يمكنك تعديل بعض الإعدادات الشائعة عن طريق التمرير ApplicationInsightsServiceOptions إلى، كما في هذا AddApplicationInsightsTelemetry المثال:

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

يحتوي هذا الجدول على ApplicationInsightsServiceOptionsالقائمة الكاملة للإعدادات:

الإعدادات ‏‏الوصف الإعداد الافتراضي
EnablePerformanceCounterCollectionModule تمكين/تعطيلPerformanceCounterCollectionModule صواب
EnableRequestTrackingTelemetryModule تمكين/تعطيلRequestTrackingTelemetryModule صواب
EnableEventCounterCollectionModule تمكين/تعطيلEventCounterCollectionModule صواب
EnableDependencyTrackingTelemetryModule تمكين/تعطيلDependencyTrackingTelemetryModule صواب
EnableAppServicesHeartbeatTelemetryModule تمكين/تعطيلAppServicesHeartbeatTelemetryModule صواب
EnableAzureInstanceMetadataTelemetryModule تمكين/تعطيلAzureInstanceMetadataTelemetryModule صواب
تمكين QuickPulseMetricStream تمكين/تعطيل ميزة LiveMetrics. صواب
EnableAdaptiveSampling تمكين/تعطيل أخذ العينات التكيفية. صواب
EnableHeartbeat تمكين/تعطيل ميزة رسالة كشف أخطاء الاتصال. يرسل بشكل دوري (افتراضي 15 دقيقة) مقياسا مخصصا يسمى HeartbeatState بمعلومات حول وقت التشغيل مثل إصدار .NET ومعلومات بيئة Azure، إن أمكن. صواب
AddAutoCollectedMetricExtractor تمكين/تعطيل AutoCollectedMetrics extractor. يرسل معالج بيانات تتبع الاستخدام هذا مقاييس مجمعة مسبقا حول الطلبات/التبعيات قبل أخذ العينات. صواب
طلبCollectionOptions.TrackExceptions تمكين/تعطيل الإبلاغ عن تتبع الاستثناء غير المعالج بواسطة وحدة مجموعة الطلب. خطأ في netstandard2.0 (لأنه يتم تعقب الاستثناءات باستخدام ApplicationInsightsLoggerProvider). صحيح خلاف ذلك.
EnableDiagnosticsTelemetryModule تمكين/تعطيلDiagnosticsTelemetryModule يؤدي تعطيل إلى تجاهل الإعدادات التالية: EnableHeartbeatو EnableAzureInstanceMetadataTelemetryModuleو.EnableAppServicesHeartbeatTelemetryModule صواب

للحصول على أحدث قائمة، راجع الإعدادات القابلة للتكوين بتنسيق ApplicationInsightsServiceOptions.

توصية التكوين لـMicrosoft.ApplicationInsights.AspNetCore SDK 2.15.0 والأحدث

في Microsoft.ApplicationInsights.AspNetCore SDK الإصدار 2.15.0 والإصدارات الأحدث، قم بتكوين كل إعداد متوفر في ، بما في ApplicationInsightsServiceOptionsذلك ConnectionString. استخدم مثيل التطبيق IConfiguration . يجب أن تكون الإعدادات ضمن القسم ApplicationInsights، كما هو موضح في المثال التالي. يقوم القسم التالي من appsettings.json بتكوين سلسلة الاتصال وتعطيل أخذ العينات التكيفية وجمع عداد الأداء.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

إذا تم استخدام builder.Services.AddApplicationInsightsTelemetry(aiOptions) لـ ASP.NET Core 6.0 أو services.AddApplicationInsightsTelemetry(aiOptions) لـ ASP.NET Core 3.1 والإصدارات السابقة، فإنه يتجاوز الإعدادات من Microsoft.Extensions.Configuration.IConfiguration.

أخذ عينات

يدعم Application Insights SDK لـ ASP.NET Core أخذ العينات بمعدل ثابت ومعدل تكيفي. يتم تمكين أخذ العينات التكيفية بشكل افتراضي.

لمزيد من المعلومات، راجعتكوين عينات التكيف لتطبيقات ASP.NET الأساسية.

إضافة TelemetryInitializers

عندما تريد إثراء بيانات تتبع الاستخدام بمزيد من المعلومات، استخدم مهيئات بيانات تتبع الاستخدام.

إضافة أي جديد TelemetryInitializer إلى DependencyInjection الحاوية كما هو موضح في التعليمات البرمجية التالية. تلتقط SDK تلقائيًاTelemetryInitializerأية إضافة إلى DependencyInjection الحاوية.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

إشعار

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();يعمل على التهيئة البسيطة. بالنسبة للآخرين، builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); مطلوب.

إزالة TelemetryInitializers

افتراضيًا، توجد مُهيئات بيانات تتبع الاستخدام عن بُعد. لإزالة جميع بيانات تتبع الاستخدام أو المُحددة منها، استخدم نموذج التعليمات البرمجية التالي بعد الاتصال AddApplicationInsightsTelemetry().

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

إضافة معالجات بيانات تتبع الاستخدام

يمكنك إضافة معالجات بيانات تتبع الاستخدامTelemetryConfigurationباستخدام طريقة الامتدادAddApplicationInsightsTelemetryProcessor فيIServiceCollection. تستخدم معالجات بيانات تتبع الاستخدام في سيناريوهات التصفية المتقدمة. استخدم المثال التالي:

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

تكوين أو إزالة الوحدات الافتراضية لبيانات تتبع الاستخدام

يجمع Application Insights تلقائيًا بيانات تتبع الاستخدام حول أحمال عمل معينة دون الحاجة إلى تتبع يدوي من قبل المستخدم.

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

  • RequestTrackingTelemetryModule: يجمع RequestTelemetry من طلبات الويب الواردة.
  • DependencyTrackingTelemetryModule: يجمع DependencyTelemetry من مكالمات HTTP الصادرة ومكالمات SQL.
  • PerformanceCollectorModule: يجمع Windows PerformanceCounters.
  • QuickPulseTelemetryModule: يجمع بيانات تتبع الاستخدام لإظهارها في جزء المقاييس المباشرة.
  • AppServicesHeartbeatTelemetryModule: يجمع رسائل كشف أخطاء الاتصال (التي يتم إرسالها كمقاييس مخصصة)، حول بيئة App Service حيث تتم استضافة التطبيق.
  • AzureInstanceMetadataTelemetryModule: يجمع رسائل كشف أخطاء الاتصال (التي يتم إرسالها كمقاييس مخصصة)، حول بيئة Azure VM حيث تتم استضافة التطبيق.
  • EventCounterCollectionModule: يجمع EventCounters. هذه الوحدة النمطية هي ميزة جديدة ومتاحة في الإصدار 2.8.0 من SDK والإصدارات الأحدث.

لتكوين أي افتراضي TelemetryModule، استخدم أسلوب ConfigureTelemetryModule<T> الملحق على IServiceCollection، كما هو موضح في المثال التالي:

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

في الإصدارات 2.12.2 والإصدارات الأحدثApplicationInsightsServiceOptions، يتضمن خيارًا سهلًا لتعطيل أي من الوحدات النمطية الافتراضية.

كوّن قناة بيانات تتبع الاستخدام

قناة بيانات تتبع الاستخدامالافتراضية هي ServerTelemetryChannel. يوضح المثال التالي كيفية تجاوزها.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

إشعار

إذا كنت تريد مسح المخزن المؤقت، فشاهد مسح البيانات. على سبيل المثال، قد تحتاج إلى مسح المخزن المؤقت إذا كنت تستخدم SDK في تطبيق يتم إيقاف تشغيله.

تعطيل بيانات تتبع الاستخدام ديناميكيًا

إذا كنت تريد تعطيل بيانات تتبع الاستخدام بشكل مشروط وديناميكي، فيمكنك TelemetryConfigurationحل المثيل باستخدام حاوية حقن التبعية ASP.NET Core في أي مكان في التعليمات البرمجيةDisableTelemetry الخاصة بك وتعيين العلامة عليها.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

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

الأسئلة الشائعة

يقدم هذا القسم إجابات للأسئلة الشائعة.

هل يدعم Application Insights ASP.NET Core 3.1؟

لم تعد Microsoft تدعم ASP.NET Core 3.1.

يمكن استخدام Application Insights SDK ل ASP.NET Core الإصدار 2.8.0 وVisual Studio 2019 أو أحدث مع تطبيقات ASP.NET Core 3.1.

كيف يمكنني تتبع بيانات تتبع الاستخدام الذي لا يتم جمعه تلقائيًا؟

الحصول على مثيل TelemetryClient باستخدام حقن الدالة الإنشائية واستدعاء الأسلوب المطلوب TrackXXX() عليه. لا نوصي بإنشاء مثيلات جديدةTelemetryClientأو مثيلات TelemetryConfigurationفي تطبيق ASP.NET Core. تم تسجيل مثيل أحادي من TelemetryClient بالفعل في الحاوية DependencyInjection ، والتي تشترك TelemetryConfiguration مع بقية بيانات تتبع الاستخدام. إنشاء مثيل جديد TelemetryClient فقط إذا كان بحاجة إلى تكوين منفصل عن بقية بيانات تتبع الاستخدام.

يوضح المثال التالي كيفية تعقب بيانات تتبع الاستخدام الإضافية من وحدة تحكم.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

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

كيف أعمل التقاط نص الطلب والاستجابة في بيانات تتبع الاستخدام الخاصة بي؟

يحتوي ASP.NET Core على دعم مضمن لتسجيل معلومات طلب/استجابة HTTP (بما في ذلك النص الأساسي) عبر ILogger. من المستحسن الاستفادة من هذا. قد يعرض هذا معلومات التعريف الشخصية (PII) في بيانات تتبع الاستخدام، ويمكن أن يتسبب في زيادة التكاليف (تكاليف الأداء وفواتير Application Insights) بشكل كبير، لذا قم بتقييم المخاطر بعناية قبل استخدام هذا.

كيف يمكنني تخصيص مجموعة سجلات ILogger؟

الإعداد الافتراضي ل Application Insights هو تسجيل التحذير والسجلات الأكثر خطورة فقط.

التقاط المعلومات والسجلات الأقل خطورة عن طريق تغيير تكوين التسجيل لموفر Application Insights كما يلي.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

من المهم ملاحظة أن المثال التالي لا يتسبب في قيام موفر Application Insights بالتقاط Information السجلات. لا يتم التقاطها لأن SDK تضيف مرشح تسجيل افتراضيًا يرشدك إلىApplicationInsightsالتقاط السجلات فقطWarning وسجلات أكثر خطورة. يتطلب Application Insights تجاوزًا صريحًا.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

لمزيد من المعلومات، راجع تكوين ILogger.

استخدمت بعض قوالب Visual Studio طريقة الامتداد UseApplicationInsights () على IWebHostBuilder لتمكين Application Insights. هل هذا الاستخدام لا يزال صالحًا؟

لا تزال طريقةUseApplicationInsights() الامتداد مدعومة ، ولكن تم تمييزها على أنها قديمة في Application Insights SDK الإصدار 2.8.0 والإصدارات الأحدث. تتم إزالته في الإصدار الرئيسي التالي من SDK. لتمكين القياس عن بعد ل Application Insights، استخدم AddApplicationInsightsTelemetry() لأنه يوفر تحميلا زائدا للتحكم في بعض التكوينات. أيضًا، في تطبيقات ASP.NET Core 3.X، services.AddApplicationInsightsTelemetry()هي الطريقة الوحيدة لتمكين Application Insights.

أنا أقوم بنشر تطبيق ASP.NET Core الخاص بي على تطبيقات الويب. هل يجب علي الاستمرار في تمكين ملحق Application Insights من تطبيقات الويب؟

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

  • يستمر القياس عن بعد ل Application Insights في العمل في:
    • جميع أنظمة التشغيل، بما في ذلك Windows، Linux، وMac.
    • جميع أوضاع النشر، بما في ذلك القائمة بذاتها أو التي تعتمد على إطار العمل.
    • جميع الأطر المستهدفة، بما في ذلك .NET Framework الكامل.
    • جميع خيارات الاستضافة، بما في ذلك تطبيقات الويب والأجهزة الظاهرية وLinux والحاويات وAKS والاستضافة غير Azure.
    • جميع إصدارات .NET Core، بما في ذلك إصدارات المعاينة.
  • يمكنك رؤية القياس عن بُعد محليًا عند تصحيح الأخطاء من Visual Studio.
  • يمكنك تتبع التتبع عن بُعد المخصص الإضافي باستخدامTrackXXX()واجهة برمجة التطبيقات.
  • لديك سيطرة كاملة على التكوين.

هل يمكنني تمكين مراقبة Application Insights باستخدام أدوات مثل Azure Monitor Application Insights Agent (سابقًا Status Monitor v2)؟

نعم. في Application Insights Agent 2.0.0-beta1 والإصدارات الأحدث، يتم دعم تطبيقات ASP.NET Core المستضافة في IIS.

هل يتم دعم جميع الميزات إذا قمت بتشغيل تطبيقي في Linux؟

نعم. دعم الميزات لـSDK هو نفسه في جميع الأنظمة الأساسية، مع الاستثناءات التالية:

هل SDK هذا مدعوم لخدمات العامل؟

‏‏لا. يرجى استخدام Application Insights لتطبيقات خدمة العامل (تطبيقات غير HTTP) لخدمات العامل.

كيف يمكنني إلغاء تثبيت SDK؟

لإزالة Application Insights، تحتاج إلى إزالة حزم NuGet والمراجع من واجهة برمجة التطبيقات في التطبيق الخاص بك. يمكنك إلغاء تثبيت حزم NuGet باستخدام مدير الحِزَم NuGet في Visual Studio.

إشعار

هذه الإرشادات هي لإلغاء تثبيت ASP.NET Core SDK. إذا كنت بحاجة إلى إلغاء تثبيت ASP.NET SDK، فشاهد كيف يمكنني إلغاء تثبيت ASP.NET SDK؟.

  1. قم بإلغاء تثبيت حزمة Microsoft.ApplicationInsights.AspNetCore باستخدام مدير الحِزَم NuGet.
  2. لإزالة Application Insights بالكامل، تحقق من التعليمات البرمجية أو الملفات المضافة وحذفها يدويا مع أي استدعاءات واجهة برمجة التطبيقات التي أضفتها في مشروعك. لمزيد من المعلومات، راجع ما الذي يتم إنشاؤه عند إضافة Application Insights SDK؟.

ما الذي يتم إنشاؤه عند إضافة Application Insights SDK؟

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

عند إضافة بيانات تتبع الاستخدام الخاصة بـ Application Insights إلى مشروع قالب Visual Studio ASP.NET Core، فإنه يضيف التعليمة البرمجية التالية:

  • [اسم المشروع الخاص بك].csproj

      <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

  • Appsettings.json:

    "ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

  • ConnectedService.json

    {
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

  • Startup.cs

       public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

كيف يمكنني تعطيل ارتباط بيانات تتبع الاستخدام؟

لتعطيل ارتباط بيانات تتبع الاستخدام في التعليمات البرمجية، راجع <ExcludeComponentCorrelationHttpHeadersOnDomains> في Application Insights لتطبيقات وحدة التحكم.

استكشاف الأخطاء وإصلاحها

راجع «dedicated troubleshooting article».

اختبار الاتصال بين مضيف التطبيق وخدمة الاستيعاب

ترسل Application Insights SDKs والوكلاء بيانات تتبع الاستخدام للحصول على استيعابها كمكالمات REST إلى نقاط نهاية الاستيعاب الخاصة بنا. يمكنك اختبار الاتصال من خادم الويب أو الجهاز المضيف للتطبيق إلى نقاط نهاية خدمة الاستيعاب باستخدام عملاء REST الخام من أوامر PowerShell أو curl. راجع استكشاف أخطاء بيانات تتبع استخدام التطبيق المفقودة وإصلاحها في Azure Monitor Application Insights.

عدة تطوير البرامج SDK مفتوحة المصدر

قراءة الرمز والمساهمة فيه.

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

ملاحظات الإصدار

للحصول على الإصدار 2.12 وأحدث: .NET SDKs (بما في ذلك ASP.NET ASP.NET الذاكرة الأساسية ومحولات التسجيل)

كما تلخص تحديثات الخدمة تحسينات Application Insights الرئيسية.

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