مشاركة عبر

تكوين Application Insights SDK باستخدام ApplicationInsights.config أو .xml

  • مقالة

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

إشعار

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

تمت تسمية ApplicationInsights.config ملف التكوين أو ApplicationInsights.xml. يعتمد الاسم على نوع التطبيق الخاص بك. وتتم إضافته تلقائيًا إلى المشروع عند تثبيت معظم إصدارات SDK. بشكل افتراضي، عند استخدام التجربة التلقائية من مشاريع قالب Visual Studio التي تدعم Add>Application Insights Telemetry، ApplicationInsights.config يتم إنشاء الملف في المجلد الجذر للمشروع. عند تحويلها برمجيا، يتم نسخها إلى مجلد الحاوية. كما يتم إضافته إلى تطبيق ويب بواسطة Application Insights Agent على خادم IIS. يتم تجاهل ملف التكوين إذا تم استخدام ملحق مواقع Azure على الويب أو ملحق أجهزة Azure الظاهرية ومجموعات مقياس الجهاز الظاهري.

لا يوجد ملف مكافئ للتحكم في SDK في صفحة ويب.

توضح هذه المقالة الأقسام التي تراها في ملف التكوين، وكيفية التحكم في مكونات SDK، وحزم NuGet التي تقوم بتحميل هذه المكونات.

إشعار

ApplicationInsights.config لا تنطبق إرشادات .xml و على .NET Core SDK. لتكوين تطبيقات .NET Core، اتبع الإرشادات الواردة في Application Insights لتطبيقات ASP.NET Core.

وحدات القياس عن بعد (ASP.NET)

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

هناك عقدة في ملف التكوين لكل وحدة نمطية. لتعطيل وحدة نمطية، احذف العقدة أو قم بالتعليق بها.

تعقب التبعية

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

يمكنك أيضا كتابة التعليمات البرمجية لتعقب التبعية الخاصة بك باستخدام واجهة برمجة تطبيقات TrackDependency.

يمكن تجميع التبعيات تلقائيا دون تعديل التعليمات البرمجية الخاصة بك باستخدام إرفاق (بدون تعليمات برمجية) يستند إلى عامل. لاستخدامه في تطبيقات ويب Azure، قم بتمكين ملحق Application Insights. لاستخدامه في Azure VM أو مجموعة مقياس الجهاز الظاهري Azure، قم بتمكين ملحق مراقبة التطبيق للأجهزة الظاهرية ومجموعات مقياس الجهاز الظاهري.

جامع الأداء

يجمع مجمع الأداء عدادات أداء النظام، مثل وحدة المعالجة المركزية والذاكرة وتحميل الشبكة من عمليات تثبيت IIS. يمكنك تحديد العدادات التي يجب جمعها، بما في ذلك عدادات الأداء التي قمت بإعدادها بنفسك.

بيانات تتبع الاستخدام لتشخيص Application Insights

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

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • حزمة Microsoft.ApplicationInsights NuGet. إذا قمت بتثبيت هذه الحزمة فقط، فلن يتم إنشاء ملف ApplicationInsights.config تلقائيا.

وضع المطوّر

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

تعقب طلب ويب

يبلغ تعقب طلب الويب عن وقت الاستجابة ورمز النتيجة لطلبات HTTP.

تتبع الاستثناء

تتعقب ExceptionTrackingTelemetryModule الفئة الاستثناءات غير المعالجة في تطبيق الويب الخاص بك. لمزيد من المعلومات، راجع حالات الفشل والاستثناءات.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • حزمة Microsoft.ApplicationInsights.Web NuGet.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: تعقب المهمة غير المحجوزة. الاستثناءات.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: يتعقب الاستثناءات غير المعالجة لأدوار العاملين وخدمات Windows وتطبيقات وحدة التحكم.
  • حزمة Application Insights Windows Server NuGet.

تتبع EventSource

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

تعقب أحداث ETW

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

Microsoft.ApplicationInsights

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

  • لا يوجد إدخال في ApplicationInsights.config.
  • حزمة Microsoft.ApplicationInsights NuGet. إذا قمت بتثبيت NuGet هذا فقط، فلن يتم إنشاء أي ملف .config.

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

تدير قناة القياس عن بعد تخزين القياس عن بعد مؤقتًا وإرساله إلى خدمة Application Insights.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel هي القناة الافتراضية لتطبيقات الويب. فهو يخزن البيانات مؤقتا في الذاكرة ويستخدم آليات إعادة المحاولة وتخزين القرص المحلي لتسليم بيانات تتبع الاستخدام أكثر موثوقية.
  • Microsoft.ApplicationInsights.InMemoryChannel هي قناة بيانات تتبع الاستخدام خفيفة الوزن. يتم استخدامه إذا لم يتم تكوين قناة أخرى.

مهيئات بيانات تتبع الاستخدام (ASP.NET)

تقوم مهيئات بيانات تتبع الاستخدام بتعيين خصائص السياق التي يتم إرسالها مع كل عنصر من عناصر بيانات تتبع الاستخدام.

يمكنك كتابة المهايئ الخاص بك لتعيين خصائص السياق.

يتم تعيين جميع المهايئات القياسية إما بواسطة الويب أو حزم WindowsServer NuGet:

  • AccountIdTelemetryInitializer تعيين الخاصية AccountId .

  • AuthenticatedUserIdTelemetryInitializer تعيين الخاصية AuthenticatedUserId كما تم تعيينها بواسطة JavaScript SDK.

  • تقوم AzureRoleEnvironmentTelemetryInitializer بتحديث الخصائص RoleNameو RoleInstance للسياق Device لكافة عناصر القياس عن بعد باستخدام المعلومات المستخرجة من بيئة وقت التشغيل Azure.

  • تقوم BuildInfoConfigComponentVersionTelemetryInitializer بتحديث الخاصية Version للسياق Component لكافة عناصر القياس عن بعد باستخدام القيمة المستخرجة من الملف BuildInfo.config الذي تم إنتاجه بواسطة MS Build.

  • ClientIpHeaderTelemetryInitializerIp يحدث خاصية سياق Location جميع عناصر بيانات تتبع الاستخدام استنادا X-Forwarded-For إلى عنوان HTTP للطلب.

  • تقوم DeviceTelemetryInitializer بتحديث الخصائص التالية للسياق Device لكافة عناصر القياس عن بعد.

    • تم تعيين Type إلى PC.
    • يتم تعيين Id إلى اسم مجال الكمبيوتر حيث يتم تشغيل تطبيق ويب.
    • OemName يتم تعيين إلى القيمة المستخرجة Win32_ComputerSystem.Manufacturer من الحقل باستخدام WMI.
    • Model يتم تعيين إلى القيمة المستخرجة Win32_ComputerSystem.Model من الحقل باستخدام WMI.
    • NetworkType يتم تعيين إلى القيمة المستخرجة من الخاصية NetworkInterface .
    • Language يتم تعيين إلى اسم الخاصية CurrentCulture .

  • تقوم DomainNameRoleInstanceTelemetryInitializer بتحديث الخاصية RoleInstance للسياق Device لكافة عناصر القياس عن بعد باستخدام اسم مجال الكمبيوتر الذي يتم تشغيل تطبيق الويب فيه.

  • OperationNameTelemetryInitializerName يحدث خاصية RequestTelemetry وخاصية Name سياق Operation جميع عناصر بيانات تتبع الاستخدام استنادا إلى أسلوب HTTP وأسماء وحدة تحكم ASP.NET MVC والإجراء الذي تم استدعاؤه لمعالجة الطلب.

  • تقوم OperationIdTelemetryInitializer أو OperationCorrelationTelemetryInitializer بتحديث خاصية السياق Operation.Id لكافة عناصر القياس عن بعد التي يتم تعقبها أثناء معالجة طلب باستخدام RequestTelemetry.Id الذي تم إنشاؤه تلقائيًا.

  • SessionTelemetryInitializerId يحدث خاصية السياق لكافة Session عناصر بيانات تتبع الاستخدام ذات القيمة المستخرجة من ai_session ملف تعريف الارتباط الذي تم إنشاؤه بواسطة ApplicationInsights التعليمة البرمجية للأجهزة JavaScript التي تعمل في متصفح المستخدم.

  • SyntheticTelemetryInitializerأو SyntheticUserAgentTelemetryInitializer يحدث UserSessionخصائص السياق و و Operation لجميع عناصر بيانات تتبع الاستخدام التي يتم تعقبها عند معالجة طلب من مصدر اصطناعي، مثل اختبار التوفر أو روبوت محرك البحث. بشكل افتراضي، لا يعرض مستكشف المقاييس بيانات تتبع الاستخدام الاصطناعية.

    تقوم <Filters>بتعيين خصائص تعريف الطلبات.

  • UserTelemetryInitializerId يحدث خصائص و AcquisitionDate للسياق User لكافة عناصر بيانات تتبع الاستخدام مع القيم المستخرجة من ai_user ملف تعريف الارتباط الذي تم إنشاؤه بواسطة التعليمات البرمجية للأجهزة ل Application Insights JavaScript التي تعمل في متصفح المستخدم.

  • تقوم WebTestTelemetryInitializer بتعيين معرف المستخدم ومعرف الجلسة وخصائص المصدر الاصطناعي لطلبات HTTP التي تأتي من اختبارات التوفر. تقوم <Filters>بتعيين خصائص تعريف الطلبات.

بالنسبة لتطبيقات .NET التي تعمل في Azure Service Fabric، يمكنك تضمين حزمة Microsoft.ApplicationInsights.ServiceFabric NuGet. تتضمن هذه الحزمة خاصية FabricTelemetryInitializer ، والتي تضيف خصائص Service Fabric إلى عناصر بيانات تتبع الاستخدام. لمزيد من المعلومات، راجع صفحة GitHub حول الخصائص المضافة بواسطة حزمة NuGet هذه.

معالجات بيانات تتبع الاستخدام (ASP.NET)

يمكن لمعالجات بيانات تتبع الاستخدام تصفية كل عنصر بيانات تتبع الاستخدام وتعديله قبل إرساله من SDK إلى المدخل.

يمكنك كتابة معالجات بيانات تتبع الاستخدام الخاصة بك.

معالج القياس عن بعد لأخذ العينات التكيفية (من 2.0.0-beta3)

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


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

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

تعرف على المزيد حول أخذ العينات.

معالج بيانات تتبع الاستخدام لأخذ العينات بمعدل ثابت (من 2.0.0-beta1)

هناك أيضا معالج قياسي لبيانات تتبع الاستخدام لأخذ العينات (من 2.0.1):


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

سلسلة الاتصال

راجع نماذج التعليمات البرمجية سلسلة الاتصال.

مفتاح الأجهزة

إشعار

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

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

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

لتعيين المفتاح لكافة مثيلات ، بما في ذلك وحدات TelemetryClientالقياس عن بعد القياسية، قم بهذه الخطوة في أسلوب التهيئة، مثل global.aspx.cs في خدمة ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

إذا كنت ترغب في إرسال مجموعة محددة من الأحداث إلى مورد مختلف، يمكنك تعيين المفتاح لعميل بيانات تتبع الاستخدام المحدد:


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

للحصول على مفتاح جديد، قم بإنشاء مورد جديد في مدخل تطبيق Application Insights.

موفر ApplicationId

يتوفر الموفر بدءا من الإصدار 2.6.0.

الغرض من هذا الموفر هو البحث عن معرف تطبيق استنادا إلى مفتاح تقرير عن حالة النظام. يتم تضمين معرف التطبيق في RequestTelemetry DependencyTelemetry ويستخدم لتحديد الارتباط في المدخل.

تتوفر هذه الوظيفة عن طريق تعيين TelemetryConfiguration.ApplicationIdProvider إما في التعليمات البرمجية أو في ملف التكوين.

الواجهة: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

نحن نقدم تطبيقين في Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider و DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

برنامج التضمين هذا من أجل واجهة برمجة تطبيقات الملف التعريفي. وسيقوم بتنظيم الطلبات ونتائج ذاكرة التخزين المؤقت.

تتم إضافة هذا الموفر إلى ملف التكوين عند تثبيت Microsoft.ApplicationInsights.DependencyCollector أو Microsoft.ApplicationInsights.Web.

تحتوي هذه الفئة على خاصية اختيارية ProfileQueryEndpoint. بشكل افتراضي، يتم تعيينه إلى https://dc.services.visualstudio.com/api/profiles/{0}/appId. إذا كنت بحاجة إلى تكوين وكيل لهذا التكوين، نوصيك بوكيل العنوان الأساسي وتضمين "/api/profiles/{0}/appId". {0} يتم استبدال في وقت التشغيل لكل طلب بمفتاح تقرير عن حالة النظام.

مثال على التكوين عبر ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

مثال على التكوين عبر التعليمات البرمجية

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

يعتمد هذا الموفر الثابت على أزواج معرف مفتاح/تطبيق الأجهزة المكونة.

تحتوي هذه الفئة على الخاصية Defined ، وهي من Dictionary<string,string> أزواج معرف مفتاح تقرير عن حالة النظام / التطبيق.

تحتوي هذه الفئة على الخاصية Nextالاختيارية ، والتي يمكن استخدامها لتكوين موفر آخر لاستخدامه عند طلب مفتاح تقرير عن حالة النظام غير موجود في التكوين الخاص بك.

مثال على التكوين عبر ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

مثال على التكوين عبر التعليمات البرمجية

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

ضبط مجموعة لقطات لتطبيقات ASP.NET

تكوين مجموعة لقطة للتطبيقات ASP.NET.

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

تعرف على المزيد حول واجهة برمجة التطبيقات