مشاركة عبر

مراقبة تطبيقات .NET و Node.js باستخدام Application Insights (واجهة برمجة التطبيقات الكلاسيكية)

ملاحظة

راجع إرشادات دعم Application Insights SDK لنهج دعم SDK لواجهة برمجة التطبيقات الكلاسيكية.

أنذر

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

توضح هذه المقالة كيفية تمكين وتكوين Application Insights ل .NET (ASP.NET و ASP.NET Core وWorker Service) وتطبيقات Node.js. يمكن ل Application Insights جمع بيانات تتبع الاستخدام التالية من تطبيقاتك:

  • الطلبات
  • التبعيات
  • الاستثناءات
  • عدادات الأداء
  • تتبعات (سجلات)
  • رسائل كشف أخطاء الاتصال
  • الأحداث المخصصة والمقاييس (يتطلب تقرير عن حالة النظام يدويا)
  • طرق عرض الصفحة (تتطلب JavaScript SDK لصفحات الويب)
  • اختبارات التوفر (تتطلب إعداد اختبارات التوفر يدويا)

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

Supported ASP.NET ASP.NET Core خدمة العمال
نظام التشغيل Windows Windows أو Linux أو macOS Windows أو Linux أو macOS
أسلوب الاستضافة قيد المعالجة (IIS أو IIS Express) قيد المعالجة أو خارج العملية وحدة التحكم أو خدمة الخلفية (يتم تشغيلها كعملية، عادة عبر dotnet واجهة سطر الأوامر (CLI) أو كبرنامج خفي لخدمة Windows/Linux)
أسلوب التوزيع نشر ويب أو MSI أو نسخة ملف يدوية إطار العمل التابع أو المكتفي ذاتيا إطار العمل التابع أو المكتفي ذاتيا
خادم ويب خدمات معلومات الإنترنت (IIS) خادم معلومات الإنترنت (IIS) أو Kestrel غير قابل للتطبيق (لا يوجد خادم ويب؛ مصمم لأحمال العمل غير HTTP مثل المراسلة ومهام الخلفية وتطبيقات وحدة التحكم)
منصة الاستضافة Azure App Service (Windows) أو أجهزة Azure الظاهرية أو الخوادم المحلية ميزة تطبيقات الويب ل Azure App Service وAzure Virtual Machines وDocker وAzure Kubernetes Service (AKS) أجهزة Azure الظاهرية أو Azure Kubernetes Service (AKS) أو الحاويات أو أي بيئة يتم فيها دعم .NET Core
إصدار .NET .NET Framework 4.6.1 والإصدارات الأحدث جميع إصدارات .NET المدعومة رسميا والتي ليست قيد المعاينة جميع إصدارات .NET المدعومة رسميا والتي ليست قيد المعاينة
بيئة التطوير المتكامل Visual Studio Visual Studio أو Visual Studio Code أو سطر الأوامر Visual Studio أو Visual Studio Code أو سطر الأوامر

لا تقوم Worker Service SDK بأي مجموعة بيانات تتبع الاستخدام من تلقاء نفسها. بدلا من ذلك ، فإنه يجلب جامعي تلقائي Application Insights معروفين آخرين مثل DependencyCollector و PerfCounterCollector و ApplicationInsightsLoggingProvider. تعرض SDK هذه أساليب الملحق لتمكين IServiceCollection مجموعة بيانات تتبع الاستخدام وتكوينها.

ملاحظة

خدمة العامل هي تطبيق خلفية طويل الأمد ينفذ المهام خارج مسار طلب/استجابة HTTP. يمكن استخدام Application Insights SDK for Worker Service في .NET Core Worker Service التي تم تقديمها حديثا، ومهام الخلفية في ASP.NET Core، وتطبيقات وحدة التحكم مثل .NET Core و.NET Framework.

إضافة Application Insights

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

إنشاء تطبيق ويب أساسي

إذا لم يكن لديك تطبيق ويب يعمل حتى الآن ، فيمكنك استخدام الإرشادات التالية لإنشاء واحد.

ASP.NET

  1. افتح Visual Studio.
  2. حدد إنشاء مشروع جديد.
  3. اختر ASP.NET Web Application (.NET Framework) مع C#‎ وحدد Next.
  4. أدخل اسم المشروع، ثم حدد إنشاء.
  5. اختر MVC، ثم حدد إنشاء.

ASP.NET Core

  1. افتح Visual Studio.
  2. حدد إنشاء مشروع جديد.
  3. اختر ASP.NET Core Web App (Razor Pages) باستخدام C#‎ وحدد Next.
  4. أدخل اسم المشروع، ثم حدد إنشاء.
  5. اختر إطار عمل (LTS أو STS)، ثم حدد إنشاء.

إضافة Application Insights تلقائيا (Visual Studio)

يرشدك هذا القسم خلال إضافة Application Insights تلقائيا إلى تطبيق ويب يستند إلى قالب.

ASP.NET

ملاحظة

هناك مشكلة معروفة في Visual Studio 2019: يتم كسر تخزين مفتاح الأجهزة أو سلسلة الاتصال في سر المستخدم للتطبيقات المستندة إلى .NET Framework. في النهاية يجب ترميز المفتاح في ملف Applicationinsights.config للتغلب على هذا الخطأ.

من داخل مشروع تطبيق ويب ASP.NET في Visual Studio:

  1. حدِّد مشروع>إضافة بيانات تتبع الاستخدام لـ Application Insights>Application Insights Sdk (محلي)>ثم>إنهاء>إغلاق.

  2. افتح ملف ApplicationInsights.config.

  3. قبل إغلاق علامة </ApplicationInsights>، أضِف سطراً يحتوي على سلسلة الاتصال لمورد Application Insights. ابحث عن سلسلة الاتصال في جزء النظرة العامة لمورد Application Insights المنشأ حديثاً.

    <ConnectionString>Copy connection string from Application Insights Resource Overview</ConnectionString>

  4. حدِّد مشروع>تحديثات إدارة حزم>NuGet. ثم قم بتحديث كل Microsoft.ApplicationInsights حزمة NuGet إلى أحدث إصدار مستقر.

  5. تشغيل تطبيقك عن طريق تحديد IIS Express. يفتح تطبيق ASP.NET الأساسي. أثناء استعراض الصفحات على الموقع، يتم إرسال بيانات تتبع الاستخدام إلى Application Insights.

ASP.NET Core

ملاحظة

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

هام

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

من داخل مشروع تطبيق ويب ASP.NET في Visual Studio:

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

  2. حدد Azure Application Insights>Next.

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

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

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

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

إضافة Application Insights يدويا (بدون Visual Studio)

يرشدك هذا القسم من خلال إضافة Application Insights يدويا إلى تطبيق ويب يستند إلى قالب.

ASP.NET

  1. إضافة حزم NuGet التالية وتبعياتها إلى مشروعك:

  2. في بعض الحالات، يتم إنشاء ملف ApplicationInsights.config لك تلقائيًا. إذا كان الملف موجودًا بالفعل، انتقل إلى الخطوة رقم 4.

    أنشئه بنفسك إذا كان مفقودا. في الدليل الجذر للتطبيق ASP.NET، قم بإنشاء ملف جديد يسمى ApplicationInsights.config.

  3. انسخ تكوين XML التالي إلى الملف الذي تم إنشاؤه حديثًا:


    قم بالتوسيع لعرض التكوين 
    <?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
  <TelemetryInitializers>
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.HttpDependenciesParsingTelemetryInitializer, Microsoft.AI.DependencyCollector" />
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureRoleEnvironmentTelemetryInitializer, Microsoft.AI.WindowsServer" />
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.BuildInfoConfigComponentVersionTelemetryInitializer, Microsoft.AI.WindowsServer" />
    <Add Type="Microsoft.ApplicationInsights.Web.WebTestTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.SyntheticUserAgentTelemetryInitializer, Microsoft.AI.Web">
      <!-- Extended list of bots:
            search|spider|crawl|Bot|Monitor|BrowserMob|BingPreview|PagePeeker|WebThumb|URL2PNG|ZooShot|GomezA|Google SketchUp|Read Later|KTXN|KHTE|Keynote|Pingdom|AlwaysOn|zao|borg|oegp|silk|Xenu|zeal|NING|htdig|lycos|slurp|teoma|voila|yahoo|Sogou|CiBra|Nutch|Java|JNLP|Daumoa|Genieo|ichiro|larbin|pompos|Scrapy|snappy|speedy|vortex|favicon|indexer|Riddler|scooter|scraper|scrubby|WhatWeb|WinHTTP|voyager|archiver|Icarus6j|mogimogi|Netvibes|altavista|charlotte|findlinks|Retreiver|TLSProber|WordPress|wsr-agent|http client|Python-urllib|AppEngine-Google|semanticdiscovery|facebookexternalhit|web/snippet|Google-HTTP-Java-Client-->
      <Filters>search|spider|crawl|Bot|Monitor|AlwaysOn</Filters>
    </Add>
    <Add Type="Microsoft.ApplicationInsights.Web.ClientIpHeaderTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.AzureAppServiceRoleNameFromHostNameHeaderInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.OperationNameTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.OperationCorrelationTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.UserTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.AuthenticatedUserIdTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.AccountIdTelemetryInitializer, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.SessionTelemetryInitializer, Microsoft.AI.Web" />
  </TelemetryInitializers>
  <TelemetryModules>
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <ExcludeComponentCorrelationHttpHeadersOnDomains>
        <!-- 
        Requests to the following hostnames will not be modified by adding correlation headers.
        Add entries here to exclude additional hostnames.
        NOTE: this configuration will be lost upon NuGet upgrade.
        -->
        <Add>core.windows.net</Add>
        <Add>core.chinacloudapi.cn</Add>
        <Add>core.cloudapi.de</Add>
        <Add>core.usgovcloudapi.net</Add>
      </ExcludeComponentCorrelationHttpHeadersOnDomains>
      <IncludeDiagnosticSourceActivities>
        <Add>Microsoft.Azure.EventHubs</Add>
        <Add>Azure.Messaging.ServiceBus</Add>
      </IncludeDiagnosticSourceActivities>
    </Add>
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
      <!--
      Use the following syntax here to collect additional performance counters:

      <Counters>
        <Add PerformanceCounter="\Process(??APP_WIN32_PROC??)\Handle Count" ReportAs="Process handle count" />
        ...
      </Counters>

      PerformanceCounter must be either \CategoryName(InstanceName)\CounterName or \CategoryName\CounterName

      NOTE: performance counters configuration will be lost upon NuGet upgrade.

      The following placeholders are supported as InstanceName:
        ??APP_WIN32_PROC?? - instance name of the application process for Win32 counters.
        ??APP_W3SVC_PROC?? - instance name of the application IIS worker process for IIS/ASP.NET counters.
        ??APP_CLR_PROC?? - instance name of the application CLR process for .NET counters.
      -->
    </Add>
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector" />
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.AppServicesHeartbeatTelemetryModule, Microsoft.AI.WindowsServer" />
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureInstanceMetadataTelemetryModule, Microsoft.AI.WindowsServer">
      <!--
      Remove individual fields collected here by adding them to the ApplicationInsighs.HeartbeatProvider
      with the following syntax:

      <Add Type="Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule, Microsoft.ApplicationInsights">
        <ExcludedHeartbeatProperties>
          <Add>osType</Add>
          <Add>location</Add>
          <Add>name</Add>
          <Add>offer</Add>
          <Add>platformFaultDomain</Add>
          <Add>platformUpdateDomain</Add>
          <Add>publisher</Add>
          <Add>sku</Add>
          <Add>version</Add>
          <Add>vmId</Add>
          <Add>vmSize</Add>
          <Add>subscriptionId</Add>
          <Add>resourceGroupName</Add>
          <Add>placementGroupId</Add>
          <Add>tags</Add>
          <Add>vmScaleSetName</Add>
        </ExcludedHeartbeatProperties>
      </Add>

      NOTE: exclusions will be lost upon upgrade.
      -->
    </Add>
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule, Microsoft.AI.WindowsServer" />
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule, Microsoft.AI.WindowsServer" />
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule, Microsoft.AI.WindowsServer">
      <!--</Add>
    <Add Type="Microsoft.ApplicationInsights.WindowsServer.FirstChanceExceptionStatisticsTelemetryModule, Microsoft.AI.WindowsServer">-->
    </Add>
    <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web">
      <Handlers>
        <!-- 
        Add entries here to filter out additional handlers:

        NOTE: handler configuration will be lost upon NuGet upgrade.
        -->
        <Add>Microsoft.VisualStudio.Web.PageInspector.Runtime.Tracing.RequestDataHttpHandler</Add>
        <Add>System.Web.StaticFileHandler</Add>
        <Add>System.Web.Handlers.AssemblyResourceLoader</Add>
        <Add>System.Web.Optimization.BundleHandler</Add>
        <Add>System.Web.Script.Services.ScriptHandlerFactory</Add>
        <Add>System.Web.Handlers.TraceHandler</Add>
        <Add>System.Web.Services.Discovery.DiscoveryRequestHandler</Add>
        <Add>System.Web.HttpDebugHandler</Add>
      </Handlers>
    </Add>
    <Add Type="Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule, Microsoft.AI.Web" />
    <Add Type="Microsoft.ApplicationInsights.Web.AspNetDiagnosticTelemetryModule, Microsoft.AI.Web" />
  </TelemetryModules>
  <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
  <TelemetrySinks>
    <Add Name="default">
      <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryProcessor, Microsoft.AI.PerfCounterCollector" />
        <Add Type="Microsoft.ApplicationInsights.Extensibility.AutocollectedMetricsExtractor, Microsoft.ApplicationInsights" />
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
          <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
          <ExcludedTypes>Event</ExcludedTypes>
        </Add>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
          <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
          <IncludedTypes>Event</IncludedTypes>
        </Add>
        <!--
          Adjust the include and exclude examples to specify the desired semicolon-delimited types. (Dependency, Event, Exception, PageView, Request, Trace)
        -->
      </TelemetryProcessors>
      <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel" />
    </Add>
  </TelemetrySinks>
  <!-- 
    Learn more about Application Insights configuration with ApplicationInsights.config here:
    http://go.microsoft.com/fwlink/?LinkID=513840
  -->
  <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
</ApplicationInsights>

  4. أضف سلسلة الاتصال، والتي يمكن إجراؤها بطريقتين:

    • (مستحسن) تعيين سلسلة الاتصال في التكوين.

      قبل علامة الإغلاق </ApplicationInsights> في ApplicationInsights.config، أضف سلسلة الاتصال لمورد Application Insights. ابحث عن سلسلة الاتصال في جزء النظرة العامة لمورد Application Insights الذي تم إنشاؤه حديثاً.

      <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>

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

      قم بتوفير سلسلة الاتصال في فئة program.cs.

      var configuration = new TelemetryConfiguration
{
    ConnectionString = "Copy the connection string from your Application Insights resource"
};

  5. في المستوى نفسه في مشروعك كملف ApplicationInsights.config، أنشئ مجلد يسمى ErrorHandler مع ملف C# جديد يسمى AiHandleErrorAttribute.cs. تبدو محتويات الملف كما يلي:

    using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace WebApplication10.ErrorHandler //namespace will vary based on your project name
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)] 
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //If customError is Off, then AI HTTPModule will report the exception
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                } 
            }
            base.OnException(filterContext);
        }
    }
}

  6. في المجلد App_Start، افتح ملف FilterConfig.cs وأدخِل تغييرات عليه لمطابقة النموذج:

    using System.Web;
using System.Web.Mvc;

namespace WebApplication10 //Namespace will vary based on project name
{
    public class FilterConfig
    {
        public static void RegisterGlobalFilters(GlobalFilterCollection filters)
        {
            filters.Add(new ErrorHandler.AiHandleErrorAttribute());
        }
    }
}

  7. إذا تم تحديث Web.config بالفعل، فتخطى هذه الخطوة. غير ذلك، قم بتحديث الملف كما يلي:


    قم بالتوسيع لعرض التكوين 
    <?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, please visit
  https://go.microsoft.com/fwlink/?LinkId=301880
  -->
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
  </appSettings>
  <system.web>
    <compilation debug="true" targetFramework="4.7.2" />
    <httpRuntime targetFramework="4.7.2" />
    <!-- Code added for Application Insights start -->
    <httpModules>
      <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" />
      <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
    </httpModules>
    <!-- Code added for Application Insights end -->
  </system.web>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="Antlr3.Runtime" publicKeyToken="eb42632606e9261f" />
        <bindingRedirect oldVersion="0.0.0.0-3.5.0.2" newVersion="3.5.0.2" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" />
        <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="System.Web.Optimization" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="1.1.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="0.0.0.0-1.6.5135.21930" newVersion="1.6.5135.21930" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="1.0.0.0-5.2.7.0" newVersion="5.2.7.0" />
      </dependentAssembly>
      <!-- Code added for Application Insights start -->
      <dependentAssembly>
        <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-4.0.1.1" newVersion="4.0.1.1" />
      </dependentAssembly>
      <!-- Code added for Application Insights end -->
    </assemblyBinding>
  </runtime>
  <system.codedom>
    <compilers>
      <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:1659;1699;1701" />
      <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+" />
    </compilers>
  </system.codedom>
  <system.webServer>
    <validation validateIntegratedModeConfiguration="false" />
    <!-- Code added for Application Insights start -->
    <modules>
      <remove name="TelemetryCorrelationHttpModule" />
      <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" preCondition="managedHandler" />
      <remove name="ApplicationInsightsWebTracking" />
      <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
    </modules>
    <!-- Code added for Application Insights end -->
  </system.webServer>
</configuration>

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

ASP.NET Core

  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 .

    أضف builder.Services.AddApplicationInsightsTelemetry(); بعد WebApplication.CreateBuilder() الأسلوب ، كما في هذا المثال:

    // 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. أضف سلسلة الاتصال، والذي يمكن القيام به بثلاث طرق:

    • (مستحسن) تعيين سلسلة الاتصال في التكوين.

      قم بتعيين سلسلة الاتصال في appsettings.json وتأكد من نسخ ملف التكوين إلى مجلد جذر التطبيق أثناء النشر.

      {
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "ApplicationInsights": {
        "ConnectionString": "<YOUR-CONNECTION-STRING>"
    }
}

    • تعيين سلسلة الاتصال في 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البيئة ، والذي يفوز على الخيارات الأخرى.

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

      قم بتوفير سلسلة الاتصال كجزء من الوسيطة ApplicationInsightsServiceOptions إلى AddApplicationInsightsTelemetry في فئة program.cs.

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

إذا كنت ترغب في تخزين سلسلة الاتصال في بيانات مستخدم 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 SDK لخدمة العامل

  1. قم بتثبيت حزمة Microsoft.ApplicationInsights.WorkerService على التطبيق.

    يعرض المقتطف التالي التغييرات التي يجب إضافتها إلى ملف مشروعك .csproj :

        <ItemGroup>
        <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    </ItemGroup>

  2. قم بتكوين سلسلة الاتصال في APPLICATIONINSIGHTS_CONNECTION_STRING متغير البيئة أو في التكوين (appsettings.json).

    لقطة شاشة تعرض نظرة عامة على Application Insights وسلسلة الاتصال.

  3. استرجع ILogger مثيلا أو TelemetryClient مثيلا من حاوية حقن التبعية (DI) عن طريق استدعاء serviceProvider.GetRequiredService<TelemetryClient>(); حقن المنشئ أو استخدامه. تؤدي هذه الخطوة إلى TelemetryConfiguration إعداد الوحدات النمطية والتجميع التلقائي.

يتم وصف تعليمات محددة لكل نوع من التطبيقات في الأقسام التالية.

تطبيق .NET Core Worker Service

تمت مشاركة المثال الكامل على موقع NuGet.

  1. قم بتنزيل .NET SDK وتثبيته.

  2. قم بإنشاء مشروع Worker Service جديد إما باستخدام قالب مشروع جديد في Visual Studio أو سطر dotnet new workerالأوامر .

  3. أضف حزمة Microsoft.ApplicationInsights.WorkerService إلى التطبيق.

  4. أضف services.AddApplicationInsightsTelemetryWorkerService(); إلى الطريقة CreateHostBuilder() في الفصل الدراسي الخاص بك Program.cs ، كما في هذا المثال:

        public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
                services.AddApplicationInsightsTelemetryWorkerService();
            });

  5. قم بتعديل الخاص بك Worker.cs وفقا للمثال التالي:

        using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;

    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;
        private static HttpClient _httpClient = new HttpClient();

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

                using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
                {
                    _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                    _logger.LogInformation("Calling bing.com");
                    var res = await _httpClient.GetAsync("https://bing.com");
                    _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                    _telemetryClient.TrackEvent("Bing call event completed");
                }

                await Task.Delay(1000, stoppingToken);
            }
        }
    }

  6. قم بإعداد سلسلة الاتصال.

    لقطة شاشة تعرض نظرة عامة على Application Insights وسلسلة الاتصال.

    ملاحظة

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

        {
        "ApplicationInsights":
        {
            "ConnectionString" : "<YOUR-CONNECTION-STRING>"
        },
        "Logging":
        {
            "LogLevel":
            {
                "Default": "Warning"
            }
        }
    }

بدلا من ذلك، حدد سلسلة الاتصال في APPLICATIONINSIGHTS_CONNECTION_STRING متغير البيئة.

عادة ما APPLICATIONINSIGHTS_CONNECTION_STRING يحدد سلسلة الاتصال للتطبيقات المنشورة في تطبيقات الويب كمهام ويب.

ملاحظة

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

ASP.NET مهام الخلفية الأساسية مع الخدمات المستضافة

يصف هذا المستند كيفية إنشاء مهام خلفية في تطبيق ASP.NET Core.

تتم مشاركة المثال الكامل في صفحة GitHub هذه.

  1. قم بتثبيت حزمة Microsoft.ApplicationInsights.WorkerService على التطبيق.

  2. أضف services.AddApplicationInsightsTelemetryWorkerService(); إلى ConfigureServices() الطريقة، كما في هذا المثال:

        public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .ConfigureAppConfiguration((hostContext, config) =>
            {
                config.AddJsonFile("appsettings.json", optional: true);
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddLogging();
                services.AddHostedService<TimedHostedService>();

                // connection string is read automatically from appsettings.json
                services.AddApplicationInsightsTelemetryWorkerService();
            })
            .UseConsoleLifetime()
            .Build();

        using (host)
        {
            // Start the host
            await host.StartAsync();

            // Wait for the host to shutdown
            await host.WaitForShutdownAsync();
        }
    }

    التعليمات البرمجية التالية ل TimedHostedService، حيث يوجد منطق مهمة الخلفية:

        using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;

    public class TimedHostedService : IHostedService, IDisposable
    {
        private readonly ILogger _logger;
        private Timer _timer;
        private TelemetryClient _telemetryClient;
        private static HttpClient httpClient = new HttpClient();

        public TimedHostedService(ILogger<TimedHostedService> logger, TelemetryClient tc)
        {
            _logger = logger;
            this._telemetryClient = tc;
        }

        public Task StartAsync(CancellationToken cancellationToken)
        {
            _logger.LogInformation("Timed Background Service is starting.");

            _timer = new Timer(DoWork, null, TimeSpan.Zero,
                TimeSpan.FromSeconds(1));

            return Task.CompletedTask;
        }

        private void DoWork(object state)
        {
            _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

            using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
            {
                _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                _logger.LogInformation("Calling bing.com");
                var res = httpClient.GetAsync("https://bing.com").GetAwaiter().GetResult();
                _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                _telemetryClient.TrackEvent("Bing call event completed");
            }
        }
    }

  3. قم بإعداد سلسلة الاتصال. استخدم نفس appsettings.json الشيء من مثال .NET Worker Service السابق.

تطبيق وحدة تحكم .NET Core/.NET Framework

كما هو مذكور في بداية هذه المقالة، يمكن استخدام الحزمة الجديدة لتمكين بيانات تتبع الاستخدام ل Application Insights حتى من تطبيق وحدة تحكم عادي. تستهدف netstandard2.0هذه الحزمة ، بحيث يمكن استخدامها لتطبيقات وحدة التحكم في .NET Core أو أعلى ، و .NET Framework أو أعلى.

تتم مشاركة المثال الكامل في صفحة GitHub هذه.

  1. قم بتثبيت حزمة Microsoft.ApplicationInsights.WorkerService على التطبيق.

  2. قم بتعديل Program.cs كما هو موضح في المثال التالي:

        using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;
    using Microsoft.ApplicationInsights.WorkerService;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Logging;
    using System;
    using System.Net.Http;
    using System.Threading.Tasks;

    namespace WorkerSDKOnConsole
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                // Create the DI container.
                IServiceCollection services = new ServiceCollection();

                // Being a regular console app, there is no appsettings.json or configuration providers enabled by default.
                // Hence connection string and any changes to default logging level must be specified here.
                services.AddLogging(loggingBuilder => loggingBuilder.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("Category", LogLevel.Information));
                services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = "<YOUR-CONNECTION-STRING>");

                // To pass a connection string
                // - aiserviceoptions must be created
                // - set connectionstring on it
                // - pass it to AddApplicationInsightsTelemetryWorkerService()

                // Build ServiceProvider.
                IServiceProvider serviceProvider = services.BuildServiceProvider();

                // Obtain logger instance from DI.
                ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

                // Obtain TelemetryClient instance from DI, for additional manual tracking or to flush.
                var telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

                var httpClient = new HttpClient();

                while (true) // This app runs indefinitely. Replace with actual application termination logic.
                {
                    logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

                    // Replace with a name which makes sense for this operation.
                    using (telemetryClient.StartOperation<RequestTelemetry>("operation"))
                    {
                        logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                        logger.LogInformation("Calling bing.com");                    
                        var res = await httpClient.GetAsync("https://bing.com");
                        logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                        telemetryClient.TrackEvent("Bing call event completed");
                    }

                    await Task.Delay(1000);
                }

                // Explicitly call Flush() followed by sleep is required in console apps.
                // This is to ensure that even if application terminates, telemetry is sent to the back-end.
                telemetryClient.Flush();
                Task.Delay(5000).Wait();
            }
        }
    }

يستخدم تطبيق وحدة التحكم هذا أيضا نفس الافتراضي TelemetryConfiguration. يمكن تخصيصه بنفس طريقة الأمثلة الواردة في الأقسام السابقة.

التحقق من تلقي Application Insights للقياس عن بعد

ASP.NET & ASP.NET الأساسية

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

خدمة العمال

قم بتشغيل التطبيق الخاص بك. يقوم العمال من جميع الأمثلة السابقة بإجراء مكالمة HTTP كل ثانية إلى bing.com ويصدرون أيضا بعض السجلات باستخدام ILogger. يتم تغليف هذه الأسطر داخل استدعاء StartOperation ، TelemetryClientوالذي يستخدم لإنشاء عملية. في هذا المثال، RequestTelemetry يسمى "العملية".

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

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

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

جمع بيانات بيانات القياس عن بعد

في هذا القسم

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

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

ملاحظة

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

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

ASP.NET

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

  1. تثبيت حزمة NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

  2. يظهر نموذج التعليمات البرمجية لتطبيق وحدة التحكم التالي إعداد مقاييس مباشرة:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a TelemetryConfiguration instance.
            TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
            config.ConnectionString = "<YOUR-CONNECTION-STRING>";
            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>";
            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();
            }
        }
    }
}
ASP.NET Core

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

  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.ConnectionString = "<YOUR-CONNECTION-STRING>";
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>";
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.

هام

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

ملاحظة

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

خدمة العمال

يتم التقاط السجلات المنبعثة ILogger مع تحذير الخطورة أو أعلى تلقائيا. لتغيير هذا السلوك، تجاوز بشكل صريح تكوين التسجيل للموفر ApplicationInsights، كما هو موضح في التعليمات البرمجية التالية. يسمح التكوين التالي ل Application Insights بالتقاط جميع Information السجلات والسجلات الأكثر خطورة.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

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

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

ملاحظة

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

لمزيد من المعلومات، اتبع مستندات ILogger لتخصيص مستويات السجل التي يتم التقاطها بواسطة Application Insights.

الآثار (السجلات)

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

يمكنك استخدام سجلات التتبع لتحديد التتبعات المرتبطة بكل طلب مستخدم وربطها بالأحداث الأخرى وتقارير الاستثناءات.

يلتقط Application Insights السجلات من ASP.NET Core وتطبيقات .NET الأخرى من خلال ILogger، ومن ASP.NET الكلاسيكي (.NET Framework) من خلال SDK الكلاسيكي والمحولات.

ملاحظة

  • بشكل افتراضي، يرسل موفر Application Insights سجلات بخطورة Warning أو أعلى. لتضمين Information السجلات أو السجلات ذات المستوى الأدنى، قم بتحديث إعدادات مستوى السجل في appsettings.json.

  • Microsoft.ApplicationInsights.WorkerService حزمة NuGet، المستخدمة لتمكين Application Insights لخدمات الخلفية، خارج النطاق.

  • لمراجعة الأسئلة المتداولة (FAQ)، راجع الأسئلة المتداولة حول التسجيل باستخدام .NET.

تثبيت تسجيل الدخول على تطبيقك

ASP.NET

اختر أسلوب تسجيل لإصدار سجلات التشخيص التي يمكن ل Application Insights جمعها.

بالنسبة لتطبيقات ASP.NET الكلاسيكية التي تستخدم تتبع System.Diagnostics ، قم بتكوين Application Insights TraceListener في التكوين.

إضافة مستمع إلى web.config أو app.config:

<configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener"
             type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

ملاحظة

تعد وحدة التقاط السجل محولا مفيدا لمسجلي الطرف الثالث. ومع ذلك، إذا لم تكن تستخدم NLog أو log4Net أو System.Diagnostics.Trace، ففكر في استدعاء Application Insights TrackTrace() مباشرة.

تكوين Application Insights لتجميع السجلات

الخيار 1: أضف Application Insights إلى مشروعك إذا لم تكن قد قمت بذلك بالفعل. عند إضافة Application Insights في Visual Studio، هناك خيار لتضمين جامع السجل.

الخيار 2: انقر بزر الماوس الأيمن فوق مشروعك في مستكشف الحلول لتكوين Application Insights. حدد الخيار تكوين مجموعة التتبع .

ملاحظة

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

ASP.NET Core

يقوم Application Insights SDK ل ASP.NET Core بالفعل بتجميع سجلات ILogger افتراضيا. إذا كنت تستخدم SDK، فلن تحتاج عادة إلى الاتصال builder.Logging.AddApplicationInsights() أيضا ويمكنك تجاهل تعليمات تثبيت ILogger التالية.

إذا كنت تحتاج فقط إلى إعادة توجيه السجل وليس مكدس بيانات تتبع الاستخدام الكامل، فيمكنك استخدام Microsoft.Extensions.Logging.ApplicationInsights حزمة الموفر لالتقاط السجلات.

التثبيت اليدوي

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

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

  2. ابحث عن Application Insights.

  3. حدد إحدى الباقات التالية:

تقوم حزمة NuGet بتثبيت التجميعات الضرورية وتعديل web.config أو app.config، إن أمكن.

تعليمات التثبيت:

ملاحظة

قم بتوسيع أي من الأقسام أدناه للحصول على إرشادات التثبيت الخاصة بالحزمة


لوغر

  1. قم بتثبيت ملف Microsoft.Extensions.Logging.ApplicationInsights.

  2. إضافة ApplicationInsightsLoggerProvider:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

ضع في اعتبارك مثال وحدة التحكم التالية:

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _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 الذي يتم إنتاجه من سجلات ILogger؟ أين يمكنني رؤية سجلات ILogger في Application Insights؟.

إدراج استدعاءات سجل التشخيص (System.Diagnostics.Trace / log4net / NLog)

إذا كنت تستخدم System.Diagnostics.Trace، فستكون المكالمة النموذجية:

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

إذا كنت تفضل log4net أو NLog، استخدم:

    logger.Warn("Slow response - database01");
استخدام أحداث EventSource

يمكنك تكوين أحداث System.Diagnostics.Tracing.EventSource ليتم إرسالها إلى Application Insights كآثار.

  1. قم بتثبيت Microsoft.ApplicationInsights.EventSourceListener حزمة NuGet.

  2. قم بتحرير TelemetryModules قسم ملف ApplicationInsights.config :

        <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

لكل مصدر، يمكنك تعيين المعلمات التالية:

  • يحدد الاسم اسم EventSource المراد تجميعه.
  • يحدد المستوى مستوى التسجيل المراد تجميعه: حرج أو خطأ أو معلوماتي أو LogAlways أو مطول أو تحذير.
  • تحدد الكلمات الرئيسية (اختيارية) القيمة الصحيحة لمجموعات الكلمات الرئيسية المراد استخدامها.
استخدام أحداث DiagnosticSource

يمكنك تكوين أحداث System.Diagnostics.DiagnosticSource لإرسالها إلى Application Insights كتتبعات.

  1. قم بتثبيت Microsoft.ApplicationInsights.DiagnosticSourceListener حزمة NuGet.

  2. قم بتحرير TelemetryModules قسم ملف ApplicationInsights.config :

        <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

لكل مصدر تشخيصي تريد تتبعه، أضف إدخالا مع Name تعيين السمة إلى اسم مصدر التشخيص.

استخدام أحداث ETW

يمكنك تكوين أحداث تتبع الأحداث ل Windows (ETW) لإرسالها إلى Application Insights كتتبعات.

  1. قم بتثبيت Microsoft.ApplicationInsights.EtwCollector حزمة NuGet.

  2. قم بتحرير قسم "TelemetryModules" في ملف ApplicationInsights.config :

ملاحظة

لا يمكن جمع أحداث ETW إلا إذا كانت العملية التي تستضيف SDK تعمل تحت هوية عضو في مستخدمي سجل الأداء أو المسؤولين.

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

لكل مصدر، يمكنك تعيين المعلمات التالية:

  • ProviderName هو اسم موفر ETW المراد جمعه.
  • يحدد ProviderGuid المعرف الفريد العمومي لموفر ETW الذي يجب تجميعه. يمكن استخدامه بدلا من ProviderName.
  • يحدد المستوى مستوى التسجيل المطلوب تجميعه. يمكن أن يكون حرجا أو خطأ أو إعلاميا أو LogAlways أو مطولا أو تحذيرا.
  • تحدد الكلمات الرئيسية (اختيارية) قيمة العدد الصحيح لمجموعات الكلمات الرئيسية المراد استخدامها.
استخدام واجهة برمجة تطبيقات التتبع مباشرة

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

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

ميزة ذلك TrackTrace هي أنه يمكنك وضع بيانات طويلة نسبيا في الرسالة. على سبيل المثال ، يمكنك تشفير بيانات POST هناك.

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

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

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

تطبيق وحدة التحكم

لإضافة تسجيل Application Insights إلى تطبيقات وحدة التحكم، قم أولا بتثبيت حزم NuGet التالية:

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

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

لمزيد من المعلومات، راجع ما هو نوع القياس عن بعد ل Application Insights الذي يتم إنتاجه من سجلات ILogger؟ أين يمكنني رؤية سجلات ILogger في Application Insights؟.

نطاقات التسجيل

ملاحظة

تنطبق الإرشادات التالية على سيناريوهات ILogger (ASP.NET Core ووحدة التحكم فقط). لا ينطبق على ASP.NET الكلاسيكية.

ApplicationInsightsLoggingProvider يدعم نطاقات السجل ، والتي يتم تمكينها افتراضيا.

إذا كان النطاق من النوع IReadOnlyCollection<KeyValuePair<string,object>>، إضافة كل زوج مفتاح/قيمة في المجموعة إلى بيانات تتبع الاستخدام Application Insights كخصائص مخصصة. في المثال التالي، يتم التقاط السجلات كما TraceTelemetry ولها ("MyKey", "MyValue") في الخصائص.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

إذا تم استخدام أي نوع آخر كنطاق، تخزينه ضمن الخاصية Scope في القياس عن بعد ل Application Insights. في المثال التالي، TraceTelemetry يحتوي على خاصية تسمى Scope تحتوي على النطاق.

using (_logger.BeginScope("hello scope"))
{
    _logger.LogError("An example of an Error level message");
}

ابحث عن سجلاتك

قم بتشغيل تطبيقك في وضع تصحيح الأخطاء أو نشره مباشرة.

في جزء نظرة عامة على تطبيقك في مدخل Application Insights، حدد البحث عن المعاملات حيث يمكنك:

  • التصفية بناء على تتبعات السجل أو العناصر ذات الخصائص المحددة.
  • افحص عنصرا معينا بالتفصيل.
  • ابحث عن بيانات سجل النظام الأخرى التي تتعلق بطلب المستخدم نفسه (لها نفس معرف العملية).
  • احفظ تكوين الصفحة كمفضلة.

ملاحظة

إذا كان تطبيقك يرسل كميات كبيرة من البيانات وكنت تستخدم Application Insights SDK للإصدار 2.0.0-beta3 ASP.NET أو أحدث، فقد تعمل ميزة أخذ العينات التكيفية وترسل جزءا فقط من بيانات تتبع الاستخدام الخاصة بك. تعرف على مزيد من المعلومات عن أخذ العينات.

استكشاف في سجلات Azure Monitor

تظهر سجلات ILogger كتتبع تتبع الاستخدام (جدول traces في Application Insights وفي AppTraces Log Analytics).

مثال

في مدخل Microsoft Azure، انتقل إلى Application Insights وقم بتشغيل:

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

تتبع موزع

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

يوفر Azure Monitor تجربتين لاستهلاك بيانات التتبع الموزعة: طريقة عرض تشخيص المعاملات لمعاملة/طلب واحد وطريقة عرض خريطة التطبيق لإظهار كيفية تفاعل الأنظمة.

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

تمكين التتبع الموزع عبر Application Insights من خلال الأجهزة التلقائية أو SDKs

تدعم وكلاء Application Insights وSDKs ل .NET و.NET Core وJava وNode.jsوJavaScript التتبع الموزع أصلا.

مع تثبيت Application Insights SDK المناسبة وتكوينها، يتم جمع معلومات التتبع تلقائيا لأطر العمل والمكتبات والتقنيات الشائعة بواسطة المجمعات التلقائية لتبعية SDK. تتوفر القائمة الكاملة للتقنيات المدعومة في وثائق التجميع التلقائي للتبعية.

يمكن أيضا تتبع أي تقنية يدويا من خلال استدعاء TrackDependency على TelemetryClient.

نموذج بيانات ارتباط القياس عن بعد

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

تتكون العملية المنطقية الموزعة عادة من مجموعة من العمليات الأصغر التي تتم معالجتها بواسطة أحد المكونات. يحدد طلب بيانات تتبع الاستخدام هذه العمليات. كل عنصر للقياس عن بعد للطلب له خاصه id الذي يحدده بشكل فريد وعالمي. ويجب أن تقوم جميع عناصر بيانات تتبع الاستخدام (مثل التتبعات والاستثناءات) المقترنة بالطلب بتعيين قيمة operation_parentId الطلب id.

يمثل قياس تتبع الاستخدام للتبعية كل عملية صادرة، مثل استدعاء HTTP لمكون آخر. كما أنه يحدد فريدا id من نوعه عالميا. يستخدم طلب بيانات تتبع الاستخدام، الذي بدأه استدعاء التبعية هذا، هذا id كملف operation_parentId.

يمكنك إنشاء طريقة عرض للعملية المنطقية الموزعة باستخدام operation_Id، ، وباستخدام operation_parentIdrequest.iddependency.id. تحدد هذه الحقول أيضا ترتيب السببية لمكالمات القياس عن بعد.

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

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

للحصول على معلومات حول الاستعلام من مثيلات متباينة متعددة، راجع الاستعلام عن البيانات عبر مساحات عمل Log Analytics وتطبيقاتها ومواردها في Azure Monitor.

مثال

هيا بنا نلقي نظرة على مثال. يعرض تطبيق يسمى أسعار الأسهم سعر السوق الحالي للسهم باستخدام واجهة برمجة تطبيقات خارجية تسمى الأسهم. يحتوي تطبيق أسعار الأسهم على صفحة تسمى صفحة الأسهم التي يفتحها مستعرض الويب للعميل باستخدام GET /Home/Stock. يستعلم التطبيق عن واجهة برمجة تطبيقات المخزون باستخدام استدعاء GET /api/stock/valueHTTP .

يمكنك تحليل بيانات تتبع الاستخدام الناتجة عن طريق تشغيل استعلام:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

في النتائج، تشترك جميع عناصر بيانات تتبع الاستخدام في جذر operation_Id. عند إجراء مكالمة Ajax من الصفحة، يتم تعيين معرف فريد جديد (qJSXU) لبيانات تتبع الاستخدام للتبعية، ويتم استخدام معرف pageView ك operation_ParentId. يستخدم طلب الخادم بعد ذلك معرف Ajax ك operation_ParentId.

نوع العنصر name المعرف operation_ParentId operation_Id
عرض الصفحة صفحة الأسهم STYz STYz
تبعية احصل على /الصفحة الرئيسية/المخزون qJSXU STYz STYz
request احصل على المنزل / المخزون KqKwlrSt9PA= qJSXU STYz
تبعية احصل على /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

عند إجراء المكالمة GET /api/stock/value إلى خدمة خارجية، تحتاج إلى معرفة هوية هذا الخادم حتى تتمكن من تعيين الحقل dependency.target بشكل مناسب. عندما لا تدعم الخدمة الخارجية المراقبة، target يتم تعيينها إلى اسم مضيف الخدمة. مثال على ذلك stock-prices-api.com . ولكن إذا عرفت الخدمة نفسها عن طريق إرجاع رأس HTTP محدد مسبقا، target تحتوي على هوية الخدمة التي تسمح ل Application Insights بإنشاء تتبع موزع عن طريق الاستعلام عن بيانات تتبع الاستخدام من تلك الخدمة.

رؤوس الارتباط باستخدام W3C TraceContext

ينتقل Application Insights إلى W3C Trace-Context، والذي يحدد:

  • traceparentيحمل معرف العملية الفريد عالميا والمعرف الفريد للمكالمة.:
  • tracestateيحمل سياق تتبع خاص بالنظام.:

يدعم أحدث إصدار من Application Insights SDK بروتوكول Trace-Context، ولكن قد تحتاج إلى الاشتراك فيه. (يتم الحفاظ على التوافق مع الإصدارات السابقة مع بروتوكول الارتباط السابق المدعوم من قبل Application Insights SDK.)

يتم إهمال بروتوكول HTTP للارتباط، والذي يسمى أيضا Request-Id. يحدد هذا البروتوكول عنوانين:

  • Request-Idيحمل المعرف الفريد عالميا للمكالمة.:
  • Correlation-Contextيحمل مجموعة أزواج الاسم والقيمة لخصائص التتبع الموزعة.:

يحدد Application Insights أيضا الملحق لبروتوكول HTTP الارتباطي. يستخدم Request-Context أزواج الاسم والقيمة لنشر مجموعة الخصائص التي يستخدمها المتصل المباشر أو المتصل. تستخدم Application Insights SDK هذا العنوان لتعيين dependency.target الحقول و request.source .

يتم تعيين نماذج بيانات W3C Trace-Context وApplication Insights بالطريقة التالية:

Application Insights W3C تتبع السياق
Id من Request و Dependency معرف الوالدين
Operation_Id معرف التتبع
Operation_ParentId معرف الأصل للامتداد الأصلي لهذه الامتداد. يجب أن يكون هذا الحقل فارغا إذا كان امتداد الجذر.

لمزيد من المعلومات، راجع نموذج بيانات بيانات تتبع الاستخدام في Application Insights.

تمكين دعم التتبع الموزع W3C

يتم تمكين التتبع الموزع المستند إلى W3C TraceContext بشكل افتراضي في جميع حزم تطوير البرامج (SDK) الحديثة ل .NET Framework/.NET Core، إلى جانب التوافق مع الإصدارات السابقة مع البروتوكول القديم Request-Id .

ارتباط القياس عن بعد

تتم معالجة الارتباط افتراضيا عند إلحاق أحد التطبيقات. لا توجد إجراءات خاصة مطلوبة.

دعم وقت تشغيل .NET الموزع بمساعدة النشاطوDiagnosticSource

يستخدم DiagnosticSource Application Insights .NET SDK وجمع Activity بيانات تتبع الاستخدام وربطها.

التبعيات

التبعيات المتعقبة تلقائيًّا

Application Insights SDKs لـ.NET وذاكرة .NET الأساسية المشحونة مع DependencyTrackingTelemetryModule، وهي وحدة نمطية لبيانات تتبع الاستخدام التي تجمع التبعيات تلقائيًّا. يتم شحن الوحدة النمطية DependencyTrackingTelemetryModule كحزمة Microsoft.ApplicationInsights.DependencyCollector NuGet ويتم إحضارها تلقائيا عند استخدام حزمة Microsoft.ApplicationInsights.Web NuGet أو Microsoft.ApplicationInsights.AspNetCore حزمة NuGet.

يتعقب DependencyTrackingTelemetryModule حاليًا التبعيات التالية تلقائيًّا:

التبعيات التفاصيل
HTTP/HTTPS المكالمات المحلية أو البعيدة لـ HTTP/HTTPS.
مكالمات Windows Communication Foundation يتم تعقبها تلقائيًّا فقط في حال تم استخدام الارتباطات المسندة إلى HTTP.
SQL المكالمات التي أجريت بـSqlClient. راجع القسم Advanced SQL Tracking للحصول على استعلام SQL الكامل لالتقاط استعلامات SQL.
Azure Blob Storage أو Table Storage أو Queue Storage المكالمات التي أُجريت مع عميل موقع تخزين Azure.
مراكز أحداث Azure لعميل SDK استخدم أحدث حزمة: https://nuget.org/packages/Azure.Messaging.EventHubs.
ناقل خدمة Azure SDK لعميل SDK استخدم أحدث حزمة: https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB يتم تعقبه تلقائيا إذا تم استخدام HTTP/HTTPS. يتم التقاط تتبع العمليات في الوضع المباشر باستخدام TCP تلقائيا باستخدام حزمة >المعاينة = 3.33.0-preview. لمزيد من التفاصيل، تفضل بزيارة الوثائق.

إذا لم يتم تجميع التبعية تلقائيًّا، فبإمكانك تعقبها يدويًّا باستخدام استدعاء تبعية المسار.

لمزيد من المعلومات حول كيفية عمل تعقب التبعية، راجع تعقب التبعية في Application Insights.

إعداد تعقب التبعية التلقائي في تطبيقات وحدة التحكم

لتعقب التبعيات تلقائيًّا من تطبيقات وحدة التحكم .NET، قم بتثبيت حزمة NuGetMicrosoft.ApplicationInsights.DependencyCollector، ثم قم بتهيئة DependencyTrackingTelemetryModule:

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

ملاحظة

بالنسبة لتطبيقات .NET Core console، فإن TelemetryConfiguration.Active قديم.

تعقب التبعيات يدويًّا

فيما يلي أمثلة على التبعيات، التي لا تُجمع تلقائيًّا، وتتطلب التعقب يدويًّا:

  • يتم تعقب Azure Cosmos DB تلقائيًّا فقط إذا استُخدم HTTP/HTTPS. لا يتم التقاط وضع TCP تلقائيا بواسطة Application Insights لإصدارات SDK الأقدم من 2.22.0-Beta1.
  • Redis

لهذه التبعيات التي لم يتم جمعها تلقائيًّا من قِبل SDK، يمكنك تعقبها يدويًّا باستخدامTrackDependency APIالمستخدمة من قِبل وحدات التجميع التلقائية القياسية.

مثال

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

لعرض هذه البيانات في المخططات البيانية للتبعية في Application Insights، أرسلها باستخدام TrackDependency:


    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

بدلًا من ذلك،TelemetryClientيوفر أساليب التوسيعStartOperationوالتيStopOperationيمكن استخدامها لتعقب التبعيات يدويًّا، كما هو موضح في تعقب التبعيات الصادرة.

تعطيل وحدة تتبع التبعية القياسية

لمزيد من المعلومات، راجع وحدات القياس عن بعد.

تعقب SQL المتقدم للحصول على استعلام SQL كامل

بالنسبة لمكالمات SQL، يتم دائمًا تجميع اسم الخادم وقاعدة البيانات وتخزينها كاسم للمجمع DependencyTelemetry. حقل إضافي يُسمى البيانات يمكنه أن يحتوي على نص استعلام SQL المتكامل.

ملاحظة

تتطلب وظائف Azure إعدادات منفصلة لتمكين مجموعة SQL النصية. لمزيد من المعلومات، راجع تمكين مجموعة استعلام SQL.

ASP.NET

بالنسبة لتطبيقات ASP.NET، يتم تجميع نص الاستعلام SQL الكامل بمساعدة تقرير عن حالة النظام للتعليمات البرمجية البايت، التي تتطلب استخدام تقرير عن حالة نظام المحرك أو باستخدام حزمةMicrosoft.Data.SqlClientNuGet بدلا من مكتبة System.Data.SqlClient. ويرد في الجدول التالي وصف لخطوات النظام الأساسي المحددة لتمكين مجموعة استعلام SQL المتكاملة.

النظام الأساسي الخطوات اللازمة للحصول على استعلام SQL متكامل
تطبيقات الويب في Azure App Service في لوحة التحكم بتطبيق الويب، افتح جزء Application Insights وقم بتمكن أوامر SQL ضمن .NET.
خادم IIS (أجهزة Azure الظاهرية، المحلية، وما إلى ذلك) إما استخدام حزمة Microsoft.Data.SqlClient NuGet أو استخدام وحدة PowerShell لعامل Application Insights لتثبيت محرك الأجهزة وإعادة تشغيل IIS.
خدمات Azure السحابية إضافة مهمة بدء التشغيل لتركيب StatusMonitor.
يجب أن يكون تطبيقك موحدا في ApplicationInsights SDK في وقت الإنشاء عن طريق تثبيت حزم NuGet للتطبيقات ASP.NET أو ASP.NET الأساسية.
IIS Express: استخدام حزمةMicrosoft.Data.SqlClientNuGet.
WebJobs في Azure App Service استخدام حزمةMicrosoft.Data.SqlClientNuGet.

بالإضافة إلى الخطوات السابقة الخاصة بالنظام الأساسي، يجب عليك أيضًا الاشتراك بشكل صريح لتمكين مجموعة أوامر SQL عن طريق تعديل الملف ApplicationInsights.config بالرمز التالي:

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>
ASP.NET Core

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

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

في الحالات السابقة، الطريقة الصحيحة للتحقق من تثبيت محرك الأجهزة بشكل صحيح هي التحقق من صحة إصدار SDK للـ DependencyTelemetry المجمع هو rddp. يتم جمع استخدام rdddsd التبعيات أو rddf الإشارة إليها عبر DiagnosticSource عمليات الاسترجاعات أو EventSource الاستدعاءات، لذلك لا يتم التقاط استعلام SQL الكامل.

الاستثناءات

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

إعداد تقارير الاستثناءات

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

من جانب الخادم

لتسجيل استثناءات من التطبيق من جانب الخادم، ضع في اعتبارك السيناريوهات التالية:

جانب العميل

توفر JavaScript SDK القدرة على إعداد التقارير من جانب العميل للاستثناءات التي تحدث في مستعرضات الويب. لإعداد تقارير الاستثناءات على العميل، راجع Application Insights لصفحات الويب.

أطر التطبيق

مع بعض أطر عمل التطبيق، يلزم المزيد من التكوين. ضع في اعتبارك التقنيات التالية:

هام

يركز هذا القسم على تطبيقات .NET Framework من منظور مثال التعليمات البرمجية. بعض الأساليب التي تعمل مع .NET Framework قديمة في .NET Core SDK.

تشخيص حالات الفشل والاستثناءات

مدخل Azure

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

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

Visual Studio

  1. افتح حل التطبيق في Visual Studio. قم بتشغيل التطبيق، إما على الخادم الخاص بك أو على جهاز التطوير الخاص بك باستخدام F5. أعد إنشاء الاستثناء.

  2. افتح نافذة بيانات تتبع الاستخدام Application Insights Search في Visual Studio. أثناء تصحيح الأخطاء، حدد المربع المنسدل Application Insights .

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

    إذا تم تمكين CodeLens ، فسترى بيانات حول الاستثناءات:

    لقطة شاشة تعرض إشعار CodeLens بالاستثناءات.

بيانات التتبع والسجل المخصصة

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

باستخدام Microsoft.VisualStudio.ApplicationInsights.TelemetryClient، لديك العديد من واجهات برمجة التطبيقات المتاحة:

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

لقطة شاشة تعرض شاشة البحث.

ملاحظة

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

انظر طلب بيانات POST

لا تتضمن تفاصيل الطلب البيانات المرسلة إلى تطبيقك في مكالمة POST. لإعداد تقارير عن هذه البيانات:

  • أضف Application Insights SDK إلى التعليمات البرمجية للتطبيق الخاص بك.
  • أدخل التعليمات البرمجية في التطبيق الخاص بك لاستدعاء Microsoft.ApplicationInsights.TrackTrace(). أرسل بيانات POST في معلمة الرسالة. هناك حد للحجم المسموح به ، لذلك يجب أن تحاول إرسال البيانات الأساسية فقط.
  • عند التحقيق في طلب فاشل، ابحث عن التتبعات المقترنة.

بشكل افتراضي، لا تظهر جميع الاستثناءات التي تتسبب في حدوث فشل في تطبيقك في المدخل. إذا كنت تستخدم JavaScript SDK في صفحات الويب الخاصة بك، فسترى استثناءات المتصفح. ومع ذلك، يتم اعتراض معظم الاستثناءات من جانب الخادم بواسطة IIS، لذلك تحتاج إلى إضافة بعض التعليمات البرمجية لالتقاطها والإبلاغ عنها.

يمكنك:

  • سجل الاستثناءات بشكل صريح عن طريق إدراج التعليمات البرمجية في معالجات الاستثناءات للإبلاغ عن الاستثناءات.
  • التقط الاستثناءات تلقائيا عن طريق تكوين إطار عمل ASP.NET الخاص بك. تختلف الإضافات الضرورية باختلاف أنواع الأطر.
الإبلاغ عن الاستثناءات بشكل صريح

إن أبسط طريقة للإبلاغ هي إدراج استدعاء في trackException() معالج استثناء.

C#‎
var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}
JavaScript
try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

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

استثناءات المستعرض

يتم الإبلاغ عن معظم استثناءات المتصفح.

إذا كانت صفحة الويب تتضمن ملفات نص برمجي من شبكات توصيل المحتوى أو نطاقات أخرى، تأكد من أن علامة النص البرمجي تحتوي على السمة crossorigin="anonymous" وأن الخادم يرسل رؤوس CORS. يسمح لك هذا السلوك بالحصول على تتبع مكدس وتفاصيل لاستثناءات JavaScript غير المعالجة من هذه الموارد.

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

ملاحظة

نوصي بإنشاء TelemetryClient مثيل مرة واحدة وإعادة استخدامها طوال عمر التطبيق.

باستخدام حقن التبعية (DI) في .NET ، و .NET SDK المناسب ، وتكوين Application Insights for DI بشكل صحيح ، يمكنك طلب TelemetryClient المعلمة كمنشئ.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

في المثال السابق ، TelemetryClient يتم حقن ال في الفئة ExampleController .

نماذج الويب

بالنسبة لنماذج الويب، تكون الوحدة النمطية HTTP قادرة على تجميع الاستثناءات عند عدم وجود عمليات إعادة توجيه تم تكوينها باستخدام CustomErrors. ومع ذلك، عندما يكون لديك عمليات إعادة توجيه نشطة، أضف الأسطر التالية إلى الدالة Application_Error في Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

في المثال السابق ، هو _telemetryClient متغير على نطاق الفئة من النوع TelemetryClient.

MVC

بدءا من الإصدار 2.6 من Application Insights Web SDK (الإصدار التجريبي 3 والإصدارات الأحدث)، يجمع Application Insights الاستثناءات غير المعالجة التي تم طرحها في أساليب وحدات التحكم MVC 5+ تلقائيا. إذا كنت قد أضفت معالجا مخصصا مسبقا لتعقب هذه الاستثناءات، فيمكنك إزالته لمنع التعقب المزدوج للاستثناءات.

هناك العديد من السيناريوهات التي يتعذر فيها على عامل تصفية الاستثناءات معالجة الأخطاء بشكل صحيح عند طرح الاستثناءات:

  • من منشئات وحدة التحكم
  • من معالجات الرسائل
  • أثناء التوجيه
  • أثناء تسلسل محتوى الاستجابة
  • أثناء بدء التطبيق
  • في مهام الخلفية

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

دعم الإصدارات السابقة

إذا كنت تستخدم MVC 4 (والإصدارات السابقة) من Application Insights Web SDK 2.5 (والسابق)، فراجع الأمثلة التالية لتعقب الاستثناءات.


قم بالتوسيع لعرض إرشادات الإصدارات السابقة

إذا كان تكوين CustomErrors هو Off، تتوفر استثناءات لوحدة HTTP النمطية لتجميعها. ومع ذلك، إذا تم تعيينه إلى RemoteOnly (افتراضي) أو On، مسح الاستثناء وغير متاح ل Application Insights لجمعه تلقائيا. يمكنك إصلاح هذا السلوك عن طريق تجاوز الفئة System.Web.Mvc.HandleErrorAttribute وتطبيق الفئة التي تم تجاوزها كما هو موضح لإصدارات MVC المختلفة هنا (راجع مصدر GitHub):

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

ام في سي 2

استبدل السمة HandleError بالسمة الجديدة في وحدات التحكم الخاصة بك:

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

العينة

ام في سي 3

التسجيل AiHandleErrorAttribute كعامل تصفية عمومي في Global.asax.cs:

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

العينة

MVC 4 ، MVC 5

التسجيل AiHandleErrorAttribute كعامل تصفية عام في FilterConfig.cs:

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

العينة

واجهة برمجة تطبيقات الويب

بدءا من الإصدار 2.6 من Application Insights Web SDK (الإصدار التجريبي 3 والإصدارات الأحدث)، يجمع Application Insights الاستثناءات غير المعالجة التي تم طرحها في أساليب وحدة التحكم تلقائيا لواجهة برمجة تطبيقات الويب 2+. إذا أضفت معالجا مخصصا مسبقا لتعقب هذه الاستثناءات، كما هو موضح في الأمثلة التالية، فيمكنك إزالته لمنع التعقب المزدوج للاستثناءات.

هناك العديد من الحالات التي لا يمكن لعوامل تصفية الاستثناءات التعامل معها. على سبيل المثال:

  • الاستثناءات التي تم طرحها من منشئي وحدة التحكم.
  • الاستثناءات التي تم طرحها من معالجات الرسائل.
  • الاستثناءات التي تم طرحها أثناء التوجيه.
  • الاستثناءات التي تم طرحها أثناء تسلسل محتوى الاستجابة.
  • الاستثناء الذي تم طرحه أثناء بدء تشغيل التطبيق.
  • استثناء ألقيت في مهام الخلفية.

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

دعم الإصدارات السابقة

إذا كنت تستخدم Web API 1 (والإصدارات الأقدم) من Application Insights Web SDK 2.5 (والإصدارات الأقدم)، فراجع الأمثلة التالية لتعقب الاستثناءات.


قم بالتوسيع لعرض إرشادات الإصدارات السابقة

واجهة برمجة تطبيقات الويب 1.x

تجاوز System.Web.Http.Filters.ExceptionFilterAttribute:

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

يمكنك إضافة هذه السمة التي تم تجاوزها إلى وحدات تحكم محددة، أو إضافتها إلى تكوين عامل التصفية العام في الفئة WebApiConfig :

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

العينة

واجهة برمجة تطبيقات الويب 2.x

أضف تطبيقا ل IExceptionLogger:

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

أضف هذا المقتطف إلى الخدمات في WebApiConfig:

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

العينة

كبدائل ، يمكنك:

  • استبدل المثيل الوحيد ExceptionHandler بتنفيذ مخصص ل IExceptionHandler. يتم استدعاء معالج الاستثناء هذا فقط عندما لا يزال إطار العمل قادرا على اختيار رسالة الاستجابة التي سيتم إرسالها، وليس عند إحباط الاتصال، على سبيل المثال.
  • استخدم عوامل تصفية الاستثناءات، كما هو موضح في القسم السابق حول وحدات تحكم Web API 1.x، والتي لا يتم استدعاؤها في جميع الحالات.

WCF

أضف فئة تمتد Attribute وتنفذ IErrorHandler و IServiceBehavior.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

أضف السمة إلى عمليات تنفيذ الخدمة:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

العينة

عدادات أداء الاستثناء

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

افتح علامة تبويب مستكشف المقاييس وأضف مخططا جديدا. ضمن عدادات الأداء، حدد معدل الاستثناء.

يحسب .NET Framework المعدل عن طريق حساب عدد الاستثناءات في الفاصل الزمني والقسمة على طول الفاصل الزمني.

يختلف هذا العدد عن عدد الاستثناءات المحسوب بواسطة تقارير جرد TrackException مدخل Application Insights. تختلف الفواصل الزمنية لأخذ العينات، ولا ترسل TrackException SDK تقارير لجميع الاستثناءات التي تمت معالجتها وغير المعالجة.

مجموعة المقاييس المخصصة

تحتوي Azure Monitor Application Insights .NET و.NET Core SDKs على طريقتين مختلفتين لجمع المقاييس المخصصة:

  • الطريقة TrackMetric() التي تفتقر إلى التجميع المسبق.
  • الطريقة GetMetric() التي تحتوي على تجميع مسبق.

نوصي باستخدام التجميع، لذلك TrackMetric()لم تعد الطريقة المفضلة لجمع المقاييس المخصصة. ترشدك هذه المقالة إلى استخدام GetMetric() الطريقة وبعض الأساس المنطقي وراء كيفية عملها.


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

TrackMetric() ترسل الطريقة القياس عن بعد الخام الذي يشير إلى مقياس. من غير الفعال إرسال عنصر بيانات تتبع الاستخدام واحد لكل قيمة. الطريقة TrackMetric() أيضا غير فعالة من حيث الأداء لأن كل منها TrackMetric(item) يمر عبر خط أنابيب SDK الكامل لمهيلات ومعالجات القياس عن بعد.

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

في Application Insights، لا تخضع المقاييس المخصصة التي تم جمعها عبر TrackMetric()GetMetric() عليها. يمكن أن يؤدي أخذ عينات من المقاييس المهمة إلى سيناريوهات تصبح فيها التنبيهات التي تم إنشاؤها حول هذه المقاييس غير موثوقة. من خلال عدم أخذ عينات من المقاييس المخصصة الخاصة بك مطلقا ، يمكنك أن تكون واثقا بشكل عام من أنه عند اختراق عتبات التنبيه الخاصة بك ، يتم إطلاق تنبيه. نظرا لعدم أخذ عينات من المقاييس المخصصة، فهناك بعض المخاوف المحتملة.

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

  • زيادة تكاليف تخزين البيانات. هناك تكلفة مرتبطة بمقدار البيانات التي ترسلها إلى Azure Monitor. كلما زادت البيانات التي ترسلها ، زادت التكلفة الإجمالية للمراقبة.
  • زيادة حركة مرور الشبكة أو النفقات العامة للأداء. في بعض السيناريوهات ، يمكن أن يكون لهذه النفقات العامة تكلفة أداء نقدية وتطبيقية.
  • خطر اختناق الابتلاع. يقوم Azure Monitor بإسقاط نقاط البيانات ("التقييد") عندما يرسل تطبيقك معدلا عاليا من بيانات تتبع الاستخدام في فترة زمنية قصيرة.

يعد الاختناق مصدر قلق لأنه يمكن أن يؤدي إلى تفويت التنبيهات. يمكن أن يحدث شرط تشغيل تنبيه محليا ثم يتم إسقاطه عند نقطة نهاية الاستيعاب بسبب إرسال الكثير من البيانات. لا نوصي باستخدام TrackMetric() ل .NET و .NET Core إلا إذا قمت بتنفيذ منطق التجميع المحلي الخاص بك. إذا كنت تحاول تتبع كل حالة يحدث فيها حدث خلال فترة زمنية معينة ، فقد تجد أن هذا TrackEvent() هو الأنسب. ضع في اعتبارك أنه على عكس المقاييس المخصصة ، تخضع الأحداث المخصصة لأخذ العينات. لا يزال بإمكانك الاستخدام TrackMetric() حتى بدون كتابة التجميع المحلي الخاص بك. ولكن إذا قمت بذلك ، فكن على دراية بالمزالق.

باختصار ، نوصي GetMetric() لأنه يقوم بالتجميع المسبق ، ويجمع القيم من جميع المكالمات Track() ، ويرسل ملخصا / تجميعا مرة كل دقيقة. يمكن أن تقلل الطريقة GetMetric() بشكل كبير من التكلفة والنفقات العامة للأداء عن طريق إرسال عدد أقل من نقاط البيانات مع الاستمرار في جمع جميع المعلومات ذات الصلة.

بدء استخدام GetMetric

بالنسبة لأمثلتنا ، سنستخدم تطبيق خدمة عامل .NET Core 3.1 أساسي. إذا كنت ترغب في نسخ بيئة الاختبار المستخدمة مع هذه الأمثلة، فاتبع الخطوات من 1 إلى 6 ضمن تطبيق .NET Core Worker Service. تضيف هذه الخطوات Application Insights إلى قالب مشروع خدمة عامل أساسي. تنطبق المفاهيم على أي تطبيق عام حيث يمكن استخدام SDK، بما في ذلك تطبيقات الويب وتطبيقات وحدة التحكم.

إرسال المقاييس

استبدل محتويات الملف بالرمز worker.cs التالي:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

عند تشغيل نموذج التعليمات البرمجية، سترى الحلقة while الحلقية يتم تنفيذها بشكل متكرر دون إرسال بيانات تتبع الاستخدام في نافذة إخراج Visual Studio. يتم إرسال عنصر قياس تتبع الاستخدام واحد حول علامة 60 ثانية ، والتي تبدو في اختبارنا كما يلي:

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

يمثل عنصر القياس عن بعد الفردي هذا مجموعة من 41 قياسا متريا مميزا. نظرا لأننا كنا نرسل نفس القيمة مرارا وتكرارا ، فلدينا انحراف معياري (stDev) مع 0 قيم الحد الأقصى (max) والحد الأدنى (min) المتطابقة. تمثل الخاصية value مجموع جميع القيم الفردية التي تم تجميعها.

ملاحظة

لا تدعم الطريقة GetMetric تتبع القيمة الأخيرة (على سبيل المثال، gauge) أو تتبع الرسوم البيانية أو التوزيعات.

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

لقطة شاشة تعرض طريقة عرض استعلام Log Analytics.

ملاحظة

على الرغم من أن عنصر بيانات تتبع الاستخدام الأولية لم يحتوي على خاصية/حقل مجموع صريح بمجرد استيعابه، فإننا ننشئ واحدا لك. في هذه الحالة ، يمثل كل من value الخاصية نفس valueSum الشيء.

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

لقطة شاشة تعرض طريقة عرض مستكشف المقاييس.

مرجع مقياس ذاكرة التخزين المؤقت للاستخدام عالي الإنتاجية

قد يتم ملاحظة قيم القياس بشكل متكرر في بعض الحالات. على سبيل المثال، قد ترغب الخدمة عالية الإنتاجية التي تعالج 500 طلب في الثانية في إصدار 20 مقياسا للقياس عن بعد لكل طلب. والنتيجة تعني تتبع 10,000 قيمة في الثانية. في مثل هذه السيناريوهات عالية الإنتاجية، قد يحتاج المستخدمون إلى مساعدة SDK عن طريق تجنب بعض عمليات البحث.

على سبيل المثال، أجرى المثال السابق بحثا عن مقبض للمقياس ComputersSold ثم تتبع قيمة ملحوظة ل 42. بدلا من ذلك، قد يتم تخزين المعرف مؤقتا لاستدعاءات المسار المتعددة:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

بالإضافة إلى التخزين المؤقت للمقبض المتري ، تم تقليل المثال السابق أيضا Task.Delay إلى 50 مللي ثانية بحيث يتم تنفيذ الحلقة بشكل متكرر. والنتيجة هي 772 TrackValue() دعوة.

مقاييس متعددة الأبعاد

توضح الأمثلة الواردة في القسم السابق مقاييس ذات أبعاد صفرية. يمكن أن تكون المقاييس متعددة الأبعاد أيضا. نحن ندعم حاليا ما يصل إلى 10 أبعاد.

فيما يلي مثال على كيفية إنشاء مقياس أحادي البعد:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

يؤدي تشغيل نموذج التعليمات البرمجية لمدة 60 ثانية على الأقل إلى إرسال ثلاثة عناصر بيانات تتبع الاستخدام المميزة إلى Azure. يمثل كل عنصر تجميع أحد عوامل الشكل الثلاثة. كما كان من قبل، يمكنك إجراء مزيد من الفحص في طريقة عرض السجلات (التحليلات ).

لقطة شاشة تعرض طريقة عرض Log Analytics للمقياس متعدد الأبعاد.

في مستكشف المقاييس:

لقطة شاشة تعرض المقاييس المخصصة.

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

لقطة شاشة توضح دعم التقسيم.

بشكل افتراضي، لا يتم تشغيل المقاييس متعددة الأبعاد داخل مستكشف المقاييس في موارد Application Insights.

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

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

بعد إجراء هذا التغيير وإرسال بيانات تتبع الاستخدام الجديدة متعددة الأبعاد، يمكنك تحديد تطبيق التقسيم.

ملاحظة

يتم تخزين أبعاد المقاييس المرسلة حديثا بعد تشغيل الميزة في المدخل فقط.

لقطة شاشة توضح تطبيق التقسيم.

عرض تجميعات المقاييس لكل FormFactor بعد.

لقطة شاشة توضح عوامل الشكل.

استخدام MetricIdentifier عندما يكون هناك أكثر من ثلاثة أبعاد

حاليا ، يتم دعم 10 أبعاد. يتطلب استخدام أكثر من ثلاثة أبعاد استخدام MetricIdentifier:

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

تكوين المقياس المخصص

إذا كنت ترغب في تغيير تكوين المقياس، فيجب عليك إجراء تعديلات في المكان الذي يتم فيه تهيئة المقياس.

أسماء الأبعاد الخاصة

لا تستخدم المقاييس سياق القياس عن بعد المستخدم TelemetryClient للوصول إليها. يعد استخدام أسماء الأبعاد الخاصة المتوفرة كثوابت في MetricDimensionNames الفصل هو أفضل حل بديل لهذا القيد.

Special Operation Request Size يتم تعيين مجاميع المقاييس المرسلة بواسطة المقياس التالي Context.Operation.Name إلى Special Operation. TrackMetric() تم تعيين الطريقة أو أي طريقة TrackXXX() أخرى OperationName بشكل صحيح على Special Operation.

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

في هذه الحالة، استخدم أسماء الأبعاد الخاصة المدرجة في الفئة MetricDimensionNames لتحديد القيم TelemetryContext .

على سبيل المثال، عندما يتم إرسال تجميع المقياس الناتج عن العبارة التالية إلى نقطة نهاية السحابة Application Insights، يتم تعيين حقل البيانات الخاص به Context.Operation.Name إلى Special Operation:

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

يتم نسخ قيمة هذا البعد الخاص إلى TelemetryContext البعد ولا يتم استخدامه كبعد عادي . إذا كنت تريد أيضا الاحتفاظ بمكون عملية لاستكشاف المقاييس العادية، عليك إنشاء مكون منفصل لهذا الغرض:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");
تحديد الأبعاد والسلاسل الزمنية

لمنع النظام الفرعي للقياس عن بعد من استخدام مواردك عن طريق الخطأ، يمكنك التحكم في الحد الأقصى لعدد سلاسل البيانات لكل مقياس. لا تزيد الحدود الافتراضية عن 1,000 سلسلة بيانات إجمالية لكل مقياس، ولا تزيد عن 100 قيمة مختلفة لكل بعد.

هام

استخدم قيما أساسية منخفضة للأبعاد لتجنب الاختناق.

في سياق تحديد الأبعاد والسلاسل الزمنية ، نستخدم Metric.TrackValue(..) للتأكد من مراعاة الحدود. إذا تم الوصول إلى الحدود بالفعل، Metric.TrackValue(..) يتم إرجاع False ولا يتم تتبع القيمة. خلاف ذلك ، فإنه يعود True. يكون هذا السلوك مفيدا إذا كانت بيانات المقياس تنشأ من إدخال المستخدم.

يأخذ MetricConfiguration المنشئ بعض الخيارات حول كيفية إدارة سلاسل مختلفة داخل المقياس المعني وكائن من فئة يتم تنفيذها IMetricSeriesConfiguration يحدد سلوك التجميع لكل سلسلة فردية من المقياس:

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call doesn't track the metric, and returns false.
  • seriesCountLimit هو الحد الأقصى لعدد السلاسل الزمنية للبيانات التي يمكن أن يحتويها المقياس. عند الوصول إلى هذا الحد ، ستؤدي المكالمات إلى TrackValue() ذلك عادة إلى إرجاع falseسلسلة جديدة.
  • valuesPerDimensionLimit يحد من عدد القيم المميزة لكل بعد بطريقة مماثلة.
  • restrictToUInt32Values يحدد ما إذا كان يجب تتبع قيم الأعداد الصحيحة غير السالبة فقط أم لا.

فيما يلي مثال على كيفية إرسال رسالة لمعرفة ما إذا كان قد تم تجاوز حدود الحد الأقصى:

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

تتبع العمليات المخصصة

تتعقب حزم SDK الخاصة ب Application Insights تلقائيا طلبات HTTP الواردة والمكالمات إلى الخدمات التابعة، مثل طلبات HTTP واستعلامات SQL. يمنحك تعقب الطلبات والتبعيات وارتباطها رؤية لاستجابة التطبيق بالكامل وموثوقيته عبر جميع الخدمات المصغرة التي تجمع بين هذا التطبيق.

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

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

نظرة عامة‬

العملية هي جزء منطقي من العمل يديره أحد التطبيقات. له اسم ووقت بدء ومدة ونتيجة وسياق تنفيذ مثل اسم المستخدم والخصائص والنتيجة. إذا بدأت العملية A بواسطة العملية B ، تعيين العملية B كأصل ل A. يمكن أن يكون للعملية والد واحد فقط ، ولكن يمكن أن يكون لها العديد من العمليات الفرعية. لمزيد من المعلومات حول العمليات وارتباط بيانات تتبع الاستخدام، راجع ارتباط بيانات تتبع الاستخدام في Application Insights.

في Application Insights .NET SDK، يتم وصف العملية بواسطة الفئة المجردة OperationTelemetry وأحفادها RequestTelemetry و DependencyTelemetry.

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

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

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

دعونا نرى كيف يمكن تتبع مثل هذه العمليات.

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

طلب HTTP في تطبيق Owin المستضاف ذاتيا

في هذا المثال، يتم نشر سياق التتبع وفقا لبروتوكول HTTP للارتباط. يجب أن تتوقع تلقي الرؤوس الموضحة هناك.


قم بالتوسيع لعرض التعليمات البرمجية 
public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

يعلن بروتوكول HTTP للارتباط أيضا عن الرأس Correlation-Context . تم حذفه هنا من أجل البساطة.

أجهزة قائمة الانتظار

يمرر سياق تتبع W3Cوبروتوكول HTTP للارتباط تفاصيل الارتباط مع طلبات HTTP، ولكن يجب أن يحدد كل بروتوكول قائمة انتظار كيفية تمرير نفس التفاصيل عبر رسالة قائمة الانتظار. تسمح بعض بروتوكولات قائمة الانتظار، مثل AMQP، بتمرير المزيد من بيانات التعريف. تتطلب البروتوكولات الأخرى، مثل قائمة انتظار تخزين Azure، ترميز السياق في حمولة الرسالة.

ملاحظة

التتبع عبر المكونات غير مدعوم لقوائم الانتظار حتى الآن.

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

قائمة انتظار حافلة الخدمة

للحصول على معلومات التتبع، راجع التتبع الموزع والارتباط من خلال مراسلة ناقل خدمة Azure.

قائمة انتظار تخزين Azure

يوضح المثال التالي كيفية تعقب عمليات قائمة انتظار Azure Storage وربط بيانات تتبع الاستخدام بين المنتج والمستهلك وAzure Storage.

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

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

قائمة الانتظار

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

يوضح هذا المثال كيفية تعقب Enqueue العملية. يمكنك:

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

العملية Enqueue هي التابعة لعملية أصلية. مثال على ذلك هو طلب HTTP وارد. استدعاء تبعية HTTP هو تابع Enqueue العملية وحفيد الطلب الوارد.

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

لتقليل مقدار بيانات تتبع الاستخدام التي يبلغ عنها التطبيق أو إذا كنت لا تريد تتبع Enqueue العملية لأسباب أخرى، فاستخدم واجهة برمجة التطبيقات Activity مباشرة:

  • قم بإنشاء (وبدء) عملية جديدة Activity بدلا من بدء تشغيل Application Insights. لا تحتاج إلى تعيين أي خصائص عليه باستثناء اسم العملية.
  • التسلسل yourActivity.Id في حمولة الرسالة بدلا من operation.Telemetry.Id. يمكنك أيضًا استخدام Activity.Current.Id.
فك قائمة الانتظار

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

العملية Dequeue صعبة. يتتبع Application Insights SDK طلبات HTTP تلقائيا. لكنها لا تعرف سياق الارتباط حتى يتم تحليل الرسالة. لا يمكن ربط طلب HTTP للحصول على الرسالة ببقية بيانات تتبع الاستخدام، خاصة عند تلقي أكثر من رسالة واحدة.

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}
عملية

في المثال التالي، يتم تعقب رسالة واردة بطريقة مشابهة لطلب HTTP وارد:

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

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

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

  • قم بإنشاء عنصر جديد Activity بعد حصولك على عنصر من قائمة الانتظار.
  • يستخدم Activity.SetParentId(message.ParentId) لربط سجلات المستهلك والمنتج.
  • ابدأ في نطاق Activity.
  • تعقب عمليات إلغاء قائمة الانتظار ومعالجتها وحذفها باستخدام Start/StopOperation المساعدين. افعل ذلك من نفس تدفق التحكم غير المتزامن (سياق التنفيذ). بهذه الطريقة ، يتم ربطهما بشكل صحيح.
  • أوقف نطاق Activity.
  • استخدم Start/StopOperation بيانات تتبع الاستخدام يدويا أو اتصل Track بها.
أنواع التبعية

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

  • Azure queue لقوائم انتظار تخزين Azure
  • Azure Event Hubs لمراكز أحداث Azure
  • Azure Service Bus لناقل خدمة Azure
معالجة الدُفعات

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

يجب معالجة كل رسالة في تدفق التحكم غير المتزامن الخاص بها. لمزيد من المعلومات، راجع قسم تعقب التبعيات الصادرة .

مهام الخلفية طويلة الأمد

تبدأ بعض التطبيقات عمليات طويلة الأمد قد تكون ناجمة عن طلبات المستخدم. من منظور التتبع / الأجهزة ، لا يختلف الأمر عن أدوات الطلب أو التبعية:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

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

عندما تبدأ المهمة من مؤشر ترابط الخلفية الذي لا يحتوي على أي عملية (Activity) مقترنة به، BackgroundTask لا يحتوي على أي أصل. ومع ذلك ، يمكن أن يكون لها عمليات متداخلة. ترتبط جميع عناصر بيانات تتبع الاستخدام التي تم الإبلاغ عنها من المهمة بعناصر DependencyTelemetry التي تم إنشاؤها في BackgroundTask.

تتبع التبعيات الصادرة

يمكنك تعقب نوع التبعية الخاصة بك أو عملية غير مدعومة من قبل Application Insights.

يمكن أن يكون الأسلوب Enqueue الموجود في قائمة انتظار ناقل خدمة Microsoft Azure أو قائمة انتظار التخزين بمثابة أمثلة لمثل هذا التعقب المخصص.

النهج العام لتعقب التبعية المخصصة هو:

  • استدعاء TelemetryClient.StartOperation الأسلوب (الامتداد) الذي يملأ DependencyTelemetry الخصائص المطلوبة للارتباط وبعض الخصائص الأخرى، مثل البداية والطابع الزمني والمدة.
  • قم بتعيين خصائص مخصصة أخرى على DependencyTelemetry، مثل الاسم وأي سياق آخر تحتاجه.
  • قم بإجراء مكالمة تبعية وانتظرها.
  • أوقف العملية StopOperation عند انتهائها.
  • معالجة الاستثناءات.
public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

يؤدي التخلص من عملية إلى توقف العملية ، لذلك يمكنك القيام بذلك بدلا من الاتصال StopOperation.

تحذير

في بعض الحالات، قد يمنعfinally الاستثناء غير اليدوي من الاستدعاء، لذلك قد لا يتم تعقب العمليات.

معالجة العمليات المتوازية وتتبعها

يؤدي الاتصال StopOperation إلى إيقاف العملية التي تم بدؤها فقط. إذا كانت العملية قيد التشغيل الحالية لا تتطابق مع العملية التي تريد إيقافها، StopOperation فلا تفعل شيئا. قد يحدث هذا الموقف إذا بدأت عمليات متعددة بالتوازي في نفس سياق التنفيذ.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

تأكد دائما من استدعاء StartOperation العملية ومعالجتها بنفس الطريقة غير المتزامنة لعزل العمليات التي تعمل بالتوازي. إذا كانت العملية متزامنة (أو غير متزامنة) ، فقم بلف العملية وتتبعها ب Task.Run.

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

عمليات ApplicationInsights مقابل System.Diagnostics.Activity

System.Diagnostics.Activity يمثل سياق التتبع الموزع وتستخدمه الأطر والمكتبات لإنشاء سياق ونشره داخل العملية وخارجها وربط عناصر القياس عن بعد. Activity يعمل جنبا إلى جنب مع System.Diagnostics.DiagnosticSource آلية الإخطار بين إطار العمل / المكتبة للإخطار بالأحداث المثيرة للاهتمام مثل الطلبات والاستثناءات الواردة أو الصادرة.

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

تتضمن كل عملية من عمليات Application Insights (الطلب أو التبعية) Activity. عندما StartOperation يتم استدعاؤه ، فإنه يخلق Activity تحته. StartOperation هي الطريقة الموصى بها لتتبع عمليات تتبع الاستخدام للطلب أو التبعية يدويا والتأكد من ارتباط كل شيء.

العدادات

يدعم Application Insights عدادات الأداء وعدادات الأحداث. يوفر هذا الدليل نظرة عامة على كليهما، بما في ذلك الغرض منها وتكوينها واستخدامها في تطبيقات .NET.

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

  • تعمل عدادات الأحداث عبر منصات متعددة ، بما في ذلك Windows و Linux و macOS. إنها تسمح للمطورين بتحديد ومراقبة المقاييس خفيفة الوزن والقابلة للتخصيص الخاصة بالتطبيق، مما يوفر مرونة أكبر من عدادات الأداء. تكون عدادات الأحداث مفيدة عندما تكون مقاييس النظام غير كافية أو عندما تكون هناك حاجة إلى القياس عن بعد التفصيلي في التطبيقات عبر الأنظمة الأساسية. إنها تتطلب تنفيذا وتكوينا واضحين ، مما يجعل الإعداد أكثر كثافة في الجهد.

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

يوفر Windows عدادات أداء متنوعة، مثل تلك المستخدمة لتجميع إحصائيات استخدام المعالج والذاكرة والقرص. يمكنك أيضا تحديد عدادات الأداء الخاصة بك.

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

تلميح

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

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

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

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"
عرض العدادات

يعرض جزء المقاييس المجموعة الافتراضية من عدادات الأداء.

ASP.NET

العدادات الافتراضية لتطبيقات الويب ASP.NET:

  • % عملية \ وقت المعالج
  • % عملية / تطبيع وقت المعالج
  • الذاكرة / البايت المتاح
  • ASP.NET الطلبات/ثانية
  • استثناءات وقت تشغيل اللغة الشائعة (CLR) .NET التي تم طرحها / ثانية
  • ASP.NET التطبيقاتوقت تنفيذ الطلب
  • العملية\وحدات البايت الخاصة
  • معالجة\بايت بيانات IO/ثانية
  • ASP.NET التطبيقات\الطلبات في قائمة انتظار التطبيق
  • المعالج (_Total) \% وقت المعالج
ASP.NET Core

العدادات الافتراضية لتطبيقات الويب الأساسية ASP.NET:

  • % عملية \ وقت المعالج
  • % عملية / تطبيع وقت المعالج
  • الذاكرة / البايت المتاح
  • العملية\وحدات البايت الخاصة
  • معالجة\بايت بيانات IO/ثانية
  • المعالج (_Total) \% وقت المعالج

ملاحظة

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

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

إذا لم يكن عداد الأداء الذي تريده مضمنا في قائمة المقاييس، فيمكنك إضافته.

ASP.NET

الخيار 1: التكوين في ApplicationInsights.config

  1. تعرف على العدادات المتوفرة في الخادم الخاص بك باستخدام أمر PowerShell هذا على الخادم المحلي:

    Get-Counter -ListSet *

    لمزيد من المعلومات، راجع Get-Counter.

  2. افتح ApplicationInsights.config.

    إذا أضفت Application Insights إلى تطبيقك أثناء التطوير:

    1. التحرير ApplicationInsights.config في مشروعك.
    2. أعد نشره على الخوادم الخاصة بك.

  3. قم بتحرير توجيه جامع الأداء:

    
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <Add PerformanceCounter="\Objects\Processes"/>
        <Add PerformanceCounter="\Sales(photo)\# Items Sold" ReportAs="Photo sales"/>
      </Counters>
    </Add>

يمكنك التقاط كل من العدادات القياسية والعدادات التي تنفذها بنفسك. \Objects\Processes مثال على عداد قياسي متوفر على جميع أنظمة Windows. \Sales(photo)\# Items Sold مثال على عداد مخصص يمكن تنفيذه في خدمة ويب.

التنسيق هو \Category(instance)\Counter، أو للفئات التي لا تحتوي على مثيلات ، فقط \Category\Counter.

المعلمة ReportAs مطلوبة لأسماء العدادات التي لا تتطابق [a-zA-Z()/-_ \.]+.

إذا حددت مثيلا ، فسيصبح بعدا CounterInstanceName للمقياس الذي تم الإبلاغ عنه.

الخيار 2: التكوين في التعليمات البرمجية

انظر القسم التالي.

ASP.NET Core

قم بالتكوين PerformanceCollectorModule بعد WebApplication.CreateBuilder() الطريقة في Program.cs:

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();
تجميع عدادات الأداء في التعليمات البرمجية لتطبيقات الويب ASP.NET أو تطبيقات وحدة التحكم .NET/.NET Core

لتجميع عدادات أداء النظام وإرسالها إلى Application Insights، يمكنك تكييف القصاصة البرمجية التالية:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

أو يمكنك القيام بنفس الشيء باستخدام المقاييس المخصصة التي أنشأتها:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);
عدادات الأداء للتطبيقات التي تعمل في Azure Web Apps وحاويات Windows على Azure App Service

تعمل كل من تطبيقات ASP.NET و ASP.NET الأساسية المنشورة في Azure Web Apps في بيئة معزولة خاصة. يمكن للتطبيقات المنشورة في Azure App Service استخدام حاوية Windows أو استضافتها في بيئة آلية الحماية. إذا تم نشر التطبيق في حاوية Windows، تتوفر جميع عدادات الأداء القياسية في صورة الحاوية.

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

يكتشف Application Insights SDK ل ASP.NET و ASP.NET Core ما إذا كان يتم نشر التعليمات البرمجية إلى تطبيق ويب أو حاوية غير Windows. يحدد الكشف ما إذا كان يجمع عدادات الأداء في بيئة معزولة أو يستخدم آلية التجميع القياسية عند استضافته على حاوية Windows أو جهاز ظاهري.

استعلامات Log Analytics لعدادات الأداء

يمكنك البحث عن تقارير عداد الأداء وعرضها في Log Analytics.

يعرض مخطط performanceCounters كل categoryعداد أداء counter واسمه instance . في بيانات تتبع الاستخدام لكل تطبيق، سترى فقط عدادات هذا التطبيق. على سبيل المثال، لمعرفة العدادات المتوفرة:

performanceCounters | summarize count(), avg(value) by category, instance, counter

هنا ، Instance يشير إلى مثيل عداد الأداء ، وليس الدور ، أو مثيل جهاز الخادم. عادة ما يقوم اسم مثيل عداد الأداء بتقسيم العدادات، مثل وقت المعالج، حسب اسم العملية أو التطبيق.

للحصول على مخطط للذاكرة المتوفرة خلال الفترة الأخيرة:

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

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

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)
الأسئلة الشائعة حول عدادات الأداء

لمراجعة الأسئلة المتداولة (FAQ)، راجع الأسئلة المتداولة حول عدادات الأداء.

عدادات الأحداث

EventCounter هي آلية .NET / .NET Core لنشر واستهلاك العدادات أو الإحصائيات. يتم دعم EventCounters في جميع الأنظمة الأساسية لنظام التشغيل - Windows و Linux و macOS. يمكن اعتباره مكافئا عبر الأنظمة الأساسية ل PerformanceCounters المدعوم فقط في أنظمة Windows.

بينما يمكن للمستخدمين نشر أي عدادات أحداث مخصصة لتلبية احتياجاتهم، ينشر .NET مجموعة من هذه العدادات افتراضيا. يوضح هذا المستند الخطوات المطلوبة لجمع عدادات الأحداث وعرضها (المعرفة من قبل النظام أو المعرفة من قبل المستخدم) في Azure Application Insights.

تلميح

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

استخدام Application Insights لتجميع EventCounters

يدعم Application Insights التجميع EventCounters باستخدام EventCounterCollectionModule، وهو جزء من حزمة NuGet التي تم إصدارها حديثا Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule يتم تمكينه تلقائيا عند استخدام AspNetCore أو WorkerService. EventCounterCollectionModule يجمع العدادات بتردد تجميع غير قابل للتكوين يبلغ 60 ثانية. لا توجد أذونات خاصة مطلوبة لجمع EventCounters. بالنسبة للتطبيقات الأساسية ASP.NET، تريد أيضا إضافة حزمة Microsoft.ApplicationInsights.AspNetCore .

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore
العدادات الافتراضية التي تم جمعها

بدءا من الإصدار 2.15.0 من AspNetCore SDK أو WorkerService SDK، لا يتم جمع أي عدادات بشكل افتراضي. تم تمكين الوحدة النمطية نفسها ، بحيث يمكن للمستخدمين إضافة العدادات المطلوبة لجمعها.

للحصول على قائمة بالعدادات المعروفة التي تم نشرها بواسطة .NET Runtime، راجع مستند العدادات المتوفرة .

تخصيص العدادات المراد جمعها

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

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );
تعطيل وحدة تجميع EventCounter

EventCounterCollectionModule يمكن تعطيلها باستخدام ApplicationInsightsServiceOptions.

يستخدم المثال التالي ASP.NET Core SDK.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

يمكن استخدام نهج مماثل ل Worker Service SDK أيضا، ولكن يجب تغيير مساحة الاسم كما هو موضح في المثال التالي.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);
استعلامات Log Analytics لعدادات الأحداث

يمكنك البحث عن تقارير عداد الأحداث وعرضها في Log Analytics، في جدول customMetrics .

على سبيل المثال، قم بتشغيل الاستعلام التالي لمعرفة العدادات التي يتم جمعها والمتاحة للاستعلام:

customMetrics | summarize avg(value) by name

للحصول على مخطط لعداد معين (على سبيل المثال: ThreadPool Completed Work Item Count) خلال الفترة الأخيرة ، قم بتشغيل الاستعلام التالي.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

مثل بيانات تتبع الاستخدام الأخرى، يحتوي customMetrics أيضا على عمود cloud_RoleInstance يشير إلى هوية مثيل الخادم المضيف الذي يعمل عليه تطبيقك. يعرض الاستعلام السابق قيمة العداد لكل مثيل، ويمكن استخدامه لمقارنة أداء مثيلات الخادم المختلفة.

الأسئلة الشائعة حول عدادات الأحداث

لمراجعة الأسئلة المتداولة (FAQ)، راجع الأسئلة المتداولة حول عدادات الأحداث.

مجموعة اللقطات

لمعرفة كيفية تكوين مجموعة اللقطات لتطبيقات ASP.NET و ASP.NET الأساسية، راجع تمكين مصحح أخطاء اللقطات لتطبيقات .NET في Azure Service Fabric والخدمات السحابية والأجهزة الظاهرية.

معالجة وتصفية بيانات تتبع الاستخدام

في هذا القسم

التصفية والمعالجة المسبقة للبيانات عن بعد

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

  • يمكن أن تؤدي التصفية إلى تعديل بيانات تتبع الاستخدام أو تجاهلها قبل إرسالها من SDK عن طريق تنفيذ ITelemetryProcessor. على سبيل المثال، يمكنك تقليل حجم بيانات تتبع الاستخدام عن طريق استبعاد الطلبات من برامج الروبوت. على عكس أخذ العينات، يمكنك التحكم الكامل في ما يتم إرساله أو تجاهله، ولكنه يؤثر على أي مقاييس تستند إلى السجلات المجمعة. بناء على كيفية تجاهل العناصر، قد تفقد أيضا القدرة على التنقل بين العناصر ذات الصلة.

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

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

ملاحظة

تستخدم واجهة برمجة تطبيقات SDK لإرسال أحداث ومقاييس مخصصة.

تصفيه

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

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

تحذير

يمكن أن تؤدي تصفية بيانات تتبع الاستخدام المرسلة من SDK باستخدام المعالجات إلى تحريف الإحصائيات التي تراها في المدخل وتجعل من الصعب متابعة العناصر ذات الصلة.

بدلا من ذلك ، ضع في اعتبارك استخدام أخذ العينات.

ITelemetryProcessor و ITelemetryInitializer

ما الفرق بين معالجات القياس عن بعد ومهيئات القياس عن بعد؟

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

إضافة/تعديل الخصائص

استخدم مهيئات بيانات تتبع الاستخدام لإثراء بيانات تتبع الاستخدام بمعلومات إضافية أو لتجاوز خصائص بيانات تتبع الاستخدام التي تم تعيينها بواسطة وحدات القياس عن بعد القياسية القياسية.

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

إذا قمت بتوفير مهيئ بيانات تتبع الاستخدام، استدعاؤه كلما تم استدعاء أي من طرق Track*(). يتضمن Track() هذا المهيئ الأساليب التي تستدعيها وحدات القياس عن بعد القياسية. وفقا للاتفاق، لا تقوم هذه الوحدات النمطية بتعيين أي خاصية تم تعيينها بالفعل بواسطة مهيئ. يتم استدعاء مهيئات القياس عن بعد قبل استدعاء معالجات القياس عن بعد، لذا فإن أي تخصيب يتم إجراؤه بواسطة أجهزة التهيئة تكون مرئية للمعالجات.

مهيئات بيانات تتبع الاستخدام

لإثراء بيانات تتبع الاستخدام بمعلومات إضافية أو لتجاوز خصائص بيانات تتبع الاستخدام التي تم تعيينها بواسطة وحدات القياس عن بعد القياسية، استخدم مهيئات بيانات تتبع الاستخدام.

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

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

مهيئ الوصف
AccountIdTelemetryInitializer تعيين الخاصية AccountId .
AuthenticatedUserIdTelemetryInitializer لتعيين الخاصية AuthenticatedUserId على أنها تم تعيينها بواسطة JavaScript SDK.
AzureRoleEnvironmentTelemetryInitializer يقوم بتحديث RoleName وخصائص RoleInstanceDevice السياق لجميع عناصر بيانات تتبع الاستخدام بالمعلومات المستخرجة من بيئة وقت تشغيل 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 وخاصية NameOperation سياق جميع عناصر بيانات تتبع الاستخدام استنادا إلى أسلوب HTTP، وأسماء وحدة تحكم MVC ASP.NET والإجراء الذي تم استدعاؤه لمعالجة الطلب.
OperationIdTelemetryInitializer أو OperationCorrelationTelemetryInitializer يقوم بتحديث Operation.Id خاصية السياق لجميع عناصر بيانات تتبع الاستخدام التي يتم تعقبها أثناء معالجة طلب باستخدام الملف الذي تم إنشاؤه RequestTelemetry.Idتلقائيا.
SessionTelemetryInitializer تحديث Id خاصية Session السياق لجميع عناصر بيانات تتبع الاستخدام بقيمة مستخرجة من ملف تعريف الارتباط ai_session الذي تم إنشاؤه بواسطة ApplicationInsights التعليمات البرمجية لأجهزة JavaScript التي تعمل في مستعرض المستخدم.
SyntheticTelemetryInitializer أو SyntheticUserAgentTelemetryInitializer يقوم بتحديث Userخصائص ، Sessionو Operation و السياق لجميع عناصر بيانات تتبع الاستخدام التي يتم تعقبها عند معالجة طلب من مصدر اصطناعي، مثل اختبار التوفر أو روبوت محرك البحث. بشكل افتراضي، لا يعرض مستكشف المقاييس بيانات تتبع الاستخدام الاصطناعية.

مجموعة <Filters> تحديد خصائص الطلبات.
UserTelemetryInitializer يقوم بتحديث Id وخصائص AcquisitionDateUser السياق لجميع عناصر بيانات تتبع الاستخدام مع القيم المستخرجة من ملف تعريف الارتباط ai_user الذي تم إنشاؤه بواسطة التعليمات البرمجية لأجهزة JavaScript في Application Insights التي تعمل في مستعرض المستخدم.
WebTestTelemetryInitializer يعين معرف المستخدم ومعرف الجلسة وخصائص المصدر الاصطناعي لطلبات HTTP التي تأتي من اختبارات التوفر.

مجموعة <Filters> تحديد خصائص الطلبات.

ملاحظة

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

إضافة ITelemetryInitializer

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

  1. تحديد المهيئ الخاص بك

    using System;
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

namespace MvcWebRole.Telemetry
{
  /*
   * Custom TelemetryInitializer that overrides the default SDK
   * behavior of treating response codes >= 400 as failed requests
   *
   */
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            var requestTelemetry = telemetry as RequestTelemetry;
            // Is this a TrackRequest() ?
            if (requestTelemetry == null) return;
            int code;
            bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
            if (!parsed) return;
            if (code >= 400 && code < 500)
            {
                // If we set the Success property, the SDK won't change it:
                requestTelemetry.Success = true;

                // Allow us to filter these requests in the portal:
                requestTelemetry.Properties["Overridden400s"] = "true";
            }
            // else leave the SDK to set the Success property
        }
    }
}

  2. قم بتحميل مهيئتك

ASP.NET

الخيار 1: التكوين في التعليمات البرمجية

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

الخيار 2: التكوين في ApplicationInsights.config

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

شاهد المزيد من هذه العينة.

ملاحظة

تأكد من أن ملف applicationinsights.config موجود في دليل الإخراج الخاص بك ويحتوي على أي تغييرات حديثة.

ASP.NET Core

إضافة مهيئ باستخدام ApplicationInsights.config تطبيقات ASP.NET الأساسية أو TelemetryConfiguration.Active غير صالحة.

بالنسبة للتطبيقات المكتوبة باستخدام ASP.NET Core، تتم إضافة مهيئ بيانات تتبع الاستخدام الجديدة عن طريق إضافته إلى الحاوية DependencyInjection ، كما هو موضح. أنجز هذه الخطوة في الطريقة Startup.ConfigureServices .

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" }); مطلوب.

إزالة مهيئات بيانات تتبع الاستخدام

افتراضيًا، توجد مُهيئات بيانات تتبع الاستخدام عن بُعد. لإزالة جميع بيانات تتبع الاستخدام أو المُحددة منها، استخدم نموذج التعليمات البرمجية التالي بعد الاتصال 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();
خدمة العمال

إضافة مهيئ باستخدام ApplicationInsights.config أو TelemetryConfiguration.Active غير صالح ل Worker Service SDK.

بالنسبة للتطبيقات المكتوبة باستخدام Worker Service، تتم إضافة مهيئ بيانات تتبع الاستخدام الجديدة عن طريق إضافته إلى الحاوية DependencyInjection ، كما هو موضح. أنجز هذه الخطوة في الطريقة Startup.ConfigureServices .

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }
إزالة مهيئات بيانات تتبع الاستخدام

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

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

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

مثال على ITelemetryInitializers

إضافة موقع مخصص

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

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}
إضافة اسم دور سحابي ومثيل دور سحابة

الخطوة 1: كتابة TelemetryInitializer مخصص

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

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

namespace CustomInitializer.Telemetry
{
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
            {
                //set custom role name here
                telemetry.Context.Cloud.RoleName = "Custom RoleName";
                telemetry.Context.Cloud.RoleInstance = "Custom RoleInstance";
            }
        }
    }
}

الخطوة 2: تحميل مهيئ إلى TelemetryConfiguration

ASP.NET

في ملف ApplicationInsights.config :

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

تتمثل الطريقة البديلة لتطبيقات الويب ASP.NET في إنشاء مثيل للمهيئ في التعليمات البرمجية. يوضح المثال التالي التعليمات البرمجية في ملف Global.aspx.cs :

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }
ASP.NET Core

لإضافة مثيل جديد TelemetryInitializer ، يمكنك إضافته إلى حاوية حقن التبعية. يوضح المثال التالي هذا النهج. أضف هذا الرمز في ConfigureServices طريقة فصلك Startup.cs .

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}
التحكم في عنوان IP للعميل المستخدم لتعيينات الموقع الجغرافي

يقوم نموذج المهيئ التالي بتعيين عنوان IP للعميل، والذي يتم استخدامه لتعيين الموقع الجغرافي، بدلا من عنوان IP لمقبس العميل، أثناء ابتلاع بيانات تتبع الاستخدام.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

معالجات القياس عن بعد

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

أنجز ITelemetryProcessor

تقوم معالجات القياس عن بعد ببناء سلسلة من المعالجة. عندما تقوم بإنشاء مثيل لمعالج القياس عن بعد، تحصل على مرجع إلى المعالج التالي في السلسلة. عندما يتم تمرير نقطة بيانات بيانات تتبع الاستخدام إلى طريقة العملية ، فإنها تقوم بعملها ثم تستدعي (أو لا تستدعي) معالج القياس عن بعد التالي في السلسلة.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.DataContracts;

public class SuccessfulDependencyFilter : ITelemetryProcessor
{
    private ITelemetryProcessor Next { get; set; }

    // next will point to the next TelemetryProcessor in the chain.
    public SuccessfulDependencyFilter(ITelemetryProcessor next)
    {
        this.Next = next;
    }

    public void Process(ITelemetry item)
    {
        // To filter out an item, return without calling the next processor.
        if (!OKtoSend(item)) { return; }

        this.Next.Process(item);
    }

    // Example: replace with your own criteria.
    private bool OKtoSend (ITelemetry item)
    {
        var dependency = item as DependencyTelemetry;
        if (dependency == null) return true;

        return dependency.Success != true;
    }
}

أضف المعالج الخاص بك

ASP.NET

أدخل هذا المقتطف في ApplicationInsights.config:

<TelemetryProcessors>
    <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
    <!-- Set public property -->
    <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
    </Add>
</TelemetryProcessors>

يمكنك تمرير قيم السلسلة من ملف .config عن طريق توفير خصائص مسماة عامة في الفصل الدراسي الخاص بك.

تحذير

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

بدلا من ذلك ، يمكنك تهيئة عامل التصفية في التعليمات البرمجية. في فئة تهيئة مناسبة ، على سبيل المثال ، AppStart في Global.asax.cs، أدخل المعالج الخاص بك في السلسلة:

ملاحظة

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

var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
builder.Use((next) => new SuccessfulDependencyFilter(next));

// If you have more processors:
builder.Use((next) => new AnotherProcessor(next));

builder.Build();

يستخدم عملاء القياس عن بعد الذين تم إنشاؤهم بعد هذه النقطة المعالجات الخاصة بك.

معالج قياس تتبع الاستخدام لأخذ العينات التكيفي (من 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>
ASP.NET Core

ملاحظة

إضافة معالج باستخدام ApplicationInsights.config تطبيقات ASP.NET Core أو TelemetryConfiguration.Active غير صالح أو إذا كنت تستخدم Microsoft.ApplicationInsights.WorkerService SDK.

بالنسبة إلى ASP.NET Core، تتم إضافة معالج بيانات تتبع الاستخدام الجديد باستخدام أسلوب الملحق AddApplicationInsightsTelemetryProcessor على IServiceCollection، كما هو موضح. تسمى هذه الطريقة في ConfigureServices طريقة فصلك Startup.cs .

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();

لتسجيل معالجات القياس عن بعد التي تحتاج إلى معلمات في ASP.NET Core، قم بإنشاء فئة مخصصة تنفذ ITelemetryProcessorFactory. استدعاء المنشئ بالمعلمات المطلوبة في الأسلوب إنشاء ثم استخدم AddSingleton<ITelemetryProcessorFactory وMyTelemetryProcessorFactory>().

خدمة العمال

ملاحظة

إضافة معالج باستخدام ApplicationInsights.config تطبيقات ASP.NET Core أو TelemetryConfiguration.Active غير صالح أو إذا كنت تستخدم Microsoft.ApplicationInsights.WorkerService SDK.

بالنسبة إلى Worker Service، تتم إضافة معالج بيانات تتبع الاستخدام جديد باستخدام أسلوب الملحق AddApplicationInsightsTelemetryProcessor على IServiceCollection، كما هو موضح. تسمى هذه الطريقة في ConfigureServices طريقة فصلك Startup.cs .

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();
        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
    }

أمثلة على الفلاتر

الطلبات التركيبية

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

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}
فشل المصادقة

فلترة الطلبات باستخدام استجابة "401".

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}
تصفية مكالمات التبعية السريعة عن بعد

إذا كنت ترغب في تشخيص المكالمات البطيئة فقط ، فقم بتصفية المكالمات السريعة.

ملاحظة

تؤدي هذه التصفية إلى تحريف الإحصائيات التي تراها على المدخل.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

أخذ عينات

لمعرفة كيفية تكوين أخذ العينات للتطبيقات الأساسية ASP.NET و ASP.NET، راجع أخذ العينات في Application Insights.

خدمة العمال

تدعم Application Insights SDK for Worker Service كلا من أخذ العينات ذات المعدل الثابتوأخذ العينات التكيفية. يتم تمكين أخذ العينات التكيفية افتراضيا. يمكن تعطيل أخذ العينات باستخدام EnableAdaptiveSampling الخيار الموجود في ApplicationInsightsServiceOptions.

لتكوين إعدادات أخذ العينات الأخرى، يمكنك استخدام المثال التالي:

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

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

ASP.NET

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

ASP.NET Core

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

تكوين SDK

في هذا القسم

يمكنك تخصيص Application Insights SDK ل ASP.NET و ASP.NET Core وWorker Service لتغيير التكوين الافتراضي.

ASP.NET

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

يتم تسمية ApplicationInsights.config ملف التكوين أو ApplicationInsights.xml. يعتمد الاسم على نوع التطبيق الخاص بك. تتم إضافته تلقائيا إلى مشروعك عند تثبيت معظم إصدارات SDK.

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

هام

يتم تجاهل ملف التكوين إذا تم استخدام ملحق مواقع Azure على الويب أو ملحق أجهزة Azure الظاهرية ومجموعات مقياس الجهاز الظاهري Azure .

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

ASP.NET Core

في ASP.NET تطبيقات Core، يتم إجراء جميع تغييرات التكوين في ConfigureServices() أسلوب فئة Startup.cs ، ما لم يتم توجيه خلاف ذلك.

ملاحظة

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

خدمة العمال

يشبه الإعداد الافتراضي TelemetryConfiguration المستخدم بواسطة Worker Service SDK التكوين التلقائي المستخدم في تطبيق ASP.NET أو ASP.NET Core، مطروحا منه مهيئات بيانات تتبع الاستخدام المستخدمة لإثراء بيانات تتبع الاستخدام من HttpContext.

يمكنك تخصيص Application Insights SDK for Worker Service لتغيير التكوين الافتراضي. قد يكون مستخدمو Application Insights ASP.NET Core SDK على دراية بتغيير التكوين باستخدام حقن التبعية المضمن في ASP.NET Core. تستند SDK لخدمة العمال أيضا إلى مبادئ مماثلة. قم بإجراء جميع تغييرات التكوين تقريبا في ConfigureServices() القسم عن طريق استدعاء الأساليب المناسبة ، IServiceCollectionكما هو مفصل في القسم التالي.

ملاحظة

عند استخدام Worker Service SDK، لا يتم دعم تغيير التكوين عن طريق التعديل TelemetryConfiguration.Active ولن تنعكس التغييرات.

قنوات القياس عن بعد

تعد قنوات بيانات تتبع الاستخدام جزءا لا يتجزأ من حزم SDK الخاصة ب Application Insights. يقومون بإدارة التخزين المؤقت ونقل بيانات تتبع الاستخدام إلى خدمة Application Insights. يحتوي إصداران .NET و .NET Core من SDKs على قناتين مضمنتين للقياس عن بعد: InMemoryChannel و ServerTelemetryChannel. يصف هذا القسم كل قناة ويوضح كيفية تخصيص سلوك القناة.

ملاحظة

لمراجعة الأسئلة المتداولة، راجع الأسئلة الشائعة حول قنوات القياس عن بعد

ما هي قنوات القياس عن بعد؟

قنوات بيانات تتبع الاستخدام مسؤولة عن التخزين المؤقت لعناصر بيانات تتبع الاستخدام وإرسالها إلى خدمة Application Insights، حيث يتم تخزينها للاستعلام والتحليل. قناة القياس عن بعد هي أي فئة تنفذ الواجهة Microsoft.ApplicationInsights.ITelemetryChannel .

Send(ITelemetry item) يتم استدعاء طريقة قناة القياس عن بعد بعد بعد استدعاء جميع مهيئات بيانات تتبع الاستخدام ومعالجات القياس عن بعد. لذلك ، فإن أي عناصر يتم إسقاطها بواسطة معالج القياس عن بعد لا تصل إلى القناة. لا ترسل الطريقة Send() عادة العناصر إلى النهاية الخلفية على الفور. عادة ما يقوم بتخزينها مؤقتا في الذاكرة وإرسالها على دفعات لنقل فعال.

تجنب الاتصال Flush() ما لم يكن من الضروري إرسال بيانات تتبع الاستخدام المخزنة مؤقتا على الفور. استخدمه فقط في سيناريوهات مثل إيقاف تشغيل التطبيق أو معالجة الاستثناءات أو عند استخدام عمليات قصيرة العمر مثل مهام الخلفية أو أدوات سطر الأوامر. في تطبيقات الويب أو الخدمات طويلة الأمد، تتعامل SDK مع إرسال بيانات تتبع الاستخدام تلقائيا. يمكن أن يتسبب الاتصال Flush() دون داع في حدوث مشكلات في الأداء.

يحتوي Live Metrics Stream أيضا على قناة مخصصة تعمل على تشغيل البث المباشر للقياس عن بعد. هذه القناة مستقلة عن قناة القياس عن بعد العادية، ولا ينطبق عليها هذا المستند.

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

يتم شحن Application Insights .NET و.NET Core SDKs مع قناتين مضمنتين:

  • InMemoryChannel: قناة خفيفة الوزن تقوم بتخزين العناصر في الذاكرة مؤقتا حتى يتم إرسالها. يتم تخزين العناصر مؤقتا في الذاكرة ومسحها مرة كل 30 ثانية، أو كلما تم تخزين 500 عنصر. توفر هذه القناة الحد الأدنى من ضمانات الموثوقية لأنها لا تعيد محاولة إرسال بيانات تتبع الاستخدام بعد الفشل. لا تحتفظ هذه القناة أيضا بالعناصر على القرص. لذلك يتم فقد أي عناصر غير مرسلة بشكل دائم عند إيقاف تشغيل التطبيق ، سواء كانت رشيقة أم لا. تنفذ هذه القناة طريقة Flush() يمكن استخدامها لفرض المسح التدريجي لأي عناصر بيانات تتبع الاستخدام في الذاكرة بشكل متزامن. هذه القناة مناسبة تماما للتطبيقات قصيرة المدى حيث يكون التدفق المتزامن مثاليا.

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

  • ServerTelemetryChannel: قناة أكثر تقدما تحتوي على نهج إعادة المحاولة والقدرة على تخزين البيانات على قرص محلي. تعيد هذه القناة محاولة إرسال بيانات تتبع الاستخدام في حالة حدوث أخطاء عابرة. تستخدم هذه القناة أيضا تخزين القرص المحلي للاحتفاظ بالعناصر على القرص أثناء انقطاع الشبكة أو وحدات تخزين بيانات تتبع الاستخدام العالية. بسبب آليات إعادة المحاولة هذه وتخزين القرص المحلي ، تعتبر هذه القناة أكثر موثوقية. نوصي به لجميع سيناريوهات الإنتاج. هذه القناة هي الإعداد الافتراضي للتطبيقات الأساسية ASP.NET و ASP.NET التي تم تكوينها وفقا للوثائق الرسمية. تم تحسين هذه القناة لسيناريوهات الخادم ذات العمليات طويلة الأمد. الطريقة Flush() التي تنفذها هذه القناة ليست متزامنة.

    يتم شحن هذه القناة كحزمة Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel NuGet ويتم الحصول عليها تلقائيا عند استخدام حزمة Microsoft.ApplicationInsights.Web أو Microsoft.ApplicationInsights.AspNetCore NuGet.

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

يمكنك تكوين قناة بيانات تتبع الاستخدام عن طريق تعيينها إلى تكوين بيانات تتبع الاستخدام النشطة. بالنسبة للتطبيقات ASP.NET، يتضمن التكوين تعيين مثيل قناة بيانات تتبع الاستخدام على TelemetryConfiguration.Active أو عن طريق التعديل ApplicationInsights.config. بالنسبة للتطبيقات الأساسية ASP.NET، يتضمن التكوين إضافة القناة إلى حاوية حقن التبعية.

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

ASP.NET

الخيار 1: التكوين في التعليمات البرمجية

تقوم التعليمات البرمجية التالية بإعداد ServerTelemetryChannel مثيل يتم StorageFolder تعيينه على موقع مخصص. أضف هذا الرمز في بداية التطبيق، عادة في Application_Start() الطريقة الموجودة في Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

الخيار 2: التكوين في ApplicationInsights.config

يعرض القسم التالي من ApplicationInsights.config القناة التي ServerTelemetryChannel تم ضبطها مع StorageFolder التعيين على موقع مخصص:

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>
ASP.NET Core

قم بتعديل ConfigureServices طريقة الفئة Startup.cs كما هو موضح هنا:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

هام

تكوين القناة باستخدام TelemetryConfiguration.Active غير مدعوم للتطبيقات الأساسية ASP.NET.

تجاوز ServerTelemetryChannel

قناة بيانات تتبع الاستخدامالافتراضية هي 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 في تطبيق يتم إيقاف تشغيله.

خدمة العمال

القناة الافتراضية هي ServerTelemetryChannel. يمكنك تجاوزه كما يوضح المثال التالي:

using Microsoft.ApplicationInsights.Channel;

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

        services.AddApplicationInsightsTelemetryWorkerService();
    }

التكوين في التعليمات البرمجية لتطبيقات وحدة التحكم

بالنسبة لتطبيقات وحدة التحكم، تكون التعليمات البرمجية هي نفسها لكل من .NET و .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

التفاصيل التشغيلية ل ServerTelemetryChannel

ServerTelemetryChannel يخزن العناصر الواردة في مخزن مؤقت في الذاكرة. يتم تسلسل العناصر وضغطها وتخزينها في مثيل Transmission مرة كل 30 ثانية، أو عند تخزين 500 عنصر. يحتوي المثيل الفردي Transmission على ما يصل إلى 500 عنصر ويمثل مجموعة من بيانات تتبع الاستخدام التي يتم إرسالها عبر مكالمة HTTPS واحدة إلى خدمة Application Insights.

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

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

الإعدادات القابلة للتكوين في القنوات

للحصول على القائمة الكاملة للإعدادات القابلة للتكوين لكل قناة، راجع:

فيما يلي الإعدادات الأكثر استخداما ل ServerTelemetryChannel:

  • MaxTransmissionBufferCapacityالحد الأقصى لمقدار الذاكرة، بالبايت، الذي تستخدمه القناة لتخزين الإرسالات في الذاكرة.: عند الوصول إلى هذه السعة، يتم تخزين العناصر الجديدة مباشرة على القرص المحلي. القيمة الافتراضية هي 5 ميغابايت. يؤدي تعيين قيمة أعلى إلى تقليل استخدام القرص، ولكن تذكر أن العناصر الموجودة في الذاكرة تفقد في حالة تعطل التطبيق.

  • MaxTransmissionSenderCapacityالحد الأقصى لعدد المثيلات Transmission التي يتم إرسالها إلى Application Insights في نفس الوقت.: القيمة الافتراضية هي 10. يمكن تكوين هذا الإعداد إلى رقم أعلى، وهو ما نوصي به عند إنشاء حجم ضخم من بيانات تتبع الاستخدام. يحدث الحجم الكبير عادة أثناء اختبار الحمل أو عند إيقاف تشغيل أخذ العينات.

  • StorageFolderالمجلد الذي تستخدمه القناة لتخزين العناصر على القرص حسب الحاجة.: في Windows، يتم استخدام %LOCALAPPDATA% أو %TEMP% إذا لم يتم تحديد مسار آخر بشكل صريح. في البيئات الأخرى غير Windows، يتم استخدام المواقع التالية بشكل افتراضي (بالترتيب): %TMPDIR%أو /var/tmp/ أو /tmp/.

ما هي القناة التي يجب أن أستخدمها؟

نوصي ServerTelemetryChannel بمعظم سيناريوهات الإنتاج التي تتضمن تطبيقات طويلة الأمد. لمزيد من المعلومات حول التنظيف عن بعد ، اقرأ عن استخدام Flush().

متى تستخدم Flush()

ترسل الطريقة Flush() أي بيانات تتبع الاستخدام المخزنة على الفور. ومع ذلك ، يجب استخدامه فقط في سيناريوهات محددة.

استخدم Flush() عندما:

  • التطبيق على وشك إيقاف التشغيل وتريد التأكد من إرسال بيانات تتبع الاستخدام قبل الخروج.
  • أنت في معالج استثناء وتحتاج إلى ضمان تسليم بيانات تتبع الاستخدام.
  • أنت تكتب عملية قصيرة العمر مثل وظيفة في الخلفية أو أداة CLI التي تخرج بسرعة.

تجنب الاستخدام Flush() في التطبيقات طويلة الأمد مثل خدمات الويب. تدير SDK التخزين المؤقت والإرسال تلقائيا. يمكن أن يتسبب الاتصال Flush() دون داع في حدوث مشكلات في الأداء ولا يضمن إرسال جميع البيانات ، خاصة عند الاستخدام ServerTelemetryChannel، والذي لا يتم تسويطه بشكل متزامن.

وحدات القياس عن بعد

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

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

ASP.NET

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

منطقة الوصف
تتبع الطلب يجمع بيانات تتبع الاستخدام للطلب (وقت الاستجابة، رمز النتيجة) لطلبات الويب الواردة.

الوحده النمطيه:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
تتبع التبعية يجمع بيانات تتبع الاستخدام حول التبعيات الصادرة (مكالمات HTTP ومكالمات SQL). للعمل في IIS، قم بتثبيت Application Insights Agent. يمكنك أيضا كتابة تعقب تبعية مخصص باستخدام واجهة برمجة تطبيقات TrackDependency. يدعم الأجهزة التلقائية مع App Serviceوالأجهزة الظاهرية ومراقبة مجموعات مقياس الجهاز الظاهري.

الوحده النمطيه:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.DependencyCollector
عدادات الأداء يجمع عدادات أداء Windows (وحدة المعالجة المركزية ، الذاكرة ، حمل الشبكة من عمليات تثبيت IIS). حدد العدادات (بما في ذلك العدادات المخصصة). لمزيد من المعلومات، راجع تجميع عدادات أداء النظام.

الوحده النمطيه:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
عدادات الفعاليات يجمع .NET EventCounters. موصى به ل ASP.NET Core وعبر الأنظمة الأساسية بدلا من عدادات أداء Windows.

الوحده النمطيه:EventCounterCollectionModule (SDK ≥ 2.8.0)
المقاييس الحية (QuickPulse) يجمع بيانات تتبع الاستخدام لجزء المقاييس المباشرة.

الوحده النمطيه:QuickPulseTelemetryModule
نبضات القلب (خدمة التطبيقات) يرسل نبضات القلب والمقاييس المخصصة لبيئة App Service.

الوحده النمطيه:AppServicesHeartbeatTelemetryModule
نبضات القلب (الأجهزة الظاهرية ومجموعات مقياس الجهاز الظاهري) يرسل نبضات القلب والمقاييس المخصصة لبيئة Azure VM.

الوحده النمطيه:AzureInstanceMetadataTelemetryModule
القياس عن بعد للتشخيص الإبلاغ عن الأخطاء في التعليمات البرمجية لأجهزة Application Insights (على سبيل المثال، العدادات المفقودة والاستثناءات ITelemetryInitializer ). يظهر تتبع بيانات تتبع الاستخدام في البحث التشخيصي.

الوحده النمطيه:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet:Microsoft.ApplicationInsights

ملاحظه: إذا قمت بتثبيت هذه الحزمة فقط، فلن يتم إنشاء ملف ApplicationInsights.config تلقائيا.
وضع المطور (مرفق مصحح الأخطاء) فرض على TelemetryChannel إرسال العناصر على الفور عند إرفاق مصحح الأخطاء. يقلل من زمن الوصول ولكنه يزيد من النفقات العامة لوحدة المعالجة المركزية / الشبكة.

الوحده النمطيه:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet:Application Insights Windows Server
تعقب الاستثناءات (الويب) يتتبع الاستثناءات غير المعالجة في تطبيقات الويب. راجع حالات الفشل والاستثناءات.

الوحده النمطيه:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
تعقب الاستثناءات (غير ملاحظ/غير معالج) يتعقب استثناءات المهام غير الملحوظة والاستثناءات غير المعالجة لأدوار العامل وخدمات Windows وتطبيقات وحدة التحكم.

وحدات:
 • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule
 • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule
NuGet:Microsoft.ApplicationInsights.WindowsServer
تعقب EventSource يرسل أحداث EventSource التي تم تكوينها إلى Application Insights كتتبعات.

الوحده النمطيه:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet:Microsoft.ApplicationInsights.EventSourceListener
جامع ETW يرسل أحداث موفر ETW التي تم تكوينها إلى Application Insights كتتبعات.

الوحده النمطيه:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet:Microsoft.ApplicationInsights.EtwCollector
واجهة برمجة التطبيقات الأساسية (ليست وحدة نمطية) واجهة برمجة التطبيقات الأساسية المستخدمة من قبل مكونات تتبع الاستخدام الأخرى وللقياس عن بعد المخصص.

الوحده النمطيه:Microsoft.ApplicationInsights package
NuGet:Microsoft.ApplicationInsights
ملاحظه: إذا قمت بتثبيت هذه الحزمة فقط، فلن يتم إنشاء ملف ApplicationInsights.config تلقائيا.
ASP.NET Core
منطقة الوصف
تتبع الطلب تعقب الطلبات المضمن عبر تكامل ASP.NET Core Application Insights.

الوحدة:لا توجد فئة وحدة منفصلة.
NuGet:Microsoft.ApplicationInsights.AspNetCore
تتبع التبعية عبر جامع التبعية.

NuGet:Microsoft.ApplicationInsights.DependencyCollector
عدادات الأداء Windows فقط! عبر الأنظمة الأساسية ، استخدم EventCounterCollectionModule (انظر الصف التالي).

NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
عدادات الفعاليات يجمع .NET EventCounters. موصى به ل ASP.NET Core وعبر الأنظمة الأساسية بدلا من عدادات أداء Windows.

الوحده النمطيه:EventCounterCollectionModule (SDK 2.8.0 والإصدارات الأحدث)
NuGet:Microsoft.ApplicationInsights.EventCounterCollector
المقاييس الحية (QuickPulse) تمكين المقاييس المباشرة في تكامل ASP.NET Core Application Insights.

الوحدة:لا توجد فئة وحدة منفصلة.
NuGet:Microsoft.ApplicationInsights.AspNetCore
جامع نبضات القلب (خدمة التطبيقات) يرسل نبضات القلب (كمقاييس مخصصة) مع تفاصيل حول بيئة App Service. مضمن عبر SDK الأساسي عند استضافته في App Service.

الوحدة:لا توجد فئة وحدة منفصلة.
NuGet:Microsoft.ApplicationInsights.AspNetCore
مجمع نبضات القلب (الأجهزة الظاهرية ومجموعات مقياس الجهاز الظاهري) يرسل دقات القلب (كمقاييس مخصصة) مع تفاصيل حول بيئة Azure VM. مضمن عبر SDK الأساسي عند استضافته على أجهزة Azure الظاهرية ومجموعات مقياس الجهاز الظاهري Azure.

الوحدة:لا توجد فئة وحدة منفصلة.
NuGet:Microsoft.ApplicationInsights.AspNetCore
القياس عن بعد للتشخيص يبلغ عن أخطاء في التعليمات البرمجية لأجهزة Application Insights نفسها (على سبيل المثال، لا يمكن الوصول إلى عدادات الأداء، ITelemetryInitializer وطرح استثناء). يظهر تتبع بيانات تتبع الاستخدام في البحث التشخيصي.

الوحده النمطيه:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet:Microsoft.ApplicationInsights
وضع المطور (مرفق مصحح الأخطاء) نفس السلوك المتاح ؛ الفئة جزء من حزمة Windows Server.

الوحده النمطيه:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet:Microsoft.ApplicationInsights.WindowsServer
تعقب الاستثناءات (الويب) تعقب الاستثناءات التلقائي في تكامل ASP.NET Core Application Insights

الوحدة:لا توجد فئة وحدة منفصلة.
NuGet:Microsoft.ApplicationInsights.AspNetCore
تعقب الاستثناءات (غير ملاحظ/غير معالج) سلوك مماثل عبر وقت التشغيل/التكامل ASP.NET Core ؛ أسماء الفئات خاصة ب Windows Server.

NuGet:Microsoft.ApplicationInsights.WindowsServer
تعقب EventSource يرسل أحداث EventSource التي تم تكوينها إلى Application Insights كتتبعات.

الوحده النمطيه:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet:Microsoft.ApplicationInsights.EventSourceListener
جامع ETW نظام التشغيل Windows فقط (ETW). يرسل أحداث موفر ETW التي تم تكوينها إلى Application Insights كتتبعات.

الوحده النمطيه:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet:Microsoft.ApplicationInsights.EtwCollector
واجهة برمجة التطبيقات الأساسية (ليست وحدة نمطية) واجهة برمجة التطبيقات الأساسية المستخدمة من قبل مكونات تتبع الاستخدام الأخرى وللقياس عن بعد المخصص.

الوحده النمطيه:Microsoft.ApplicationInsights package
NuGet:Microsoft.ApplicationInsights

تكوين وحدات القياس عن بعد

ASP.NET

استخدم القسم TelemetryModules الموجود فيApplicationInsights.config لتكوين الوحدات النمطية أو إضافتها أو إزالتها. الأمثلة التالية:

  • تكوين DependencyTrackingTelemetryModule (تمكين حقن رأس W3C).
  • التكوين EventCounterCollectionModule (مسح الإعدادات الافتراضية وإضافة عداد واحد).
  • تعطيل مجموعة perf-counter عن طريق إزالة PerformanceCollectorModule.
<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

ملاحظة

تعتمد المجموعة الدقيقة من الوحدات النمطية الموجودة في الخاص بك ApplicationInsights.config على حزم SDK التي قمت بتثبيتها.

ASP.NET Core

الخيار 1: تكوين وحدات القياس عن بعد باستخدام ConfigureTelemetryModule

لتكوين أي افتراضي 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: تكوين وحدات القياس عن بعد باستخدام ApplicationInsightsServiceOptions

في الإصدارات 2.12.2 من SDK والإصدارات الأحدث، يمكنك تعديل بعض الإعدادات الشائعة عن طريق المرور 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 صواب
تمكينAzureInstanceMetadataTelemetryModule تمكين/تعطيلAzureInstanceMetadataTelemetryModule صواب
تمكين QuickPulseMetricStream تمكين/تعطيل ميزة LiveMetrics. صواب
EnableAdaptiveSampling تمكين/تعطيل أخذ العينات التكيفية. صواب
EnableHeartbeat تمكين/تعطيل ميزة رسالة كشف أخطاء الاتصال. يرسل بشكل دوري (افتراضي 15 دقيقة) مقياسا مخصصا يسمى HeartbeatState بمعلومات حول وقت التشغيل مثل إصدار .NET ومعلومات بيئة Azure، إن أمكن. صواب
AddAutoCollectedMetricExtractor تمكين/تعطيل AutoCollectedMetrics extractor. يرسل معالج بيانات تتبع الاستخدام هذا مقاييس مجمعة مسبقا حول الطلبات/التبعيات قبل أخذ العينات. صواب
طلبCollectionOptions.TrackExceptions تمكين/تعطيل الإبلاغ عن تتبع الاستثناء غير المعالج بواسطة وحدة مجموعة الطلب. خطأ في netstandard2.0 (لأنه يتم تعقب الاستثناءات باستخدام ApplicationInsightsLoggerProvider). صحيح خلاف ذلك.
تمكينDiagnosticsTelemetryModule تمكين/تعطيل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": "<YOUR-CONNECTION-STRING>",
    "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.

خدمة العمال

الخيار 1: تكوين وحدات القياس عن بعد باستخدام ConfigureTelemetryModule

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

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

  • DependencyTrackingTelemetryModule
  • PerformanceCollectorModule
  • QuickPulseTelemetryModule
  • AppServicesHeartbeatTelemetryModule (توجد حاليا مشكلة تتعلق بوحدة القياس عن بعد هذه. للحصول على حل بديل مؤقت، راجع الإصدار 1689 من GitHub.)
  • AzureInstanceMetadataTelemetryModule

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

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "<YOUR-API-KEY-HERE>";
            });

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

الخيار 2: تكوين وحدات القياس عن بعد باستخدام ApplicationInsightsServiceOptions

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

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

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

ApplicationInsightsServiceOptions موجودة في SDK هذه في مساحة Microsoft.ApplicationInsights.WorkerService الاسم بدلا من Microsoft.ApplicationInsights.AspNetCore.Extensions ASP.NET Core SDK.

يسرد الجدول التالي الإعدادات شائعة الاستخدام في ApplicationInsightsServiceOptions.

اعداد الوصف افتراضي
تمكين QuickPulseMetricStream تمكين/تعطيل ميزة المقاييس المباشرة. صواب
EnableAdaptiveSampling تمكين/تعطيل أخذ العينات التكيفية. صواب
EnableHeartbeat تمكين/تعطيل ميزة Heartbeats، والتي ترسل بشكل دوري (افتراضي مدته 15 دقيقة) مقياسا مخصصا باسم "HeartBeatState" مع معلومات حول وقت التشغيل مثل إصدار .NET وبيئة Azure، إن أمكن. صواب
AddAutoCollectedMetricExtractor تمكين/تعطيل مستخرج AutoCollectedMetrics، وهو معالج قياس عن بعد يرسل مقاييس مجمعة مسبقا حول الطلبات/التبعيات قبل إجراء أخذ العينات. صواب
تمكينDiagnosticsTelemetryModule تمكين/تعطيلDiagnosticsTelemetryModule يؤدي تعطيل هذا الإعداد إلى تجاهل الإعدادات التالية: EnableHeartbeat، EnableAzureInstanceMetadataTelemetryModuleو و EnableAppServicesHeartbeatTelemetryModule. صواب

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

تعطيل القياس عن بعد

ASP.NET

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

ASP.NET Core

إذا كنت تريد تعطيل بيانات تتبع الاستخدام بشكل مشروط وديناميكي، فيمكنك 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. لا يمنع أي وحدات جمع تلقائية من جمع بيانات تتبع الاستخدام. إذا كنت ترغب في إزالة وحدة نمطية معينة للتجميع التلقائي، فراجع وحدات القياس عن بعد.

خدمة العمال

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

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

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

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

راجع سلاسل الاتصال في Application Insights للحصول على نماذج التعليمات البرمجية.

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

ASP.NET

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

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "<YOUR-CONNECTION-STRING>";
        var telemetryClient = new TelemetryClient(configuration);

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


    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
    tc.TrackEvent("myEvent");
    // ...

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

ASP.NET Core

في ASP.NET Core، قم بتكوين سلسلة الاتصال أثناء Program.cs بدء تشغيل التطبيق باستخدام TelemetryConfiguration حاوية حقن التبعية (DI):

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

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";

app.Run();

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

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
tc.TrackEvent("myEvent");
// ...

موفر ApplicationId

ملاحظة

بالنسبة إلى ASP.NET، يتوفر هذا الموفر بدءا من SDK v2.6.0*.

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

هذه الوظيفة متاحة عن طريق الإعداد TelemetryConfiguration.ApplicationIdProvider.

الواجهة: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string connectionString, 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} يتم استبداله بسلسلة الاتصال لكل طلب.

ASP.NET

مثال على التكوين عبر 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();
ASP.NET Core

ملاحظة

في ASP.NET Core ، لا يوجد ملف ApplicationInsights.config . يتم التكوين من خلال حقن التبعية (DI) في Program.cs أو Startup.cs.

يمكنك تجاوز الموفر الافتراضي أو تخصيص .ProfileQueryEndpoint

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

DictionaryApplicationIdProvider

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

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

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

ASP.NET

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

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="ConnectionString_1" value="ApplicationId_1"/>
            <Type key="ConnectionString_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>
    {
        {"ConnectionString_1", "ApplicationId_1"},
        {"ConnectionString_2", "ApplicationId_2"}
    }
};
ASP.NET Core
using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "ConnectionString_1", "ApplicationId_1" },
            { "ConnectionString_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

إضافة مراقبة من جانب العميل

قدمت الأقسام السابقة إرشادات حول أساليب تكوين المراقبة من جانب الخادم تلقائيًا ويدويًا. لإضافة مراقبة من جانب العميل، استخدم JavaScript SDK من جانب العميل. يمكنك مراقبة أي معاملات من جانب العميل لصفحة ويب عن طريق إضافة برنامج JavaScript (Web) SDK Loader Script قبل علامة إغلاق </head> HTML للصفحة.

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

ASP.NET

بالنسبة إلى تطبيق MVC لـ ASP.NET المستند إلى القالب من هذه المقالة، الملف الذي تحتاج إلى تحريره هو _Layout.cshtml. يمكنك العثور عليه ضمن المشاهدات>المشتركة. لإضافة مراقبة من جانب العميل، افتح _Layout.cshtml واتبع تعليمات الإعداد المستندة إلى برنامج JavaScript (Web) SDK Loader Script من المقالة حول تكوين JavaScript SDK من جانب العميل.

ASP.NET Core

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

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

ملاحظة

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

واجهة برمجة التطبيقات الأساسية للأحداث والمقاييس المخصصة

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

ملخص واجهة برمجة التطبيقات

واجهة برمجة التطبيقات الأساسية موحدة عبر جميع الأنظمة الأساسية ، باستثناء بعض الاختلافات مثل GetMetric (.NET فقط).

الأسلوب تستخدم ل
TrackPageView الصفحات أو الشاشات أو الأجزاء أو النماذج.
TrackEvent إجراءات المستخدم والأحداث الأخرى. تستخدم لتتبع سلوك المستخدم أو لمراقبة الأداء.
GetMetric مقاييس صفرية ومتعددة الأبعاد، تجميع تم تكوينه مركزيا، C# فقط.
TrackMetric قياسات الأداء، مثل أطوال قوائم الانتظار غير المرتبطة بأحداث محددة.
TrackException تسجيل استثناءات للتشخيص. تتبع مكان حدوثها فيما يتعلق بالأحداث الأخرى وفحص آثار المكدس.
TrackRequest تسجيل تكرار ومدة طلبات الخادم لتحليل الأداء.
TrackTrace رسائل سجل تشخيص الموارد. يمكنك أيضا التقاط سجلات الجهات الخارجية.
TrackDependency تسجيل مدة وتكرار المكالمات إلى المكونات الخارجية التي يعتمد عليها تطبيقك.

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

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

إذا لم يكن لديك مرجع حول Application Insights SDK حتى الآن:

  1. أضف Application Insights SDK إلى مشروعك.

  2. في رمز جهازك أو خادم الويب، قم بما يلي:

    using Microsoft.ApplicationInsights;

الحصول على مثيل TelemetryClient

احصل على مثيل ل TelemetryClient:

ملاحظة

إذا كنت تستخدم Azure Functions v2+ أو Azure WebJobs v3+، فراجع مراقبة Azure Functions.

ملاحظة

بالنسبة ASP.NET Core وNon-HTTP/Worker لتطبيقات .NET/.NET Core، احصل على مثيل TelemetryClient من حاوية حقن التبعية كما هو موضح في الوثائق الخاصة بها.

private TelemetryClient telemetry = new TelemetryClient();

إذا رأيت رسالة تخبرك بأن هذا الأسلوب قديم، فراجع microsoft/ApplicationInsights-dotnet#1152 للحصول على مزيد من المعلومات.

يتم التقاط طلبات HTTP الواردة تلقائيا. قد ترغب في إنشاء المزيد من المثيلات للوحدات TelemetryClient النمطية الأخرى لتطبيقك. على سبيل المثال، قد يكون لديك مثيل واحد TelemetryClient في فئة البرامج الوسيطة للإبلاغ عن أحداث منطق الأعمال. يمكنك تعيين خصائص مثل UserId وتحديد DeviceId الجهاز. يتم إرفاق هذه المعلومات بجميع الأحداث التي يرسلها المثيل.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

ملاحظة

TelemetryClient هو الخيط آمنة.

TrackEvent

في Application Insights، الحدث المخصص هو نقطة بيانات يمكنك عرضها في Metrics Explorer كعدد مجمع وفي البحث التشخيصي كتكرارات فردية. (لا يتعلق الأمر ب MVC أو "أحداث" إطار عمل أخرى.)

أدخل TrackEvent المكالمات في التعليمات البرمجية الخاصة بك لحساب الأحداث المختلفة. على سبيل المثال، قد ترغب في تتبع عدد المرات التي يختار فيها المستخدمون ميزة معينة. أو قد ترغب في معرفة عدد المرات التي يحققون فيها أهدافا معينة أو يرتكبون أنواعا معينة من الأخطاء.

على سبيل المثال، في تطبيق ألعاب، أرسل حدثا عندما يفوز مستخدم باللعبة:

telemetry.TrackEvent("WinGame");

الأحداث المخصصة في Log Analytics

يتوفر بيانات تتبع الاستخدام في customEvents الجدول الموجود في علامة التبويب Application Insights Logs أو تجربة الاستخدام. قد تأتي الأحداث من trackEvent(..)المكون الإضافي Click Autocollection أو من "إحصاءات النقرات".

إذا كان أخذ العينات قيد التشغيل، تعرض itemCount الخاصية قيمة أكبر من 1. على سبيل المثال ، itemCount==10 يعني أنه من بين 10 مكالمات إلى trackEvent()، ترسل عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح للأحداث المخصصة، استخدم رمزا مثل customEvents | summarize sum(itemCount).

ملاحظة

itemCount له قيمة لا تقل عن واحد؛ يمثل السجل نفسه إدخالا.

GetMetric

لمعرفة كيفية استخدام المكالمة GetMetric() بشكل فعال لالتقاط المقاييس المجمعة محليا لتطبيقات .NET و.NET Core، راجع مجموعة المقاييس المخصصة في .NET و.NET Core.

تراك متري

ملاحظة

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric ليست الطريقة المفضلة لإرسال المقاييس. يجب دائما تجميع المقاييس مسبقا عبر فترة زمنية قبل إرسالها. استخدم أحد الأحمال GetMetric(..) الزائدة للحصول على كائن متري للوصول إلى إمكانات التجميع المسبق ل SDK.

إذا كنت تقوم بتنفيذ منطق التجميع المسبق الخاص بك، فيمكنك استخدام الطريقة TrackMetric() لإرسال التجميعات الناتجة. إذا كان التطبيق الخاص بك يتطلب إرسال عنصر بيانات تتبع الاستخدام منفصل في كل مناسبة دون التجميع عبر الوقت، فمن المحتمل أن يكون لديك حالة استخدام للقياس عن بعد للحدث. راجع TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

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

لإرسال المقاييس إلى Application Insights، يمكنك استخدام TrackMetric(..) واجهة برمجة التطبيقات. هناك طريقتان لإرسال مقياس:

  • قيمة واحدة. في كل مرة تقوم فيها بإجراء قياس في التطبيق الخاص بك، ترسل القيمة المقابلة إلى Application Insights.

    على سبيل المثال، افترض أن لديك مقياسا يصف عدد العناصر الموجودة في حاوية. خلال فترة زمنية معينة ، تضع أولا ثلاثة عناصر في الحاوية ثم تقوم بإزالة عنصرين. وفقا لذلك ، ستتصل TrackMetric مرتين. أولا ، ستقوم بتمرير القيمة 3 ثم تمرير القيمة -2. يخزن Application Insights كلتا القيمتين لك.

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

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

أمثلة على القيمة الفردية

لإرسال قيمة مقياس واحدة:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

المقاييس المخصصة في Log Analytics

يتوفر بيانات تتبع الاستخدام في الجدول customMetrics في Application Insights Analytics. يمثل كل صف مكالمة في trackMetric(..) تطبيقك.

  • valueSumمجموع القياسات.: للحصول على القيمة المتوسطة ، اقسم على valueCount.
  • valueCountعدد القياسات التي تم تجميعها في هذه trackMetric(..) المكالمة.:

ملاحظة

valueCount لها قيمة لا تقل عن واحد. يمثل السجل نفسه إدخالا.

عرض الصفحة

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

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

مشاهدات الصفحة المخصصة

telemetry.TrackPageView("GameReviewPage");

بيانات تتبع الاستخدام للصفحة في Log Analytics

في Log Analytics، يعرض جدولان بيانات من عمليات المستعرض:

  • pageViewsيحتوي على بيانات حول عنوان URL وعنوان الصفحة.:
  • browserTimingsيحتوي على بيانات حول أداء العميل مثل الوقت المستغرق لمعالجة البيانات الواردة.:

لمعرفة المدة التي يستغرقها المتصفح لمعالجة الصفحات المختلفة:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

لاكتشاف شعبية المتصفحات المختلفة:

pageViews
| summarize count() by client_Browser

لإقران مشاهدات الصفحة بمكالمات AJAX، انضم إلى التبعيات:

pageViews
| join (dependencies) on operation_Id

طلب التتبع

تستخدم TrackRequest SDK للخادم لتسجيل طلبات HTTP.

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

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

سياق التشغيل

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

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

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

لمزيد من المعلومات حول الارتباط، راجع ارتباط بيانات تتبع الاستخدام في Application Insights.

إلى جانب تعيين سياق عملية، StartOperation يقوم بإنشاء عنصر بيانات تتبع الاستخدام من النوع الذي تحدده. يرسل عنصر القياس عن بعد عند التخلص من العملية أو إذا قمت باستدعاء StopOperation. إذا كنت تستخدم RequestTelemetry كنوع بيانات تتبع الاستخدام، تعيين مدته على الفاصل الزمني المحدد بين البدء والإيقاف.

تصبح عناصر القياس عن بعد التي تم الإبلاغ عنها في نطاق التشغيل من أبناء مثل هذه العملية. يمكن أن تكون سياقات العمليات متداخلة.

في البحث، يتم استخدام سياق العملية لإنشاء قائمة العناصر ذات الصلة .

لقطة شاشة تعرض قائمة العناصر ذات الصلة.

لمزيد من المعلومات حول تعقب العمليات المخصصة، راجع تعقب العمليات المخصصة باستخدام Application Insights .NET SDK.

الطلبات في Log Analytics

في Application Insights، تظهر الطلبات requests في الجدول.

إذا كان أخذ العينات قيد التشغيل، تعرض itemCount الخاصية قيمة أكبر من 1. على سبيل المثال ، itemCount==10 يعني أنه من بين 10 مكالمات إلى trackRequest()، ترسل عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح من الطلبات ومتوسط المدة مقسمة حسب أسماء الطلبات، استخدم رمزا مثل:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

إرسال الاستثناءات إلى Application Insights:

تتضمن التقارير آثار المكدس.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

تلتقط حزم SDK العديد من الاستثناءات تلقائيا، لذلك لا يتعين عليك دائما الاتصال TrackException بشكل صريح.

الاستثناءات في Log Analytics

في Application Insights، تظهر الاستثناءات في exceptions الجدول.

إذا كان أخذ العينات قيد التشغيل، تعرض itemCount الخاصية قيمة أكبر من 1. على سبيل المثال ، itemCount==10 يعني أنه من بين 10 مكالمات إلى trackException()، ترسل عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح من الاستثناءات مقسمة حسب نوع الاستثناء، استخدم تعليمات برمجية مثل:

exceptions
| summarize sum(itemCount) by type

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

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

لإقران الاستثناءات بطلباتها ذات الصلة، استخدم انضمام:

exceptions
| join (requests) on operation_Id

تتبع المسار

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

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

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

سجل حدثا تشخيصيا مثل إدخال طريقة أو مغادرتها.

المعلمة‬ الوصف
message البيانات التشخيصية. يمكن أن يكون أطول بكثير من الاسم.
properties خريطة من سلسلة إلى سلسلة. يتم استخدام المزيد من البيانات لتصفية الاستثناءات في المدخل. الإعداد الافتراضي إلى فارغ.
severityLevel القيم المدعومة: SeverityLevel.ts.

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

الحد message الأقصى للحجم أعلى بكثير من الحد الأقصى للخصائص. ميزة ذلك TrackTrace هي أنه يمكنك وضع بيانات طويلة نسبيا في الرسالة. على سبيل المثال ، يمكنك تشفير بيانات POST هناك.

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

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

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

التتبعات في Log Analytics

في Application Insights، يتم الاستدعاءات للظهور TrackTrace في traces الجدول.

إذا كان أخذ العينات قيد التشغيل، تعرض itemCount الخاصية قيمة أكبر من 1. على سبيل المثال ، itemCount==10 يعني أنه من بين 10 مكالمات إلى trackTrace()، ترسل عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح لمكالمات التتبع، استخدم التعليمات البرمجية مثل traces | summarize sum(itemCount).

التتبع التبعية

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

ملاحظة

بالنسبة إلى .NET و.NET Core، يمكنك بدلا من ذلك استخدام TelemetryClient.StartOperation الأسلوب (الملحق) الذي يملأ الخصائص DependencyTelemetry المطلوبة للارتباط وبعض الخصائص الأخرى مثل وقت البدء والمدة، لذلك لا تحتاج إلى إنشاء مؤقت مخصص كما هو الحال مع الأمثلة التالية. لمزيد من المعلومات، راجع القسم الخاص بتعقب التبعية الصادرة في تعقب العمليات المخصصة باستخدام Application Insights .NET SDK.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

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

يمكنك استخدام هذه المكالمة إذا كنت تريد تتبع المكالمات التي لا يلتقطها التتبع التلقائي.

لإيقاف تشغيل الوحدة النمطية لتتبع التبعية القياسية في C#، قم بتحرير ApplicationInsights.config وحذف المرجع إلى DependencyCollector.DependencyTrackingTelemetryModule.

التبعيات في Log Analytics

في Application Insights، trackDependency تظهر المكالمات في dependencies الجدول.

إذا كان أخذ العينات قيد التشغيل، تعرض itemCount الخاصية قيمة أكبر من 1. على سبيل المثال ، itemCount==10 يعني أنه من بين 10 مكالمات إلى trackDependency()، ترسل عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح من التبعيات مقسمة حسب المكون الهدف، استخدم التعليمات البرمجية مثل:

dependencies
| summarize sum(itemCount) by target

لإقران التبعيات بطلباتها ذات الصلة، استخدم ضم:

dependencies
| join (requests) on operation_Id

مسح البيانات

عادة ما ترسل SDK البيانات على فترات زمنية ثابتة، عادة 30 ثانية، أو عندما يكون المخزن المؤقت ممتلئا، وهو عادة 500 عنصر. في بعض الحالات ، قد ترغب في مسح المخزن المؤقت. مثال على ذلك إذا كنت تستخدم SDK في تطبيق يتم إيقاف تشغيله.

عند الاستخدام Flush()، نوصي بهذا النمط:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

عند الاستخدام FlushAsync()، نوصي بهذا النمط:

await telemetryClient.FlushAsync()
// No need to sleep

نوصي دائما بالتنظيف كجزء من إيقاف تشغيل التطبيق لضمان عدم فقدان بيانات تتبع الاستخدام.

ملاحظة

مراجعة تكوين المسح التلقائي: يمكن أن يؤدي تمكين المسح التلقائي في ملفك web.config إلى تدهور الأداء في تطبيقات .NET المزودة بنتائج تحليلات التطبيقات. مع تمكين المسح التلقائي، يؤدي كل استدعاء للطرق System.Diagnostics.Trace.Trace* إلى إرسال عناصر القياس عن بعد الفردية كطلبات ويب منفصلة مميزة إلى خدمة الاستيعاب. يمكن أن يتسبب هذا في استنفاد الشبكة ومساحة التخزين على خوادم الويب الخاصة بك. لتحسين الأداء ، يوصى بتعطيل التدفق التلقائي وأيضا استخدام ServerTelemetryChannel ، المصممة لنقل بيانات القياس عن بعد بشكل أكثر فعالية.

الوظيفة غير متزامنة لقناة القياس عن بعد للخادم.

المستخدمون المصادق عليهم

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

إذا سجل المستخدمون الدخول إلى تطبيقك، يمكنك الحصول على عدد أكثر دقة من خلال تعيين رقم تعريف المستخدم المصادق عليه في رمز المتصفح. ليس من الضروري استخدام اسم تسجيل الدخول الفعلي للمستخدم. يجب أن يكون فقط معرفا فريدا لهذا المستخدم. يجب ألا تتضمن مسافات أو أي من الأحرف ,;=|.

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

إذا كان تطبيقك يجمع المستخدمين في حسابات، يمكنك أيضا تمرير معرف للحساب. تنطبق نفس قيود الأحرف.

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

يمكنك أيضا البحث عن نقاط بيانات العميل بأسماء مستخدمين وحسابات محددة.

ملاحظة

تعمل الخاصية EnableAuthenticationTrackingJavaScript في الفئة ApplicationInsightsServiceOptions في .NET Core SDK على تبسيط تكوين JavaScript المطلوب لحقن اسم المستخدم كمعرف المصادقة لكل تتبع يتم إرساله بواسطة Application Insights JavaScript SDK.

عند تعيين هذه الخاصية إلى true، تتم طباعة اسم المستخدم من المستخدم في ASP.NET Core جنبا إلى جنب مع بيانات تتبع الاستخدام من جانب العميل. لهذا السبب، لم تعد الإضافة appInsights.setAuthenticatedUserContext يدويا مطلوبة بعد الآن لأنها تم إدخالها بالفعل بواسطة SDK ل ASP.NET Core. يتم أيضا إرسال معرف المصادقة إلى الخادم حيث تحدده SDK في .NET Core وتستخدمه لأي بيانات تتبع الاستخدام من جانب الخادم، كما هو موضح في مرجع واجهة برمجة تطبيقات JavaScript.

بالنسبة لتطبيقات JavaScript التي لا تعمل بنفس طريقة ASP.NET Core MVC، مثل تطبيقات ويب SPA، لا تزال بحاجة إلى الإضافة appInsights.setAuthenticatedUserContext يدويا.

تصفية بياناتك والبحث عنها وتقسيمها باستخدام المواقع

يمكنك إرفاق الخصائص والقياسات بالأحداث والمقاييس ومشاهدات الصفحة والاستثناءات وبيانات بيانات تتبع الاستخدام الأخرى.

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

هناك حد 8,192 على طول السلسلة. إذا كنت تريد إرسال أجزاء كبيرة من البيانات، فاستخدم معلمة message .TrackTrace

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

يجب أن تكون قيم المقياس أكبر من أو تساوي 0 لعرضها بشكل صحيح.

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

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

هام

تأكد من عدم تسجيل معلومات التعريف الشخصية في المواقع.

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

إذا كان الأمر أكثر ملاءمة، يمكنك جمع معلمات حدث في كائن منفصل:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

تحذير

لا تقم بإعادة استخدام مثيل عنصر القياس عن بعد نفسه (event في هذا المثال) للاتصال Track*() عدة مرات. قد تتسبب هذه الممارسة في إرسال بيانات تتبع الاستخدام بتكوين غير صحيح.

القياسات والمواقع المخصصة في Log Analytics

في Log Analytics، تظهر المقاييس والخصائص المخصصة في customMeasurements سمات customDimensions كل سجل بيانات تتبع الاستخدام.

على سبيل المثال، إذا أضفت خاصية باسم "لعبة" إلى بيانات تتبع الاستخدام لطلبك، فإن هذا الاستعلام يحسب تكرارات القيم المختلفة ل "game" ويعرض متوسط "النتيجة" للمقياس المخصص:

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

لاحظ ما يلي:

  • عند استخراج قيمة من أو customDimensionscustomMeasurements JSON، يكون لها نوع ديناميكي، لذا يجب إرسالها tostring أو todouble.
  • لمراعاة إمكانية أخذ العينات ، لا sum(itemCount)تستخدم count() .

توقيت الأحداث

في بعض الأحيان تريد رسم المدة التي يستغرقها تنفيذ إجراء. على سبيل المثال، قد ترغب في معرفة المدة التي يستغرقها المستخدمون للنظر في الخيارات في اللعبة. للحصول على هذه المعلومات، استخدم معلمة القياس.

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

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

إذا كنت تريد تعيين قيم الخصائص التلقائية لبعض الأحداث المخصصة التي تكتبها، فقم بتعيينها في TelemetryClient مثيل. يتم إرفاقها بكل عنصر بيانات تتبع الاستخدام يتم إرساله من هذا العميل.

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

يمكن لاستدعاءات القياس عن بعد الفردية تجاوز القيم الافتراضية في قواميس الخصائص الخاصة بها.

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

تعطيل القياس عن بعد

لإيقاف وبدء جمع وإرسال بيانات تتبع الاستخدام ديناميكيا :

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

وضع المطور

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

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

تعيين مفتاح الأجهزة لبيانات تتبع الاستخدام المخصصة المحددة

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

سلسلة اتصال ديناميكية

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

بدلا من الحصول على مفتاح الأجهزة من ملف التكوين ، يمكنك تعيينه في التعليمات البرمجية الخاصة بك. قم بتعيين المفتاح في طريقة تهيئة، كما هو global.aspx.cs الحال في خدمة ASP.NET:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

سياق القياس عن بعد

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

telemetry.Context.Operation.Name = "MyOperationName";

إذا قمت بتعيين أي من هذه القيم بنفسك ، ففكر في إزالة السطر ذي الصلة من ApplicationInsights.config حتى لا يتم الخلط بين قيمك والقيم القياسية.

  • المكون: التطبيق وإصداره.
  • الجهاز: بيانات حول الجهاز الذي يعمل فيه التطبيق. في تطبيقات الويب، يتم إرسال القياس عن بعد هو الخادم أو الجهاز العميل.
  • InstrumentationKey: مورد Application Insights في Azure حيث يظهر بيانات تتبع الاستخدام. عادة ما يتم التقاطها من ApplicationInsights.config.
  • الموقع: الموقع الجغرافي للجهاز.
  • العملية: في تطبيقات الويب، طلب HTTP الحالي. في أنواع التطبيقات الأخرى، يمكنك ضبط هذه القيمة لتجميع الأحداث معا.
    • المعرف: قيمة تم إنشاؤها تربط الأحداث المختلفة بحيث يمكنك العثور على العناصر ذات الصلة عند فحص أي حدث في البحث التشخيصي.
    • الاسم: معرف، وعادة ما يكون عنوان URL لطلب HTTP.
    • SyntheticSource: إذا لم تكن فارغة أو فارغة، فهذه سلسلة تشير إلى أن مصدر الطلب قد تم تحديده على أنه روبوت أو اختبار ويب. بشكل افتراضي، يتم استبعاده من العمليات الحسابية في مستكشف المقاييس.
  • الجلسة: جلسة المستخدم. يتم تعيين المعرف إلى قيمة تم إنشاؤها، والتي يتم تغييرها عندما لا يكون المستخدم نشطا لفترة من الوقت.
  • المستخدم: معلومات المستخدم.

الحدود

هناك بعض الحدود على عدد المقاييس والأحداث لكل تطبيق، أي لكل سلسلة اتصال. تعتمد الحدود على خطة التسعير التي تختارها.

مورد الحد الافتراضي الحد الأقصى الإشعارات
إجمالي البيانات في اليوم 100 غيغابايت اتصل بالدعم. يمكنك تعيين حد أقصى لتقليل البيانات. إذا كنت بحاجة إلى مزيد من البيانات، فيمكنك زيادة الحد في المدخل حتى 1,000 جيجابايت. إذا كانت السعة أكبر من 1,000 جيجابايت، أرسل رسالة بريد إلكتروني إلى AIDataCap@microsoft.com.
Throttling 32,000 حدث / ثانية اتصل بالدعم. يتم قياس الحد على مدى دقيقة.
سجلات استبقاء البيانات من 30 إلى 730 يوما 730 يوما هذا المورد مخصص للسجلات.
مقاييس استبقاء البيانات 90 يوما 90 يوما هذا المورد مخصص ل Metrics Explorer.
توافر اختبار متعدد الخطوات الاستباق بالنتائج التفصيلية 90 يوما 90 يوما يوفر هذا المورد نتائج مفصلة لكل خطوة.
الحد الأقصى لحجم عنصر القياس عن بعد 64 كيلوبايت 64 كيلوبايت
الحد الأقصى من عناصر القياس عن بعد لكل دفعة 64,000 64,000
طول اسم الموقع والمقياس 150 150 انظر نوع المخططات.
طول سلسلة قيمة الخاصية 8,192 8,192 انظر نوع المخططات.
طول رسالة التتبع والاستثناء 32,768 32,768 انظر نوع المخططات.
يتم احتساب اختبارات التوفر لكل مورد Application Insights 100 100
عدد اختبارات التوفر لكل مجموعة موارد 800 800 راجع Azure Resource Manager
اختبارات التوفر الحد الأقصى لإعادة التوجيه لكل اختبار 10 10
اختبار التوفر الحد الأدنى من تكرار الاختبار 300 ثانية تتطلب ترددات الاختبار المخصصة أو الترددات التي تقل عن 5 دقائق تطبيقات TrackAvailability مخصصة .
.NET محلل ملفات التعريف واحتفاظ ببيانات مصحح أخطاء اللقطات أسبوعان اتصل بفريق الدعم. حد الإستبقاء الأقصى هو 6 أشهر.
بيانات محلل ملفات تعريف .NET المرسلة يوميا غير محدود لا حدود.
بيانات مصحح أخطاء اللقطات المرسلة يوميا 30 لقطة يوميًا لكل تطبيق مراقب لا حدود. يمكن تعديل عدد اللقطات التي تم جمعها لكل تطبيق من خلال التكوين.

للحصول على مزيدٍ من المعلومات عن التسعير والحصص، راجع فواتير Application Insights.

لتجنب الوصول إلى حد معدل البيانات، استخدم أخذ العينات.

لتحديد مدة الاحتفاظ بالبيانات، راجع الاحتفاظ بالبيانات والخصوصية.

نماذج التطبيقات

تطبيق وحدة تحكم .NET Core: استخدم هذا النموذج إذا كنت تستخدم تطبيق وحدة تحكم مكتوب بلغة .NET Core (2.0 أو أعلى) أو .NET Framework (4.7.2 أو أعلى).

ASP.NET مهام الخلفية الأساسية مع HostedServices: استخدم هذا النموذج إذا كنت في ASP.NET Core وتقوم بإنشاء مهام خلفية وفقا للإرشادات الرسمية.

.NET Core Worker Service: استخدم هذا النموذج إذا كان لديك تطبيق .NET Worker Service وفقا للإرشادات الرسمية.

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

راجع مقالات استكشاف الأخطاء وإصلاحها المخصصة ل .NET و Node.js.

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

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

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

اقرأ الكود الخاص ب .NET و Node.jsوالمساهمة فيه.

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

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

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

  • Last updated on