تكوين 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.
تمت تسمية 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.
Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
- حزمة Microsoft.ApplicationInsights.DependencyCollector NuGet
يمكن تجميع التبعيات تلقائيا دون تعديل التعليمات البرمجية الخاصة بك باستخدام إرفاق (بدون تعليمات برمجية) يستند إلى عامل. لاستخدامه في تطبيقات ويب Azure، قم بتمكين ملحق Application Insights. لاستخدامه في Azure VM أو مجموعة مقياس الجهاز الظاهري Azure، قم بتمكين ملحق مراقبة التطبيق للأجهزة الظاهرية ومجموعات مقياس الجهاز الظاهري.
جامع الأداء
يجمع مجمع الأداء عدادات أداء النظام، مثل وحدة المعالجة المركزية والذاكرة وتحميل الشبكة من عمليات تثبيت IIS. يمكنك تحديد العدادات التي يجب جمعها، بما في ذلك عدادات الأداء التي قمت بإعدادها بنفسك.
Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
- حزمة Microsoft.ApplicationInsights.PerfCounterCollector NuGet
بيانات تتبع الاستخدام لتشخيص Application Insights
تبلغ DiagnosticsTelemetryModule
الفئة عن أخطاء في التعليمات البرمجية للأجهزة Application Insights نفسها. ومن الأمثلة على ذلك ما إذا كانت التعليمات البرمجية لا يمكنها الوصول إلى عدادات الأداء أو إذا ITelemetryInitializer
كانت تطرح استثناء. يظهر تتبع القياس عن بعد الذي تعقبته هذه الوحدة النمطية في البحث التشخيصي.
Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
- حزمة Microsoft.ApplicationInsights NuGet. إذا قمت بتثبيت هذه الحزمة فقط، فلن يتم إنشاء ملف ApplicationInsights.config تلقائيا.
وضع المطوّر
تجبر DeveloperModeWithDebuggerAttachedTelemetryModule
الفئة Application Insights TelemetryChannel
على إرسال البيانات على الفور، عنصر بيانات تتبع الاستخدام واحد في كل مرة، عند إرفاق مصحح أخطاء بعملية التطبيق. يقلل هذا التصميم من مقدار الوقت بين اللحظة التي يتعقب فيها تطبيقك بيانات تتبع الاستخدام ومتى يظهر في مدخل Application Insights. مما يؤدي إلى حمل كبير في وحدة المعالجة المركزية وعرض النطاق الترددي للشبكة.
Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
- حزمة Application Insights Windows Server NuGet
تعقب طلب ويب
يبلغ تعقب طلب الويب عن وقت الاستجابة ورمز النتيجة لطلبات HTTP.
Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
- حزمة Microsoft.ApplicationInsights.Web NuGet
تتبع الاستثناء
تتعقب 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.
Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
- Microsoft.ApplicationInsights.EventSourceListener
تعقب أحداث ETW
EtwCollectorTelemetryModule
تسمح لك الفئة بتكوين الأحداث من موفري ETW ليتم إرسالها إلى Application Insights كتتتبعات. للحصول على معلومات حول تعقب أحداث ETW، راجع استخدام أحداث ETW.
Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
- Microsoft.ApplicationInsights.EtwCollector
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.ClientIpHeaderTelemetryInitializer
Ip
يحدث خاصية سياق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
لكافة عناصر القياس عن بعد باستخدام اسم مجال الكمبيوتر الذي يتم تشغيل تطبيق الويب فيه.OperationNameTelemetryInitializer
Name
يحدث خاصيةRequestTelemetry
وخاصيةName
سياقOperation
جميع عناصر بيانات تتبع الاستخدام استنادا إلى أسلوب HTTP وأسماء وحدة تحكم ASP.NET MVC والإجراء الذي تم استدعاؤه لمعالجة الطلب.تقوم
OperationIdTelemetryInitializer
أوOperationCorrelationTelemetryInitializer
بتحديث خاصية السياقOperation.Id
لكافة عناصر القياس عن بعد التي يتم تعقبها أثناء معالجة طلب باستخدامRequestTelemetry.Id
الذي تم إنشاؤه تلقائيًا.SessionTelemetryInitializer
Id
يحدث خاصية السياق لكافةSession
عناصر بيانات تتبع الاستخدام ذات القيمة المستخرجة منai_session
ملف تعريف الارتباط الذي تم إنشاؤه بواسطةApplicationInsights
التعليمة البرمجية للأجهزة JavaScript التي تعمل في متصفح المستخدم.SyntheticTelemetryInitializer
أوSyntheticUserAgentTelemetryInitializer
يحدثUser
Session
خصائص السياق و وOperation
لجميع عناصر بيانات تتبع الاستخدام التي يتم تعقبها عند معالجة طلب من مصدر اصطناعي، مثل اختبار التوفر أو روبوت محرك البحث. بشكل افتراضي، لا يعرض مستكشف المقاييس بيانات تتبع الاستخدام الاصطناعية.تقوم
<Filters>
بتعيين خصائص تعريف الطلبات.UserTelemetryInitializer
Id
يحدث خصائص و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.
الخطوات التالية
الملاحظات
https://aka.ms/ContentUserFeedback.
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجعإرسال الملاحظات وعرضها المتعلقة بـ