Monitorowanie aplikacji platformy .NET i Node.js za pomocą usługi Application Insights (klasyczny interfejs API)

Uwaga / Notatka

Zapoznaj się z wskazówkami dotyczącymi obsługi zestawu SDK dla usługi Application Insights, aby dowiedzieć się o naszej polityce wsparcia SDK dla Klasycznego API.

Ostrzeżenie

Zalecamy Azure Monitor OpenTelemetry Distro dla nowych aplikacji lub klientów w celu zwiększenia wydajności Azure Monitor Application Insights. Azure Monitor OpenTelemetry Distro zapewnia podobną funkcjonalność i doświadczenie jak SDK usługi Application Insights. Migracja z zestawu SDK usługi Application Insights jest możliwa przy użyciu przewodników migracji dla platformy .NET, Node.js i języka Python, ale nadal pracujemy nad dodaniem kilku dodatkowych funkcji w celu zapewnienia zgodności z poprzednimi wersjami.

W tym artykule wyjaśniono, jak włączyć i skonfigurować usługę Application Insights dla platformy .NET (ASP.NET, ASP.NET Core i aplikacji Worker Service) i aplikacji Node.js. Usługa Application Insights może zbierać następujące dane telemetryczne z aplikacji:

• Requests
• Zależności
• Exceptions
• Liczniki wydajności
• Ślady (dzienniki)
• Bicie serca
• Niestandardowe zdarzenia i metryki (wymagają instrumentacji ręcznej)
• Widoki stron (wymaga zestawu SDK języka JavaScript dla stron internetowych)
• Testy dostępności (wymagają ręcznego konfigurowania testów dostępności)

Obsługiwane scenariusze

.NET

Wsparte	ASP.NET	ASP.NET Core	Usługa procesu roboczego
System operacyjny	Windows	Windows, Linux lub macOS	Windows, Linux lub macOS
Metoda hostingu	W procesie wewnętrznym (IIS lub IIS Express)	W procesie lub poza procesem	Konsola lub usługa w tle (działa jako proces, zazwyczaj za pośrednictwem dotnet interfejsu wiersza polecenia lub jako demona systemu Windows/Linux)
Metoda wdrażania	Web Deploy, MSI lub ręczne kopiowanie plików	Struktura zależna lub samodzielna	Struktura zależna lub samodzielna
Serwer sieci Web	Internet Information Services (IIS)	Internet Information Server (IIS) lub Kestrel	Nie dotyczy (brak serwera internetowego; przeznaczony dla obciążeń innych niż HTTP, takich jak obsługa komunikatów, zadania w tle i aplikacje konsolowe)
Platforma hostingu	Azure App Service (Windows), Azure Virtual Machines lub serwery lokalne	Funkcja Web Apps usług Azure App Service, Azure Virtual Machines, Docker i Azure Kubernetes Service (AKS)	Azure Virtual Machines, Azure Kubernetes Service (AKS), kontenery lub dowolne środowisko, w którym jest obsługiwana platforma .NET Core
Wersja platformy .NET	.NET Framework 4.6.1 i nowsze	Wszystkie oficjalnie obsługiwane wersje platformy .NET , które nie są dostępne w wersji zapoznawczej	Wszystkie oficjalnie obsługiwane wersje platformy .NET , które nie są dostępne w wersji zapoznawczej
IDE	Visual Studio	Visual Studio, Visual Studio Code lub wiersz polecenia	Visual Studio, Visual Studio Code lub wiersz polecenia

Zestaw SDK usługi procesu roboczego nie wykonuje żadnego zbierania danych telemetrycznych. Zamiast tego wprowadza on inne dobrze znane moduły zbierające automatyczne usługi Application Insights, takie jak DependencyCollector, PerfCounterCollector i ApplicationInsightsLoggingProvider. Ten SDK udostępnia metody rozszerzenia na IServiceCollection aby włączyć i skonfigurować kolekcję danych telemetrycznych.

Uwaga / Notatka

Usługa pracownika to długo działająca aplikacja działająca w tle, która wykonuje zadania poza potokiem żądania/odpowiedzi HTTP. SDK Application Insights dla usług roboczych może być używany w nowo wprowadzonej usłudze roboczej .NET Core, zadaniach w tle w ASP.NET Core i aplikacjach konsolowych, takich jak te działające na .NET Core i .NET Framework.

Node.js

Wsparte	Node.js
System operacyjny	Windows, Linux lub macOS
Metoda hostingu	Konsola lub usługa w tle (uruchamia się jako proces za pomocą polecenia Node.js lub skryptów npm)
Metoda wdrażania	Zależne od platformy (wymaga Node.js środowiska uruchomieniowego zainstalowanego za pośrednictwem pakietu npm)
Serwer sieci Web	Wbudowany moduł HTTP lub frameworki webowe (Express, Fastify itp.) lub nie dotyczy zadań niezwiązanych z HTTP
Platforma hostingu	Azure App Service, Azure Virtual Machines, Azure Kubernetes Service (AKS), Docker, lokalnie lub w dowolnym środowisku, w którym jest obsługiwana Node.js
wersjaNode.js	Wszystkie oficjalnie obsługiwane wersje Node.js LTS (obecnie 18.19.0 lub 20.6.0+ dla zestawu SDK 3.X)
IDE	Visual Studio Code, Visual Studio lub wiersz polecenia

Biblioteka klienta Node.js może automatycznie monitorować przychodzące i wychodzące żądania HTTP, wyjątki i niektóre metryki systemowe. Począwszy od wersji 0.20, biblioteka kliencka może również monitorować niektóre typowe pakiety innych firm, takie jak MongoDB, MySQL i Redis.

Wszystkie zdarzenia związane z przychodzącym żądaniem HTTP są skorelowane, aby zapewnić szybsze rozwiązanie problemów.

Interfejs API TelemetryClient umożliwia ręczne instrumentowanie i monitorowanie większej liczby aspektów aplikacji i systemu. Interfejs API TelemetryClient został szczegółowo opisany w dalszej części tego artykułu.

Dodawanie usługi Application Insights

.NET

Wymagania wstępne

• Subskrypcja platformy Azure. Jeśli jeszcze go nie masz, utwórz bezpłatne konto platformy Azure.
• Zasób oparty na obszarze roboczym usługi Application Insights.
• Działająca aplikacja. Jeśli jeszcze go nie masz, zobacz Tworzenie podstawowej aplikacji internetowej.
• Najnowsza wersja programu Visual Studio z następującymi obciążeniami:
  • Tworzenie aplikacji na platformie ASP.NET i aplikacji internetowych
  • Programowanie na platformie Azure

Tworzenie podstawowej aplikacji internetowej

Jeśli nie masz jeszcze działającej aplikacji internetowej, możesz użyć poniższych wskazówek, aby je utworzyć.

ASP.NET

1. Otwórz program Visual Studio.
2. Wybierz pozycję Utwórz nowy projekt.
3. Wybierz pozycję ASP.NET Aplikacja internetowa (.NET Framework) z językiem C# , a następnie wybierz pozycję Dalej.
4. Wprowadź nazwę projektu, a następnie wybierz pozycję Utwórz.
5. Wybierz pozycję MVC, a następnie wybierz pozycję Utwórz.

ASP.NET Core

1. Otwórz program Visual Studio.
2. Wybierz pozycję Utwórz nowy projekt.
3. Wybierz ASP.NET Core Web App (Razor Pages) z językiem C# , a następnie wybierz przycisk Dalej.
4. Wprowadź nazwę projektu, a następnie wybierz pozycję Utwórz.
5. Wybierz platformę (LTS lub STS), a następnie wybierz pozycję Utwórz.

Automatyczne dodawanie usługi Application Insights (Visual Studio)

Ta sekcja przeprowadzi Cię przez proces automatycznego dodawania usługi Application Insights do aplikacji internetowej opartej na szablonach.

ASP.NET

Uwaga / Notatka

W programie Visual Studio 2019 występuje znany problem: przechowywanie klucza instrumentacji lub ciągu połączenia w sekrecie użytkownika nie działa dla aplikacji opartych na programie .NET Framework. Klucz musi być ostatecznie zakodowany w pliku Applicationinsights.config , aby obejść tę usterkę.

Z poziomu projektu aplikacji internetowej ASP.NET w programie Visual Studio:

1. Wybierz Projekt>Dodaj telemetrię Application Insights>Application Insights SDK (lokalnie)>Dalej>Zakończ>Zamknij.

2. Otwórz plik ApplicationInsights.config.

3. Przed tagiem zamykającym </ApplicationInsights> dodaj wiersz zawierający parametry połączenia dla zasobu usługi Application Insights. Znajdź parametry połączenia w okienku przeglądu nowo utworzonego zasobu usługi Application Insights.

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

4. Wybierz Projekt>Zarządzaj pakietami NuGet>Aktualizacje. Następnie zaktualizuj każdy Microsoft.ApplicationInsights pakiet NuGet do najnowszej stabilnej wersji.

5. Uruchom aplikację, wybierając pozycję IIS Express. Zostanie otwarta podstawowa aplikacja ASP.NET. Podczas przeglądania stron w witrynie dane telemetryczne są wysyłane do usługi Application Insights.

ASP.NET Core

Uwaga / Notatka

Jeśli chcesz użyć autonomicznego dostawcy ILogger dla aplikacji ASP.NET, użyj polecenia Microsoft.Extensions.Logging.ApplicationInsight.

Ważne

W przypadku programu Visual Studio dla systemu macOS skorzystaj z wskazówek ręcznych. Ta procedura jest obsługiwana tylko w wersji systemu Windows programu Visual Studio.

Z poziomu projektu aplikacji internetowej ASP.NET w programie Visual Studio:

1. Przejdź do Project>Dodaj telemetrię Application Insights.

2. Wybierz Azure Application Insights>Dalej.

3. Wybierz subskrypcję i wystąpienie usługi Application Insights. Możesz też utworzyć nowe wystąpienie za pomocą polecenia Utwórz nowe. Wybierz Dalej.

4. Dodaj lub potwierdź parametry połączenia usługi Application Insights. Powinna zostać wstępnie wypełniona na podstawie Twojego wyboru w poprzednim kroku. Wybierz Zakończ

5. Po dodaniu usługi Application Insights do projektu sprawdź, czy używasz najnowszej stabilnej wersji zestawu SDK. Przejdź do Projekt>Zarządzaj pakietami NuGet>Microsoft.ApplicationInsights.AspNetCore. Jeśli chcesz, wybierz pozycję Aktualizuj.

   

Ręczne dodawanie usługi Application Insights (bez programu Visual Studio)

Ta sekcja zawiera instrukcje ręcznego dodawania usługi Application Insights do aplikacji internetowej opartej na szablonach.

ASP.NET

1. Dodaj następujące pakiety NuGet i ich zależności do projektu:

   • Microsoft.ApplicationInsights.WindowsServer
   • Microsoft.ApplicationInsights.Web
   • Microsoft.AspNet.TelemetryCorrelation

2. W niektórych przypadkach plik ApplicationInsights.config jest tworzony automatycznie. Jeśli plik jest już obecny, przejdź do kroku 4.

   Utwórz ją samodzielnie, jeśli jej brakuje. W katalogu głównym aplikacji ASP.NET utwórz nowy plik o nazwie ApplicationInsights.config.

3. Skopiuj następującą konfigurację XML do nowo utworzonego pliku:

   
   
   Rozwiń, aby wyświetlić konfigurację

   <?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. Dodaj parametry połączenia, które można wykonać na dwa sposoby:

   • (Zalecane) Ustaw parametry połączenia w konfiguracji.

     Przed tagiem zamykającym </ApplicationInsights> w pliku ApplicationInsights.config dodaj parametry połączenia dla zasobu usługi Application Insights. Parametry połączenia można znaleźć w okienku przeglądu nowo utworzonego zasobu usługi Application Insights.

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

   • Ustaw parametry połączenia w kodzie.

     Podaj parametry połączenia w klasie program.cs.

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

5. Na tym samym poziomie projektu co plik ApplicationInsights.config utwórz folder o nazwie ErrorHandler z nowym plikiem C# o nazwie AiHandleErrorAttribute.cs. Zawartość pliku wygląda następująco:

   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. W folderze App_Start otwórz plik FilterConfig.cs i zmień go tak, aby był zgodny z przykładem:

   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. Jeśli plik Web.config został już zaktualizowany, pomiń ten krok. W przeciwnym razie zaktualizuj plik w następujący sposób:

   
   
   Rozwiń, aby wyświetlić konfigurację

   <?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>
   

Na tym etapie pomyślnie skonfigurowano monitorowanie aplikacji po stronie serwera. Jeśli uruchomisz aplikację internetową, zobaczysz, że dane telemetryczne zaczynają pojawiać się w usłudze Application Insights.

ASP.NET Core

1. Zainstaluj pakiet NuGet dla zestawu SDK usługi Application Insights na platformę ASP.NET Core.

   Zalecamy, aby zawsze używać najnowszej stabilnej wersji. Znajdź pełne informacje o wersji zestawu SDK w repozytorium GitHub typu open source.

   Poniższy przykładowy kod przedstawia zmiany, które mają zostać dodane do pliku csproj projektu:

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

2. Dodaj AddApplicationInsightsTelemetry() do klasy program.cs.

   Dodaj builder.Services.AddApplicationInsightsTelemetry(); po metodzie WebApplication.CreateBuilder() , jak w tym przykładzie:

   // 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. Dodaj parametry połączenia, które można wykonać na trzy sposoby:

   • (Zalecane) Ustaw parametry połączenia w konfiguracji.

     Ustaw parametry połączenia w appsettings.json i upewnij się, że plik konfiguracji został skopiowany do folderu głównego aplikacji podczas publikowania.

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

   • Ustaw parametry połączenia w zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING lub ApplicationInsights:ConnectionString w pliku konfiguracji JSON.

     Przykład:

     • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
     • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     • Zazwyczaj jest używany w usłudze APPLICATIONINSIGHTS_CONNECTION_STRING Web Apps. Można go również używać we wszystkich miejscach, w których ten zestaw SDK jest obsługiwany.

     Uwaga / Notatka

     Ciąg połączenia określony w kodzie ma priorytet nad zmienną środowiskową APPLICATIONINSIGHTS_CONNECTION_STRING, która ma priorytet nad innymi opcjami.

   • Ustaw parametry połączenia w kodzie.

     Podaj łańcuch połączenia jako część argumentu ApplicationInsightsServiceOptions do AddApplicationInsightsTelemetry w klasie program.cs.

Wpisy tajne użytkownika i inni dostawcy konfiguracji

Jeśli chcesz przechowywać ciąg połączeń w tajnych użytkownika ASP.NET Core lub pobrać je z innego dostawcy konfiguracji, możesz użyć przeciążenia z parametrem Microsoft.Extensions.Configuration.IConfiguration. Przykładowy parametr to services.AddApplicationInsightsTelemetry(Configuration);.

W Microsoft.ApplicationInsights.AspNetCore wersji 2.15.0 lub nowszej wywołanie services.AddApplicationInsightsTelemetry() automatycznie odczytuje parametry połączenia z Microsoft.Extensions.Configuration.IConfiguration aplikacji. Nie ma potrzeby jawnego podawania IConfiguration.

W przypadku IConfiguration załadowania konfiguracji od wielu dostawców services.AddApplicationInsightsTelemetry priorytet konfiguracji z appsettings.json, niezależnie od kolejności dodawania dostawców. Użyj metody services.AddApplicationInsightsTelemetry(IConfiguration) do odczytu konfiguracji z IConfiguration bez tego preferencyjnego traktowania dla appsettings.json.

Usługa procesu roboczego

W tym dziale

• Korzystanie z zestawu SDK Application Insights dla Worker Service
• Aplikacja usługi roboczej platformy .NET Core
• ASP.NET Podstawowe zadania w tle z hostowanymi usługami
• Aplikacja konsolowa .NET Core/.NET Framework

Korzystanie z SDK Application Insights dla usługi Worker

1. Zainstaluj pakiet Microsoft.ApplicationInsights.WorkerService w aplikacji.

   Poniższy fragment kodu przedstawia zmiany, które należy dodać do pliku projektu .csproj :

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

2. Skonfiguruj parametry połączenia w zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING lub w konfiguracji (appsettings.json).

   

3. ILogger Pobierz wystąpienie lub TelemetryClient wystąpienie z kontenera wstrzykiwania zależności (DI), wywołując serviceProvider.GetRequiredService<TelemetryClient>(); metodę lub używając iniekcji konstruktora. Ten krok wyzwala konfigurowanie modułów TelemetryConfiguration i autokolekcji.

Szczegółowe instrukcje dotyczące każdego typu aplikacji opisano w poniższych sekcjach.

Aplikacja usługi roboczej platformy .NET Core

Pełny przykład jest udostępniany w witrynie internetowej NuGet.

1. Pobierz i zainstaluj zestaw .NET SDK.

2. Utwórz nowy projekt usługi Worker przy użyciu szablonu nowego projektu programu Visual Studio lub wiersza polecenia dotnet new worker.

3. Dodaj pakiet Microsoft.ApplicationInsights.WorkerService do aplikacji.

4. Dodaj services.AddApplicationInsightsTelemetryWorkerService(); do CreateHostBuilder() metody w Program.cs klasie, jak w tym przykładzie:

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

5. Zmodyfikuj element Worker.cs zgodnie z poniższym przykładem:

       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. Skonfiguruj parametry połączenia.

   

   Uwaga / Notatka

   Zalecamy określenie ciągu połączenia w konfiguracji. Poniższy przykładowy kod pokazuje, jak określić parametry połączenia w pliku appsettings.json. Podczas publikowania upewnij się, że appsettings.json plik został skopiowany do folderu głównego aplikacji.

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

Alternatywnie określ parametry połączenia w zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING .

APPLICATIONINSIGHTS_CONNECTION_STRING Zazwyczaj określa ciąg połączenia dla aplikacji wdrożonych w aplikacjach webowych jako zadania webowe.

Uwaga / Notatka

Parametry połączenia określone w kodzie mają pierwszeństwo przed zmienną środowiskową APPLICATIONINSIGHTS_CONNECTION_STRING, która ma pierwszeństwo przed innymi opcjami.

Zadania w tle w ASP.NET Core z hostowanymi usługami

W tym dokumencie opisano sposób tworzenia zadań w tle w aplikacji ASP.NET Core.

Pełny przykład jest udostępniany na tej stronie usługi GitHub.

1. Zainstaluj pakiet Microsoft.ApplicationInsights.WorkerService w aplikacji.

2. Dodaj services.AddApplicationInsightsTelemetryWorkerService(); do metody ConfigureServices(), jak w tym przykładzie:

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

   Poniższy kod dotyczy elementu TimedHostedService, gdzie znajduje się logika zadań działających w tle.

       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. Skonfiguruj parametry połączenia. Użyj tego samego appsettings.json z wcześniejszego przykładu usługi roboczej platformy .NET.

Aplikacja konsolowa .NET Core/.NET Framework

Jak wspomniano na początku tego artykułu, nowy pakiet może służyć do włączania telemetrii usługi Application Insights z nawet zwykłej aplikacji konsolowej. Ten pakiet jest przeznaczony dla netstandard2.0, dzięki czemu można go używać w przypadku aplikacji konsolowych na .NET Core lub nowsze wersje oraz .NET Framework lub nowsze wersje.

Pełny przykład jest udostępniany na tej stronie usługi GitHub.

1. Zainstaluj pakiet Microsoft.ApplicationInsights.WorkerService w aplikacji.

2. Zmodyfikuj Program.cs, jak pokazano w poniższym przykładzie:

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

Ta aplikacja konsolowa również używa tego samego domyślnego TelemetryConfiguration. Można go dostosować w taki sam sposób, jak przykłady we wcześniejszych sekcjach.

Node.js

Wymagania wstępne

• Subskrypcja platformy Azure. Jeśli jeszcze go nie masz, utwórz bezpłatne konto platformy Azure.
• Zasób oparty na obszarze roboczym usługi Application Insights.
• Działająca aplikacja. Jeśli jeszcze go nie masz, zobacz Tworzenie podstawowej aplikacji internetowej.

Konfigurowanie biblioteki klienta Node.js

Uwzględnij zestaw SDK w aplikacji, aby mógł zbierać dane.

1. Skopiuj parametry połączenia zasobu z nowego zasobu. Usługa Application Insights używa ciągu połączenia do mapowania danych do zasobu platformy Azure. Aby zestaw SDK mógł używać parametry połączenia, należy określić parametry połączenia w zmiennej środowiskowej lub w kodzie.

   

2. Dodaj bibliotekę klienta Node.js do zależności aplikacji za pomocą polecenia package.json. Z folderu głównego Twojej aplikacji uruchom polecenie:

   npm install applicationinsights --save
   

   Uwaga / Notatka

   Jeśli używasz języka TypeScript, nie instaluj oddzielnych pakietów "typings". Ten pakiet NPM zawiera wbudowane definicje typów.

3. Wyraźnie załaduj bibliotekę w swoim kodzie. Ponieważ zestaw SDK wprowadza instrumentację do wielu innych bibliotek, załaduj go możliwie jak najszybciej, nawet przed innymi instrukcjami require.

   let appInsights = require('applicationinsights');
   

4. Można również podać parametry połączenia za pomocą zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING, zamiast przekazywać ją ręcznie do setup() lub new appInsights.TelemetryClient(). Ta praktyka pozwala zachować parametry połączenia poza zatwierdzonym kodem źródłowym i można określić różne parametry połączenia dla różnych środowisk. Aby ręcznie skonfigurować, wywołaj metodę appInsights.setup('[your connection string]');.

   Aby uzyskać więcej opcji konfiguracji, zobacz następujące sekcje.

   Zestaw SDK możesz wypróbować bez wysyłania danych telemetrycznych przez ustawienie elementu appInsights.defaultClient.config.disableAppInsights = true.

5. Rozpocznij automatyczne zbieranie i wysyłanie danych przez wywołanie metody appInsights.start();.

Uwaga / Notatka

W ramach instrumentacji usługi Application Insights zbieramy i wysyłamy dane diagnostyczne do firmy Microsoft. Te dane pomagają nam uruchamiać i ulepszać usługę Application Insights. Możesz wyłączyć zbieranie danych nieistotnych. Dowiedz się więcej.

Podstawowy sposób użycia

W przypadku gotowej do użycia kolekcji żądań HTTP, popularnych zdarzeń bibliotek zewnętrznych, nieobsługiwanych wyjątków i metryk systemowych:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Uwaga / Notatka

Jeśli parametr połączenia jest ustawiony w zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING, .setup() można wywołać bez argumentów. Ułatwia to korzystanie z różnych parametry połączenia w różnych środowiskach.

Załaduj bibliotekę usługi Application Insights require("applicationinsights") tak szybko, jak to możliwe, przed załadowaniem innych pakietów. Ten krok jest potrzebny, aby biblioteka usługi Application Insights mogła przygotować później pakiety do śledzenia. Jeśli wystąpią konflikty z innymi bibliotekami wykonującymi podobne przygotowania, spróbuj załadować bibliotekę Application Insights później.

Ze względu na sposób, w jaki język JavaScript obsługuje wywołania zwrotne, konieczna jest większa praca w celu śledzenia żądania między zależnościami zewnętrznymi i późniejszymi wywołaniami zwrotnymi. Domyślnie to dodatkowe śledzenie jest włączone. Wyłącz tę funkcję, wywołując wywołanie setAutoDependencyCorrelation(false) zgodnie z opisem w sekcji konfiguracji zestawu SDK.

Migrowanie z wersji wcześniejszych do wersji 0.22

Istnieją zmiany powodujące niezgodność między wydaniami przed wersją 0.22 a wydaniami po niej. Te zmiany zostały zaprojektowane tak, aby zapewnić spójność z innymi zestawami SDK usługi Application Insights i umożliwiają rozszerzanie w przyszłości.

Ogólnie rzecz biorąc, można przeprowadzić migrację przy użyciu następujących akcji:

• Zastąp odwołania do appInsights.client na appInsights.defaultClient.
• Zastąp odwołania do appInsights.getClient() na new appInsights.TelemetryClient().
• Zastąp wszystkie argumenty metod client.track* pojedynczym obiektem zawierającym nazwane właściwości jako argumenty. Zobacz wbudowane wskazówki dotyczące typu środowiska IDE lub TelemetryTypes dla obiektu z wyjątkiem dla każdego typu telemetrii.

Jeśli uzyskujesz dostęp do funkcji konfiguracji SDK bez łączenia ich z appInsights.setup(), możesz teraz znaleźć te funkcje w appInsights.Configurations. Przykładem jest appInsights.Configuration.setAutoCollectDependencies(true). Przejrzyj zmiany konfiguracji domyślnej w następnej sekcji.

Sprawdzanie, czy usługa Application Insights odbiera dane telemetryczne

.NET

ASP.NET i ASP.NET Core

Uruchom aplikację i wysyłaj do niej żądania. Dane telemetryczne powinny teraz przepływać do usługi Application Insights. Zestaw SDK usługi Application Insights automatycznie zbiera przychodzące żądania internetowe do aplikacji wraz z następującymi danymi telemetrycznymi.

Usługa procesu roboczego

Uruchom aplikację. Pracownicy ze wszystkich powyższych przykładów co sekundę wykonują wywołanie HTTP do bing.com, a także rejestrują kilka dzienników za pomocą ILogger. Te linie są opakowane wewnątrz wywołania metody StartOperation z TelemetryClient, które służy do tworzenia operacji. W tym przykładzie RequestTelemetry jest nazwany "operation".

Usługa Application Insights zbiera te dzienniki ILogger o ważności Ostrzeżenie lub nowsze domyślnie oraz zależności. Są one powiązane z RequestTelemetry, wykazując relację nadrzędny-podrzędny. Korelacja działa również w granicach procesów/sieci. Jeśli na przykład wywołanie zostało wykonane do innego monitorowanego składnika, jest również skorelowane z tym komponentem nadrzędnym.

Tę niestandardową operację RequestTelemetry można traktować jako odpowiednik przychodzącego żądania internetowego w typowej aplikacji internetowej. Nie jest konieczne użycie operacji, ale najlepiej pasuje do modelu danych korelacji usługi Application Insights. RequestTelemetry działa jako operacja nadrzędna, a każda telemetria wygenerowana wewnątrz iteracji procesu roboczego jest traktowana jako logicznie należąca do tej samej operacji.

Takie podejście zapewnia również, że wygenerowane dane telemetryczne, zarówno automatyczne, jak i ręczne, mają ten sam typ operation_id. Ponieważ próbkowanie jest oparte na metodzie operation_id, algorytm próbkowania zachowuje lub odrzuca wszystkie dane telemetryczne z jednej iteracji.

Node.js

Zestaw SDK automatycznie zbiera dane telemetryczne dotyczące środowiska uruchomieniowego Node.js i niektórych typowych modułów innych firm. Użyj swojej aplikacji, aby wygenerować niektóre z tych danych.

Następnie w witrynie Azure Portal przejdź do usługi Application Insights i otwórz utworzony zasób. W sekcji Podgląd na osi czasu, znajdź kilka pierwszych punktów danych. Aby wyświetlić bardziej szczegółowe dane, wybierz inne składniki wykresów.

Aby wyświetlić topologię odnalezioną dla aplikacji, możesz użyć mapy aplikacji.

Brak danych

Ponieważ SDK grupuje dane do przesłania, może wystąpić opóźnienie, zanim pozycje pojawią się w portalu. Jeśli nie widzisz danych w swoim zasobie, wypróbuj następujące sposoby:

• Kontynuuj korzystanie z aplikacji. Wykonaj więcej akcji, aby wygenerować więcej telemetrii.
• Wybierz pozycję Odśwież w widoku zasobów portalu. Wykresy są odświeżane samoczynnie w regularnych odstępach czasu, ale ręczne odświeżenie wymusza ich natychmiastowe zaktualizowanie.
• Upewnij się, że wymagane porty wychodzące zostały otwarte.
• Użyj pozycji Wyszukaj, aby znaleźć określone zdarzenia.
• Zapoznaj się z sekcją Często zadawane pytania.

Zbieranie danych telemetrycznych

.NET

W tym dziale

• Metryki na żywo
• Ślady (dzienniki)
• Śledzenie rozproszone
• Zależności
• Wyjątki
• Metryki niestandardowe
• Operacje niestandardowe
• Liczniki
• Kolekcja migawek

Metryki na żywo

Metryki na żywo mogą służyć do szybkiego sprawdzania, czy monitorowanie aplikacji za pomocą usługi Application Insights jest poprawnie skonfigurowane. Dane telemetryczne mogą pojawić się w witrynie Azure Portal, ale okienko metryk na żywo pokazuje użycie procesora CPU uruchomionego procesu niemal w czasie rzeczywistym. Może również wyświetlać inne dane telemetryczne, takie jak żądania, zależności i ślady.

Uwaga / Notatka

Metryki na żywo są domyślnie włączone podczas wdrożenia przy użyciu zalecanych instrukcji dla aplikacji .NET.

Włączanie metryk na żywo przy użyciu kodu dla dowolnej aplikacji .NET

ASP.NET

Aby ręcznie skonfigurować metryki na żywo:

1. Zainstaluj pakiet NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. Poniższy przykładowy kod aplikacji konsoli przedstawia konfigurowanie metryk na żywo:

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

Aby ręcznie skonfigurować metryki na żywo:

1. Zainstaluj pakiet NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. Poniższy przykładowy kod aplikacji konsoli przedstawia konfigurowanie metryk na żywo:

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

Powyższy przykład dotyczy aplikacji konsolowej, ale ten sam kod może być używany w dowolnych aplikacjach platformy .NET.

Ważne

Jeśli jakiekolwiek inne moduły telemetryczne są włączone do automatycznego generowania danych telemetrycznych, upewnij się, że ta sama konfiguracja używana do inicjowania tych modułów jest używana dla modułu metryk na żywo.

Uwaga / Notatka

Domyślna konfiguracja zbiera ILoggerWarning dzienniki oraz dzienniki o wyższym poziomie ważności. Aby uzyskać więcej informacji, zobacz Jak mogę dostosować kolekcję dzienników ILogger?.

Usługa procesu roboczego

Dzienniki generowane za pomocą ILogger o poziomie ważności Ostrzeżenie lub wyższym są automatycznie przechwytywane. Aby zmienić to zachowanie, jawnie przesłoń konfigurację rejestrowania dla dostawcy ApplicationInsights, jak pokazano w poniższym kodzie. Poniższa konfiguracja umożliwia usłudze Application Insights przechwytywanie wszystkich Information dzienników i bardziej krytycznych dzienników.

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

Należy pamiętać, że poniższy przykład nie powoduje przechwycenia Information dzienników przez dostawcę usługi Application Insights. Nie rejestruje tego, ponieważ zestaw SDK dodaje domyślny filtr rejestrowania, który instruuje ApplicationInsights, aby rejestrował tylko dzienniki Warning i bardziej poważne logi. Usługa Application Insights wymaga jawnego zastąpienia.

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

Uwaga / Notatka

Usługa Application Insights uwzględnia poziomy dzienników skonfigurowane za pośrednictwem funkcji ConfigureLogging(...) w kodzie. Jeśli jest używana tylko appsettings.json, a funkcja ConfigureLogging nie jest jawnie zastępowana, domyślny poziom dziennika to Ostrzeżenie.

Aby uzyskać więcej informacji, zapoznaj się z dokumentacją ILogger, aby dostosować poziomy dzienników, które są przechwytywane przez Application Insights.

Ślady (dzienniki)

W tej sekcji wyjaśniono, jak wysyłać dzienniki śledzenia diagnostycznego z aplikacji ASP.NET lub ASP.NET Core do usługi Application Insights, a następnie eksplorować/przeszukiwać te dzienniki w portalu.

Dzienniki śledzenia umożliwiają identyfikowanie śladów skojarzonych z każdym żądaniem użytkownika i korelowanie ich z innymi zdarzeniami i raportami wyjątków.

Usługa Application Insights przechwytuje dzienniki z platformy ASP.NET Core i innych aplikacji platformy .NET za pośrednictwem protokołu ILogger oraz z klasycznych ASP.NET (.NET Framework) za pośrednictwem klasycznego zestawu SDK i kart.

Uwaga / Notatka

• Domyślnie dostawca usługi Application Insights wysyła tylko dzienniki o ważności Warning lub wyższej. Aby uwzględnić Information lub niższego poziomu dzienniki, zaktualizuj ustawienia poziomu dziennika w programie appsettings.json.

• Microsoft.ApplicationInsights.WorkerService Pakiet NuGet używany do włączania usługi Application Insights dla usług w tle jest poza zakresem.

• Aby zapoznać się z często zadawanymi pytaniami, zobacz Rejestrowanie przy użyciu platformy .NET — często zadawane pytania.

Instalowanie rejestrowania w aplikacji

ASP.NET

Wybierz metodę rejestrowania, aby emitować dzienniki diagnostyczne, które mogą zbierać usługa Application Insights.

W przypadku klasycznych aplikacji ASP.NET korzystających ze śledzenia System.Diagnostics, skonfiguruj Application Insights TraceListener w pliku konfiguracyjnym.

Dodaj odbiornik do lub .

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

Uwaga / Notatka

Moduł przechwytywania logów jest przydatnym adapterem dla rejestratorów innych firm. Jeśli jednak nie używasz jeszcze protokołu NLog, log4Net lub System.Diagnostics.Trace, rozważ bezpośrednie wywołanie metody TrackTrace() usługi Application Insights .

Konfigurowanie usługi Application Insights w celu zbierania dzienników

Opcja 1: Jeśli jeszcze tego nie zrobiono, dodaj usługę Application Insights do projektu. Podczas dodawania usługi Application Insights w programie Visual Studio istnieje możliwość uwzględnienia modułu zbierającego dzienniki.

Opcja 2: Kliknij prawym przyciskiem myszy projekt w Eksploratorze rozwiązań, aby skonfigurować usługę Application Insights. Wybierz opcję Konfiguruj kolekcjonowanie śladów.

Uwaga / Notatka

Jeśli brakuje opcji menu usługi Application Insights lub modułu zbierającego dzienniki, zapoznaj się z dedykowanym artykułem dotyczącym rozwiązywania problemów.

ASP.NET Core

Zestaw SDK usługi Application Insights dla platformy ASP.NET Core już zbiera dzienniki ILogger domyślnie. Jeśli używasz zestawu SDK, zwykle nie musisz również wywoływać builder.Logging.AddApplicationInsights() i można pominąć następujące instrukcje instalacji ILogger.

Jeśli potrzebujesz tylko przekazywania dzienników, a nie pełnego stosu telemetrii, możesz użyć Microsoft.Extensions.Logging.ApplicationInsights pakietu dostawcy do przechwytywania dzienników.

Instalacja ręczna

Użyj tej metody, jeśli typ projektu nie jest obsługiwany przez instalatora usługi Application Insights (na przykład niektóre scenariusze pulpitu/konsoli) lub jeśli wolisz jawną kontrolę na poziomie pakietu.

1. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy projekt i wybierz polecenie Zarządzaj pakietami NuGet.

2. Wyszukaj usługę Application Insights.

3. Wybierz jeden z następujących pakietów:

   • ILogger: Microsoft.Extensions.Logging.ApplicationInsights
   • System.Diagnostics: Microsoft.ApplicationInsights.TraceListener
   • log4net: Microsoft.ApplicationInsights.Log4NetAppender
   • NLog: Microsoft.ApplicationInsights.NLogTarget
   • Microsoft.ApplicationInsights.EventSourceListener
   • Microsoft.ApplicationInsights.DiagnosticSourceListener Baner odbiornika źródła diagnostycznego NuGet
   • Microsoft.ApplicationInsights.EtwCollector

Pakiet NuGet instaluje niezbędne zestawy i modyfikuje web.config lub app.config, jeśli ma to zastosowanie.

Instrukcje instalacji:

Uwaga / Notatka

Rozwiń dowolną z poniższych sekcji, aby uzyskać instrukcje instalacji specyficzne dla pakietu.

ILogger

1. Zainstaluj program Microsoft.Extensions.Logging.ApplicationInsights.

2. Dodaj ApplicationInsightsLoggerProviderpolecenie :

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

Po zainstalowaniu pakietu NuGet i zarejestrowaniu dostawcy za pomocą wstrzykiwania zależności aplikacja jest gotowa do rejestrowania. W przypadku iniekcji ILogger konstruktora wymagana jest alternatywa ILogger<TCategoryName> typu ogólnego lub ogólnego. Po rozwiązaniu ApplicationInsightsLoggerProvider tych implementacji udostępnia je. Zarejestrowane komunikaty lub wyjątki są wysyłane do usługi Application Insights.

Rozważmy następujący przykładowy kontroler:

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" };
    }
}

Aby uzyskać więcej informacji, zobacz Rejestrowanie w usłudze ASP.NET Core i Jaki typ telemetrii usługi Application Insights jest generowany na podstawie dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w usłudze Application Insights?.

Wstawianie wywołań dziennika diagnostycznego (System.Diagnostics.Trace / log4net / NLog)

Jeśli używasz metody System.Diagnostics.Trace, typowe wywołanie to:

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

Jeśli wolisz log4net lub NLog, skorzystaj z:

    logger.Warn("Slow response - database01");

Używanie zdarzeń z EventSource

Zdarzenia System.Diagnostics.Tracing.EventSource można skonfigurować do wysyłania do usługi Application Insights jako śladów.

1. Microsoft.ApplicationInsights.EventSourceListener Zainstaluj pakiet NuGet.

2. Edytuj sekcję TelemetryModules pliku ApplicationInsights.config :

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

Dla każdego źródła można ustawić następujące parametry:

• Nazwa określa nazwę źródła zdarzeń do zebrania.
• Poziom określa poziom rejestrowania do zbierania: Krytyczne, Błąd, Informacje, LogAlways, Verbose lub Warning.
• Słowa kluczowe (opcjonalnie) określają wartość całkowitą kombinacji słów kluczowych do użycia.

Używanie zdarzeń DiagnosticSource

Zdarzenia System.Diagnostics.DiagnosticSource można skonfigurować do wysyłania do usługi Application Insights jako śladów.

1. Microsoft.ApplicationInsights.DiagnosticSourceListener Zainstaluj pakiet NuGet.

2. Edytuj sekcję TelemetryModules pliku ApplicationInsights.config :

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

Dla każdego źródła diagnostycznego, które chcesz śledzić, dodaj wpis z atrybutem Name ustawionym na nazwę źródła diagnostycznego.

Używanie zdarzeń ETW

Śledzenie zdarzeń systemu Windows (ETW) można skonfigurować tak, aby było wysyłane do usługi Application Insights jako ślady.

1. Microsoft.ApplicationInsights.EtwCollector Zainstaluj pakiet NuGet.

2. Edytuj sekcję "TelemetryModules" w pliku ApplicationInsights.config :

Uwaga / Notatka

Zdarzenia ETW można zbierać tylko wtedy, gdy proces, w którym działa zestaw SDK, operuje na tożsamości, która jest członkiem grupy użytkowników dziennika wydajności lub administratorów.

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

Dla każdego źródła można ustawić następujące parametry:

• ProviderName to nazwa dostawcy ETW, którego dane mają być zbierane.
• ProviderGuid określa identyfikator GUID zbieranego dostawcy ETW. Można go użyć zamiast ProviderName.
• Poziom ustawia poziom rejestrowania w celu zbierania. Może to być krytyczne, błędy, informacyjne, logalways, pełne lub ostrzeżenie.
• Słowa kluczowe (opcjonalnie) ustawiają wartość całkowitą kombinacji słów kluczowych do użycia.

Bezpośrednie użycie API śledzenia

Interfejs API śledzenia usługi Application Insights można wywołać bezpośrednio. Adaptery logowania używają tego interfejsu API. Przykład:

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

Zaletą TrackTrace jest to, że można umieścić stosunkowo długie dane w komunikacie. Możesz na przykład zakodować tam dane POST.

Możesz również dodać stopień surowości do wiadomości. Podobnie jak inne dane telemetryczne, można dodać wartości właściwości, aby ułatwić filtrowanie lub wyszukiwanie różnych zestawów śladów. Przykład:

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

Teraz możesz łatwo odfiltrować w obszarze Wyszukiwanie transakcji wszystkie komunikaty określonego poziomu ważności, które odnoszą się do określonej bazy danych.

Aplikacja konsolowa

Aby dodać rejestrowanie usługi Application Insights do aplikacji konsoli, najpierw zainstaluj następujące pakiety NuGet:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

W poniższym przykładzie Microsoft.Extensions.Logging.ApplicationInsights użyto pakietu i pokazano domyślne zachowanie aplikacji konsolowej. Pakiet Microsoft.Extensions.Logging.ApplicationInsights powinien być używany w aplikacji konsolowej lub zawsze, gdy potrzebujesz minimalnej implementacji usługi Application Insights bez pełnego zestawu funkcji, takich jak metryki, śledzenie rozproszone, próbkowanie i inicjatory telemetrii.

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

Aby uzyskać więcej informacji, zobacz What Application Insights telemetry type is produced from ILogger logs? (Jaki typ telemetrii usługi Application Insights jest generowany na podstawie dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w usłudze Application Insights?.

Zakresy rejestrowania

Uwaga / Notatka

Poniższe wskazówki dotyczą scenariuszy ILogger (tylko ASP.NET Core i konsoli). Nie ma zastosowania do klasycznych ASP.NET.

ApplicationInsightsLoggingProvider obsługuje zakresy dzienników, które są domyślnie włączone.

Jeśli zakres ma typ IReadOnlyCollection<KeyValuePair<string,object>>, każda para klucz/wartość w kolekcji zostanie dodana do telemetrii usługi Application Insights jako właściwości niestandardowych. W poniższym przykładzie dzienniki są przechwytywane jako TraceTelemetry i mają ("MyKey", "MyValue") właściwości.

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

Jeśli jakikolwiek inny typ jest używany jako zakres, jest przechowywany w ramach właściwości Scope w telemetrii usługi Application Insights. W poniższym przykładzie TraceTelemetry ma właściwość o nazwie Scope , która zawiera zakres.

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

Znajdowanie dzienników

Uruchom aplikację w trybie debugowania lub wdróż ją na żywo.

Eksploruj w wyszukiwaniu transakcji

W okienku przeglądu aplikacji w portalu usługi Application Insights wybierz pozycję Wyszukiwanie transakcji , w którym można:

• Filtruj ślady dziennika lub elementy o określonych właściwościach.
• Szczegółowe sprawdzanie określonego elementu.
• Znajdź inne dane dziennika systemu, które odnoszą się do tego samego żądania użytkownika (ma ten sam identyfikator operacji).
• Zapisz konfigurację strony jako ulubionej.

Uwaga / Notatka

Jeśli aplikacja wysyła duże ilości danych i używasz zestawu SDK usługi Application Insights dla ASP.NET w wersji 2.0.0-beta3 lub nowszej, funkcja próbkowania adaptacyjnego może działać i wysyłać tylko część danych telemetrycznych. Dowiedz się więcej o próbkowaniu.

Eksplorowanie w dziennikach usługi Azure Monitor

Dzienniki ILogger są wyświetlane jako dane telemetryczne śledzenia (tabela traces w usłudze Application Insights i AppTraces w usłudze Log Analytics).

Przykład

W witrynie Azure Portal przejdź do usługi Application Insights i uruchom polecenie:

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

Śledzenie rozproszone

Nowoczesne architektury chmury i mikrousług umożliwiają proste, niezależne wdrażanie usług, które zmniejszają koszty przy jednoczesnym zwiększeniu dostępności i przepływności. Jednak sprawiło to, że ogólne systemy stały się trudniejsze do rozumienia i debugowania. Śledzenie rozproszone rozwiązuje ten problem, udostępniając profiler wydajności, który działa jak stosy wywołań dla architektur chmury i mikrousług.

Usługa Azure Monitor udostępnia dwa środowiska korzystania z rozproszonych danych śledzenia: widok diagnostyki transakcji dla pojedynczej transakcji/żądania i widok mapy aplikacji , aby pokazać, jak systemy współdziałają.

Usługa Application Insights może monitorować poszczególne składniki oddzielnie i wykrywać, który składnik jest odpowiedzialny za awarie lub obniżenie wydajności przy użyciu korelacji rozproszonej telemetrii. W tym artykule wyjaśniono model danych, techniki propagacji kontekstu, protokoły i implementację taktyki korelacji na różnych językach i platformach używanych przez usługę Application Insights.

Włącz śledzenie rozproszone za pośrednictwem usługi Application Insights z wykorzystaniem autoinstrumentacji lub SDK.

Agenty i zestawy SDK usługi Application Insights dla platform .NET, .NET Core, Java, Node.js i JavaScript obsługują naturalną obsługę śledzenia rozproszonego.

Po zainstalowaniu i skonfigurowaniu odpowiedniego SDK usługi Application Insights, autokollektory zależności automatycznie zbierają informacje śledzenia dla popularnych frameworków, bibliotek i technologii. Pełna lista obsługiwanych technologii jest dostępna w dokumentacji autocollection zależności.

Każda technologia może być również śledzona ręcznie za pomocą wywołania funkcji TrackDependency w obiekcie TelemetryClient.

Model danych dla korelacji telemetrii

Usługa Application Insights definiuje model danych dla korelacji rozproszonej telemetrii. Aby skojarzyć dane telemetryczne z operacją logiczną, każdy element telemetrii ma pole kontekstu o nazwie operation_Id. Każdy element telemetrii w rozproszonej trasie posiada ten identyfikator. Nawet jeśli utracisz dane telemetryczne z jednej warstwy, nadal można skojarzyć dane telemetryczne zgłaszane przez inne składniki.

Rozproszona operacja logiczna zwykle składa się z zestawu mniejszych operacji, które są żądaniami przetwarzanymi przez jeden ze składników. Telemetria żądania definiuje te operacje. Każdy element telemetrii żądania ma swój własny id, który identyfikuje go unikatowo i globalnie. Wszystkie elementy telemetrii (takie jak ślady i wyjątki) związane z żądaniem powinny ustawiać operation_parentId na wartość odpowiadającą żądaniu id.

Telemetria zależności reprezentuje każdą operację wychodzącą, taką jak wywołanie HTTP do innego składnika. Definiuje również własną id, która jest globalnie unikalna. Telemetria żądania, zainicjowana przez wywołanie tej zależności, używa tego id jako operation_parentId.

Widok rozproszonej operacji logicznej można utworzyć przy użyciu elementów operation_Id, operation_parentIdi request.id .dependency.id Te pola definiują również kolejność przyczynowości wywołań telemetrycznych.

W środowisku mikrousług ślady ze składników mogą przechodzić do różnych elementów magazynu. Każdy składnik może mieć własne parametry połączenia w usłudze Application Insights. Aby uzyskać dane telemetryczne dla operacji logicznej, usługa Application Insights wysyła zapytania o dane z każdego elementu magazynu.

Gdy liczba elementów magazynu jest duża, potrzebujesz wskazówki dotyczącej tego, gdzie szukać dalej. Model danych usługi Application Insights definiuje dwa pola, aby rozwiązać ten problem: request.source i dependency.target. Pierwsze pole identyfikuje składnik, który zainicjował żądanie zależności. Drugie pole identyfikuje, który składnik zwrócił odpowiedź wywołania zależności.

Aby uzyskać informacje na temat wykonywania zapytań z wielu niezależnych instancji, zobacz Wykonywanie zapytań dotyczących danych w obszarach roboczych, aplikacjach i zasobach usługi Log Analytics w usłudze Azure Monitor.

Example

Przyjrzyjmy się przykładowi. Aplikacja o nazwie Ceny akcji pokazuje bieżącą cenę rynkową akcji przy użyciu zewnętrznego interfejsu API o nazwie Stock. Aplikacja Stock Prices ma stronę o nazwie Stock page (Strona giełdowa), która zostanie otwarta w przeglądarce internetowej klienta przy użyciu polecenia GET /Home/Stock. Aplikacja wysyła zapytanie do interfejsu API stock przy użyciu wywołania GET /api/stock/valueHTTP .

Możesz przeanalizować wynikową telemetrię, uruchamiając zapytanie:

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

W wynikach wszystkie elementy telemetrii dzielą wspólny korzeń operation_Id. Gdy ze strony wykonano wywołanie Ajax, do telemetrii zależności zostanie przypisany nowy unikatowy identyfikator (qJSXU), a identyfikator widoku strony jest używany jako operation_ParentId. Następnie żądanie serwera używa identyfikatora Ajax jako operation_ParentId.

typPrzedmiotu	nazwa	identyfikator	operation_ParentId	Id_operacji
pageView	Strona zapasów	STYz		STYz
zależność	GET /Home/Stock	qJSXU	STYz	STYz
żądanie	GET Strona główna/Akcje	KqKwlrSt9PA=	qJSXU	STYz
zależność	GET /api/stock/value	bBrf2L7mm2g=	KqKwlrSt9PA=	STYz

Po wywołaniu GET /api/stock/value usługi zewnętrznej należy znać tożsamość tego serwera, aby można było odpowiednio ustawić dependency.target pole. Jeśli usługa zewnętrzna nie obsługuje monitorowania, target jest ustawiona na nazwę hosta usługi. Przykładem jest stock-prices-api.com. Jeśli jednak usługa identyfikuje się, zwracając wstępnie zdefiniowany nagłówek HTTP, target zawiera tożsamość usługi, co umożliwia Application Insights tworzenie rozproszonego śledzenia przez wykonywanie zapytań dotyczących danych telemetrycznych z tej usługi.

Nagłówki korelacji z użyciem W3C TraceContext.

Usługa Application Insights przechodzi na kontekst śledzenia W3C, który definiuje:

• traceparent: Zawiera globalnie unikalny identyfikator operacji i unikalny identyfikator wywołania.
• tracestate: niesie kontekst śledzenia specyficzny dla systemu.

Najnowsza wersja zestawu SDK usługi Application Insights obsługuje protokół Trace-Context, ale może być konieczne jego wybranie. (Zachowana jest zgodność z poprzednim protokołem korelacji obsługiwanym przez zestaw SDK usługi Application Insights.)

Protokół HTTP korelacji, nazywany również identyfikatorem żądania, jest przestarzały. Ten protokół definiuje dwa nagłówki:

• Request-Id: Przechowuje globalnie unikalny identyfikator połączenia.
• Correlation-Context: zawiera kolekcję par klucz-wartość dla właściwości śledzenia rozproszonego.

Usługa Application Insights definiuje również rozszerzenie dla korelacyjnego protokołu HTTP. Używa par Request-Context nazwa-wartość do propagowania kolekcji właściwości używanych przez bezpośredniego wywołującego lub wywoływanego. Zestaw SDK usługi Application Insights używa tego nagłówka do ustawiania pól dependency.target i request.source.

Modele danych W3C Trace-Context i Application Insights są odwzorowywane w następujący sposób:

Application Insights	W3C TraceContext
Idi RequestDependency	parent-id
Operation_Id	trace-id
Operation_ParentId	parent-id tego zakresu nadrzędnego. To pole musi być puste, jeśli jest to zakres korzeniowy.

Aby uzyskać więcej informacji, zobacz Model danych telemetrycznych usługi Application Insights.

Włącz obsługę śledzenia rozproszonego W3C

Śledzenie rozproszone oparte na protokole W3C TraceContext jest domyślnie włączone we wszystkich ostatnich zestawach SDK .NET Framework/.NET Core wraz ze zgodnością wsteczną ze starszym Request-Id protokołem.

Korelacja telemetrii

Korelacja jest domyślnie obsługiwana podczas włączania aplikacji. Nie są wymagane żadne akcje specjalne.

Środowisko uruchomieniowe platformy .NET obsługuje działania rozproszone za pomocą Activity i DiagnosticSource

SDK .NET usługi Application Insights używa DiagnosticSource i Activity do zbierania i korelowania danych telemetrycznych.

Zależności

Automatycznie śledzone zależności

Zestawy SDK usługi Application Insights dla platform .NET i .NET Core są dostarczane z modułem DependencyTrackingTelemetryModule, który jest modułem telemetrii, który automatycznie zbiera zależności. Moduł DependencyTrackingTelemetryModule jest dostarczany jako pakiet NuGet Microsoft.ApplicationInsights.DependencyCollector i jest dostarczany automatycznie podczas korzystania z Microsoft.ApplicationInsights.Web pakietu NuGet lub Microsoft.ApplicationInsights.AspNetCore pakietu NuGet.

DependencyTrackingTelemetryModule Obecnie śledzi następujące zależności automatycznie:

Zależności	Szczegóły
HTTP/HTTPS	Lokalne lub zdalne wywołania HTTP/HTTPS.
Wywołania WCF	Śledzone automatycznie tylko wtedy, gdy są używane powiązania oparte na protokole HTTP.
SQL	Połączenia wykonane za pomocą SqlClient. Zobacz sekcję Zaawansowane śledzenie SQL, aby uzyskać pełne zapytanie SQL na potrzeby przechwytywania zapytań SQL.
Azure Blob Storage, Table Storage lub Queue Storage	Wywołania wykonywane za pomocą klienta usługi Azure Storage.
Zestaw SDK klienta usługi Azure Event Hubs	Użyj najnowszego pakietu: https://nuget.org/packages/Azure.Messaging.EventHubs.
Zestaw SDK klienta usługi Azure Service Bus	Użyj najnowszego pakietu: https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB	Śledzone automatycznie, jeśli jest używany protokół HTTP/HTTPS. Śledzenie operacji w trybie bezpośrednim przy użyciu protokołu TCP jest przechwytywane automatycznie przy użyciu pakietu >w wersji zapoznawczej = 3.33.0-preview. Aby uzyskać więcej informacji, odwiedź dokumentację.

Jeśli zależność nie została automatycznie zebrana, możesz ją rejestrować ręcznie za pomocą wywołania śledzenia zależności.

Aby uzyskać więcej informacji na temat sposobu działania śledzenia zależności, zobacz Śledzenie zależności w usłudze Application Insights.

Konfigurowanie automatycznego śledzenia zależności w aplikacjach konsoli

Aby automatycznie śledzić zależności z poziomu aplikacji konsolowych platformy .NET, zainstaluj pakiet NuGet Microsoft.ApplicationInsights.DependencyCollector i zainicjuj DependencyTrackingTelemetryModule.

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

Uwaga / Notatka

W aplikacjach konsolowych platformy .NET Core element TelemetryConfiguration.Active jest przestarzały.

Ręczne śledzenie zależności

Następujące przykłady zależności, które nie są zbierane automatycznie, wymagają ręcznego śledzenia:

• Usługa Azure Cosmos DB jest śledzona automatycznie tylko wtedy, gdy jest używany protokół HTTP/HTTPS . Tryb TCP nie jest automatycznie przechwytywany przez usługę Application Insights dla wersji zestawu SDK starszych niż 2.22.0-Beta1.
• Redis

W przypadku tych zależności, które nie są automatycznie zbierane przez zestaw SDK, można je śledzić ręcznie przy użyciu interfejsu API TrackDependency używanego przez standardowe moduły automatycznego zbierania danych.

Przykład

Jeśli budujesz swój kod z użyciem zestawu, którego nie napisałeś samodzielnie, możesz zmierzyć czas wykonania wszystkich wywołań do niego. W tym scenariuszu można dowiedzieć się, jaki wkład ma w czasie odpowiedzi.

Aby wyświetlić te dane na wykresach zależności w usłudze Application Insights, wyślij je przy użyciu polecenia 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);
    }

Alternatywnie, TelemetryClient udostępnia metody rozszerzenia StartOperation i StopOperation, które mogą służyć do ręcznego śledzenia zależności, jak pokazano w śledzeniu zależności wychodzących.

Wyłączanie standardowego modułu śledzenia zależności

Aby uzyskać więcej informacji, zobacz moduły telemetrii.

Zaawansowane śledzenie SQL w celu uzyskania pełnego zapytania SQL

W przypadku wywołań SQL nazwa serwera i bazy danych jest zawsze zbierana i przechowywana jako nazwa zebranego DependencyTelemetryelementu . Inne pole, nazywane danymi, może zawierać pełny tekst zapytania SQL.

Uwaga / Notatka

Usługa Azure Functions wymaga oddzielnych ustawień w celu włączenia zbierania tekstu SQL. Aby uzyskać więcej informacji, zobacz Włączanie zbierania zapytań SQL.

ASP.NET

W przypadku aplikacji ASP.NET pełny tekst zapytania SQL jest zbierany dzięki instrumentacji kodu bajtowego, co wymaga użycia silnika instrumentacji lub wykorzystania pakietu NuGet Microsoft.Data.SqlClient zamiast biblioteki System.Data.SqlClient. Kroki specyficzne dla platformy umożliwiające włączenie pełnej kolekcji zapytań SQL zostały opisane w poniższej tabeli.

Platforma	Kroki potrzebne do uzyskania pełnego zapytania SQL
Usługa Azure App Service dla aplikacji sieciowych	W panelu sterowania aplikacji internetowej otwórz okienko Usługi Application Insights i włącz polecenia SQL na platformie .NET.
Serwer IIS (maszyny wirtualne platformy Azure, środowisko lokalne itd.)	Użyj pakietu NuGet Microsoft.Data.SqlClient lub modułu agenta Application Insights PowerShell, aby zainstalować aparat instrumentacji i ponownie uruchomić IIS.
Azure Cloud Services	Dodaj zadanie uruchamiania, aby zainstalować narzędzie StatusMonitor. Aplikacja powinna zostać dołączona do zestawu SDK usługi ApplicationInsights w czasie kompilacji przez zainstalowanie pakietów NuGet dla aplikacji ASP.NET lub ASP.NET Core.
IIS Express	Użyj pakietu NuGet Microsoft.Data.SqlClient.
Zadania WebJob w usłudze aplikacji Azure	Użyj pakietu NuGet Microsoft.Data.SqlClient.

Oprócz powyższych kroków specyficznych dla platformy należy również jawnie wyrazić zgodę na włączenie zbierania poleceń SQL, modyfikując ApplicationInsights.config plik przy użyciu następującego kodu:

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

ASP.NET Core

W przypadku aplikacji ASP.NET Core należy wyrazić zgodę na zbieranie tekstu SQL przy użyciu:

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

W poprzednich przypadkach właściwym sposobem weryfikacji, czy aparat instrumentacji jest poprawnie zainstalowany, jest zweryfikowanie, czy zebrana DependencyTelemetry wersja zestawu SDK to rddp. rdddsd Użycie funkcji lub rddf wskazuje, że zależności są zbierane za pośrednictwem wywołań DiagnosticSource zwrotnych lub lubEventSource, więc pełne zapytanie SQL nie jest przechwytywane.

Exceptions

Wyjątki w aplikacjach internetowych można zgłaszać za pomocą usługi Application Insights. Żądania niepomyślne można skorelować z wyjątkami i innymi zdarzeniami zarówno na kliencie, jak i serwerze, aby można było szybko zdiagnozować przyczyny. W tej sekcji dowiesz się, jak skonfigurować raportowanie wyjątków, jawnie zgłaszać wyjątki, diagnozować błędy i nie tylko.

Konfigurowanie raportowania wyjątków

Usługę Application Insights można skonfigurować tak, aby zgłaszała wyjątki występujące na serwerze lub kliencie. W zależności od platformy, od której zależy aplikacja, potrzebne jest odpowiednie rozszerzenie lub zestaw SDK.

Server-side

Aby zgłaszać wyjątki z aplikacji po stronie serwera, rozważ następujące scenariusze:

• Dodaj rozszerzenie usługi Application Insights dla aplikacji internetowych platformy Azure.
• Dodaj rozszerzenie monitorowania aplikacji dla maszyn wirtualnych platformy Azure i zestawów skalowania maszyn wirtualnych platformy Azure z aplikacjami hostowanymi w IIS.
• Dodaj zestaw SDK usługi Application Insights do kodu aplikacji, uruchom agenta usługi Application Insights dla serwerów internetowych usług IIS lub włącz agenta Java dla aplikacji internetowych Java.

Client-side

Zestaw SDK języka JavaScript umożliwia raportowanie po stronie klienta wyjątków występujących w przeglądarkach internetowych. Aby skonfigurować raportowanie wyjątków na kliencie, zobacz Application Insights dla stron internetowych.

Struktury aplikacji

W przypadku niektórych struktur aplikacji wymagana jest większa konfiguracja. Rozważ następujące technologie:

• Formularze sieci Web
• MVC
• Internetowy interfejs API 1.*
• Internetowy interfejs API 2.*
• WCF

Ważne

Ta sekcja koncentruje się na aplikacjach .NET Framework z perspektywy przykładu kodu. Niektóre metody, które działają dla platformy .NET Framework, są przestarzałe w zestawie .NET Core SDK.

Diagnozowanie błędów i wyjątków

Azure Portal

Usługa Application Insights zawiera nadzorowane środowisko zarządzania wydajnością aplikacji, które ułatwia diagnozowanie błędów w monitorowanych aplikacjach.

Aby uzyskać szczegółowe instrukcje, zobacz Badanie błędów, wydajności i transakcji za pomocą usługi Application Insights.

Visual Studio

1. Otwórz rozwiązanie aplikacji w programie Visual Studio. Uruchom aplikację na serwerze lub na komputerze deweloperskim przy użyciu F5. Utwórz ponownie wyjątek.

2. Otwórz okno telemetrii wyszukiwania usługi Application Insights w programie Visual Studio. Podczas debugowania wybierz pole listy rozwijanej Application Insights .

3. Wybierz raport wyjątku, aby wyświetlić jego ślad stosu. Aby otworzyć odpowiedni plik kodu, wybierz odwołanie do wiersza w śladzie stosu.

   Jeśli funkcja CodeLens jest włączona, zobaczysz dane dotyczące wyjątków:

   

Niestandardowe śledzenie i dane dziennika

Aby uzyskać dane diagnostyczne specyficzne dla aplikacji, możesz wstawić kod w celu wysłania własnych danych telemetrycznych. Niestandardowe dane telemetryczne lub dane dziennika są wyświetlane w wyszukiwaniu diagnostycznym wraz z żądaniem, widokiem strony i innymi automatycznie zebranymi danymi.

Za pomocą programu Microsoft.VisualStudio.ApplicationInsights.TelemetryClientdostępnych jest kilka interfejsów API:

• TelemetryClient.TrackEvent jest zwykle używany do monitorowania wzorców użycia, ale wysyłane dane są również wyświetlane w obszarze Zdarzenia niestandardowe w wyszukiwaniu diagnostycznym. Zdarzenia są nazwane i mogą przenosić właściwości ciągu i metryki liczbowe, na których można filtrować wyszukiwania diagnostyczne.
• TelemetryClient.TrackTrace umożliwia wysyłanie dłuższych danych, takich jak informacje POST.
• TelemetryClient.TrackException wysyła szczegóły wyjątku, takie jak ślady stosu do usługi Application Insights.

Aby wyświetlić te zdarzenia, w menu po lewej stronie otwórz pozycję Wyszukaj. Wybierz menu rozwijane Typy zdarzeń, a następnie wybierz pozycję Niestandardowe zdarzenie, ślad lub wyjątek.

Uwaga / Notatka

Jeśli aplikacja generuje duże ilości danych telemetrycznych, moduł próbkowania adaptacyjnego automatycznie zmniejsza wolumin wysyłany do portalu, wysyłając tylko reprezentatywny ułamek zdarzeń. Zdarzenia, które są częścią tej samej operacji, są zaznaczone lub zaznaczone jako grupa, aby można było przechodzić między powiązanymi zdarzeniami. Aby uzyskać więcej informacji, zobacz Próbkowanie w usłudze Application Insights.

Zobacz żądanie danych POST

Szczegóły żądania nie zawierają danych wysyłanych do aplikacji w wywołaniu POST. Aby te dane zostały zgłoszone:

• Dodaj zestaw SDK usługi Application Insights do kodu aplikacji.
• Wstaw kod w aplikacji, aby wywołać metodę Microsoft.ApplicationInsights.TrackTrace(). Wyślij dane POST w parametrze komunikatu. Istnieje limit dozwolonego rozmiaru, dlatego należy spróbować wysłać tylko niezbędne dane.
• Po zbadaniu żądania, które zakończyło się niepowodzeniem, znajdź skojarzone ślady.

Przechwytywanie wyjątków i powiązanych danych diagnostycznych

Domyślnie nie wszystkie wyjątki, które powodują błędy w aplikacji, są wyświetlane w portalu. Jeśli używasz zestawu SDK języka JavaScript na stronach internetowych, zobaczysz wyjątki przeglądarki. Jednak większość wyjątków po stronie serwera jest przechwytywane przez usługi IIS, więc należy dodać kod do przechwytywania i raportowania.

Masz następujące możliwości:

• Jawne rejestrowanie wyjątków przez wstawianie kodu w programach obsługi wyjątków w celu raportowania wyjątków.
• Przechwyć wyjątki automatycznie , konfigurując platformę ASP.NET. Niezbędne dodatki różnią się w przypadku różnych typów platform.

Jawne zgłaszanie wyjątków

Najprostszym sposobem raportowania jest wstawienie wywołania metody trackException() w procedurze obsługi wyjątków.

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

Parametry właściwości i pomiarów są opcjonalne, ale są przydatne do filtrowania i dodawania dodatkowych informacji. Jeśli na przykład masz aplikację, która może uruchamiać kilka gier, możesz znaleźć raporty wyjątków związane z określoną grą. Możesz dodać dowolną liczbę elementów do każdego słownika.

Wyjątki przeglądarki

Zgłoszono większość wyjątków przeglądarki.

Jeśli strona internetowa zawiera pliki skryptów z sieci dostarczania zawartości lub innych domen, upewnij się, że tag skryptu ma atrybut crossorigin="anonymous" i że serwer wysyła nagłówki CORS. To zachowanie pozwala uzyskać ślad stosu i szczegóły dla nieobsługiwane wyjątki języka JavaScript z tych zasobów.

Ponowne używanie klienta telemetrii

Uwaga / Notatka

Zalecamy utworzenie wystąpienia TelemetryClient raz i ponowne użycie go przez cały czas działania aplikacji.

W przypadku wstrzykiwania zależności (DI) na platformie .NET, odpowiedniego zestawu .NET SDK i poprawnego konfigurowania usługi Application Insights dla di, można wymagać TelemetryClient parametru jako konstruktora.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

W poprzednim przykładzie parametr TelemetryClient jest wstrzykiwany do ExampleController klasy.

Formularze sieci Web

W przypadku formularzy internetowych moduł HTTP może zbierać wyjątki, gdy nie skonfigurowano przekierowań za pomocą polecenia CustomErrors. Jeśli jednak masz aktywne przekierowania, dodaj następujące wiersze do Application_Error funkcji w Global.asax.cs.

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

W poprzednim przykładzie _telemetryClient jest to zmienna o zakresie klasy typu TelemetryClient.

MVC

Począwszy od zestawu WEB SDK usługi Application Insights w wersji 2.6 (wersja beta 3 lub nowsza), usługa Application Insights automatycznie zbiera nieobsługiwane wyjątki zgłaszane w metodach kontrolerów MVC 5+ . Jeśli wcześniej dodano program obsługi niestandardowej w celu śledzenia takich wyjątków, możesz go usunąć, aby zapobiec podwójnemu śledzeniu wyjątków.

Istnieje kilka scenariuszy, w których filtr wyjątku nie może poprawnie obsługiwać błędów, gdy wyjątki są zgłaszane:

• Z konstruktorów kontrolera
• Z programów obsługi komunikatów
• Podczas routingu
• Podczas serializacji zawartości odpowiedzi
• Podczas uruchamiania aplikacji
• W zadaniach w tle

Wszystkie wyjątki obsługiwane przez aplikację muszą być śledzone ręcznie. Nieobsługiwane wyjątki pochodzące z kontrolerów zwykle powodują odpowiedź 500 "Wewnętrzny błąd serwera". Jeśli taka odpowiedź jest tworzona ręcznie w wyniku obsłużonego wyjątku lub w ogóle nie ma wyjątku, jest ona śledzona w odpowiednich danych telemetrycznych żądania z ResultCode 500. Jednak zestaw SDK usługi Application Insights nie może śledzić odpowiedniego wyjątku.

Obsługa wcześniejszych wersji

Jeśli używasz wzorca MVC 4 (i wcześniejszych) zestawu Web SDK usługi Application Insights w wersji 2.5 (i wcześniejszych), zapoznaj się z poniższymi przykładami, aby śledzić wyjątki.

Rozwiń, aby wyświetlić instrukcje dotyczące wcześniejszych wersji

Jeśli konfiguracja customErrors to Off, wyjątki są dostępne dla modułu HTTP do zebrania. Jeśli jednak jest ustawiona wartość RemoteOnly (wartość domyślna) lub On, wyjątek zostanie wyczyszczone i niedostępny dla usługi Application Insights do automatycznego zbierania. To zachowanie można naprawić, przesłaniając klasę System.Web.Mvc.HandleErrorAttribute i stosując przesłoniętą klasę, jak pokazano w przypadku różnych wersji MVC tutaj (zobacz źródło usługi 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);
        }
    }
}

MVC 2

Zastąp atrybut HandleError nowym atrybutem w kontrolerach:

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

Przykład

MVC 3

Zarejestruj AiHandleErrorAttribute się jako filtr globalny w Global.asax.cs:

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

Przykład

MVC 4, MVC 5

Zarejestruj AiHandleErrorAttribute się jako filtr globalny w FilterConfig.cs:

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

Przykład

Internetowe API

Począwszy od internetowego zestawu SDK usługi Application Insights w wersji 2.6 (wersja beta 3 lub nowsza), usługa Application Insights zbiera nieobsługiwane wyjątki zgłaszane automatycznie w metodach kontrolera dla internetowego interfejsu API 2 lub nowszego. Jeśli wcześniej dodano program obsługi niestandardowej w celu śledzenia takich wyjątków, zgodnie z opisem w poniższych przykładach, możesz go usunąć, aby zapobiec podwójnemu śledzeniu wyjątków.

Istnieje kilka przypadków, w których filtry wyjątków nie mogą obsługiwać. Przykład:

• Wyjątki zgłaszane przez konstruktory kontrolera.
• Wyjątki zgłaszane przez programy obsługi komunikatów.
• Wyjątki zgłaszane podczas routingu.
• Wyjątki zgłaszane podczas serializacji zawartości odpowiedzi.
• Wyjątek zgłaszany podczas uruchamiania aplikacji.
• Wyjątek zgłaszany w zadaniach w tle.

Wszystkie wyjątki obsługiwane przez aplikację muszą być śledzone ręcznie. Nieobsługiwane wyjątki pochodzące z kontrolerów zwykle powodują odpowiedź 500 "Wewnętrzny błąd serwera". Jeśli taka odpowiedź jest tworzona ręcznie w wyniku obsłużonego wyjątku lub w ogóle nie ma wyjątku, jest śledzona w odpowiedniej telemetrii żądania z ResultCode 500. Jednak zestaw SDK usługi Application Insights nie może śledzić odpowiedniego wyjątku.

Obsługa wcześniejszych wersji

Jeśli używasz internetowego interfejsu API 1 (i starszych) zestawu Web SDK usługi Application Insights w wersji 2.5 (i starszych), zapoznaj się z poniższymi przykładami, aby śledzić wyjątki.

Rozwiń, aby wyświetlić instrukcje dotyczące wcześniejszych wersji

Internetowy interfejs API 1.x

Zastąpij 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);
    }
    }
}

Ten zastąpiony atrybut można dodać do określonych kontrolerów lub dodać go do konfiguracji filtru globalnego WebApiConfig w klasie:

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

Przykład

Internetowy interfejs API 2.x

Dodaj implementację polecenia 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);
        }
    }
}

Dodaj ten fragment kodu do usług w pliku 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());
        }
    }
}

Przykład

Alternatywnie można wykonać następujące elementy:

• Zastąp jedyne ExceptionHandler wystąpienie niestandardową implementacją IExceptionHandler. Ta procedura obsługi wyjątków jest wywoływana tylko wtedy, gdy platforma nadal może wybrać komunikat odpowiedzi do wysłania, a nie po przerwaniu połączenia, na przykład.
• Użyj filtrów wyjątków, jak opisano w poprzedniej sekcji na kontrolerach internetowego interfejsu API 1.x, które nie są wywoływane we wszystkich przypadkach.

WCF

Dodaj klasę, która rozszerza i implementuje AttributeIErrorHandler polecenia i 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)
        {
        }
      }
    }

Dodaj atrybut do implementacji usługi:

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

Przykład

Liczniki wydajności wyjątków

Jeśli na serwerze zainstalowano agenta usługi Azure Monitor Application Insights , możesz uzyskać wykres liczby wyjątków mierzonych przez platformę .NET. Uwzględniane są zarówno obsługiwane, jak i nieobsługiwane wyjątki platformy .NET.

Otwórz kartę Eksploratora metryk i dodaj nowy wykres. W obszarze Liczniki wydajności wybierz pozycję Współczynnik wyjątków.

Program .NET Framework oblicza szybkość, zliczając liczbę wyjątków w interwale i dzieląc według długości interwału.

Ta liczba różni się od liczby wyjątków obliczonych przez raporty zliczania TrackException portalu usługi Application Insights. Interwały próbkowania są różne, a zestaw SDK nie wysyła TrackException raportów dla wszystkich obsługiwanych i nieobsługiwalnych wyjątków.

Kolekcja metryk niestandardowych

Zestawy SDK platformy .NET i .NET Core usługi Azure Monitor Application Insights mają dwie różne metody zbierania metryk niestandardowych:

• Metoda TrackMetric() , która nie ma wstępnie agregacji.
• Metoda GetMetric() , która ma preaggregację.

Zalecamy używanie agregacji, więc TrackMetric()nie jest to już preferowana metoda zbierania metryk niestandardowych. Ten artykuł przeprowadzi Cię przez proces używania GetMetric() metody i niektóre uzasadnienie jego działania.

Rozwiń, aby dowiedzieć się więcej na temat wstępnego agregowania a nieprzygotowania interfejsu API

Metoda TrackMetric() wysyła nieprzetworzone dane telemetryczne oznaczające metrykę. Nieefektywne jest wysyłanie pojedynczego elementu telemetrii dla każdej wartości. Metoda TrackMetric() jest również nieefektywna pod względem wydajności, ponieważ każdy TrackMetric(item) przechodzi przez pełny potok zestawu SDK inicjatorów i procesorów telemetrii.

W przeciwieństwie do TrackMetric()programu GetMetric() obsługuje lokalne wstępne agregowanie, a następnie przesyła tylko zagregowaną metrykę podsumowania w stałym interwale jednej minuty. Jeśli musisz dokładnie monitorować metrykę niestandardową na drugim lub nawet milisekundowym poziomie, możesz to zrobić, jednocześnie generując tylko koszt magazynowania i ruchu sieciowego tylko co minutę. To zachowanie znacznie zmniejsza również ryzyko wystąpienia ograniczania przepustowości, ponieważ całkowita liczba elementów telemetrii, które należy wysłać dla zagregowanej metryki, jest znacznie zmniejszona.

W usłudze Application Insights metryki niestandardowe zbierane za pośrednictwem usługi TrackMetric() i GetMetric() nie podlegają próbkowaniu. Próbkowanie ważnych metryk może prowadzić do scenariuszy, w których alerty utworzone wokół tych metryk stają się zawodne. Nigdy nie próbkując metryk niestandardowych, możesz mieć pewność, że po naruszeniu progów alertu alert zostanie wyzwolony. Ponieważ metryki niestandardowe nie są próbkowane, istnieją pewne potencjalne obawy.

Śledzenie trendów w metryce co sekundę lub w jeszcze bardziej szczegółowym interwale może spowodować:

• Zwiększone koszty magazynowania danych. Istnieje koszt związany z ilością danych wysyłanych do usługi Azure Monitor. Im więcej wysyłanych danych, tym większy całkowity koszt monitorowania.
• Zwiększony ruch sieciowy lub obciążenie związane z wydajnością. W niektórych scenariuszach obciążenie to może mieć zarówno koszt wydajności pieniężnej, jak i aplikacji.
• Ryzyko ograniczenia pozyskiwania. Usługa Azure Monitor odrzuca punkty danych ("throttles"), gdy aplikacja wysyła wysoką szybkość telemetrii w krótkim przedziale czasu.

Ograniczanie przepustowości jest problemem, ponieważ może prowadzić do nieodebranych alertów. Warunek wyzwalania alertu może wystąpić lokalnie, a następnie zostać porzucony w punkcie końcowym pozyskiwania z powodu zbyt dużej ilości wysyłanych danych. Nie zalecamy używania dla TrackMetric() platform .NET i .NET Core, chyba że zaimplementowano własną lokalną logikę agregacji. Jeśli próbujesz śledzić każde wystąpienie, które występuje w danym okresie, może się okazać, że TrackEvent() jest to lepsze dopasowanie. Należy pamiętać, że w przeciwieństwie do metryk niestandardowych zdarzenia niestandardowe podlegają próbkowaniu. Nadal można używać TrackMetric() nawet bez konieczności pisania własnej lokalnej preaggregacji. Ale jeśli to zrobisz, pamiętaj o pułapkach.

Podsumowując, zalecamy GetMetric() , ponieważ wykonuje wstępne agregowanie, gromadzi wartości ze wszystkich Track() wywołań i wysyła podsumowanie/agregację raz na minutę. Metoda GetMetric() może znacząco zmniejszyć koszty i obciążenie związane z wydajnością, wysyłając mniej punktów danych, jednocześnie zbierając wszystkie istotne informacje.

Wprowadzenie do usługi GetMetric

W naszych przykładach użyjemy podstawowej aplikacji usługi procesu roboczego platformy .NET Core 3.1. Jeśli chcesz odtworzyć środowisko testowe używane z tymi przykładami, wykonaj kroki 1–6 w sekcji aplikacja usługi procesu roboczego platformy .NET Core. Te kroki dodają usługę Application Insights do podstawowego szablonu projektu usługi procesu roboczego. Koncepcje dotyczą dowolnej aplikacji ogólnej, w której można używać zestawu SDK, w tym aplikacji internetowych i aplikacji konsolowych.

Wysyłanie metryk

Zastąp zawartość worker.cs pliku następującym kodem:

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

Po uruchomieniu przykładowego kodu pętla while jest wielokrotnie wykonywana bez wysyłania danych telemetrycznych w oknie danych wyjściowych programu Visual Studio. Pojedynczy element telemetrii jest wysyłany około 60-sekundowego znacznika, który w naszym teście wygląda następująco:

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"}}}}

Ten pojedynczy element telemetrii reprezentuje agregację 41 odrębnych pomiarów metryk. Ponieważ wysyłaliśmy tę samą wartość ponownie, mamy odchylenie standardowe (stDev) z 0 identycznymi wartościami maksymalnymi (max) i minimalnymi (min). Właściwość value reprezentuje sumę wszystkich poszczególnych wartości, które zostały zagregowane.

Uwaga / Notatka

Metoda GetMetric nie obsługuje śledzenia ostatniej wartości (na przykład gauge) ani śledzenia histogramów lub dystrybucji.

Jeśli zbadamy nasz zasób usługi Application Insights w środowisku dzienników (analiza ), pojedynczy element telemetrii będzie wyglądać jak na poniższym zrzucie ekranu.

Uwaga / Notatka

Podczas gdy nieprzetworzony element telemetrii nie zawierał jawnej właściwości sumy/pola po pozyskaniu, utworzymy go dla Ciebie. W tym przypadku zarówno właściwość , jak value i valueSum reprezentuje to samo.

Dostęp do niestandardowej telemetrii metryk można również uzyskać w sekcji Metryki portalu jako metryki opartej na dzienniku i niestandardowej. Poniższy zrzut ekranu jest przykładem metryki opartej na dzienniku.

Dokumentacja metryk pamięci podręcznej na potrzeby użycia wysokiej przepływności

W niektórych przypadkach wartości metryk mogą być obserwowane często. Na przykład usługa o wysokiej przepływności, która przetwarza 500 żądań na sekundę, może chcieć emitować 20 metryk telemetrii dla każdego żądania. Wynik oznacza śledzenie 10 000 wartości na sekundę. W takich scenariuszach o wysokiej przepływności użytkownicy mogą potrzebować pomocy zestawowi SDK, unikając niektórych odnośników.

Na przykład w poprzednim przykładzie wykonano wyszukiwanie uchwytu dla metryki ComputersSold , a następnie prześledził obserwowaną wartość 42. Zamiast tego dojście może być buforowane dla wielu wywołań śledzenia:

//...

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

Oprócz buforowania uchwytu metryki, powyższy przykład również zmniejszył Task.Delay się do 50 milisekund, aby pętla wykonywała się częściej. Wynik to 772 TrackValue() wywołania.

Metryki wielowymiarowe

W przykładach w poprzedniej sekcji przedstawiono metryki zerowymiarowe. Metryki mogą być również wielowymiarowe. Obecnie obsługujemy maksymalnie 10 wymiarów.

Oto przykład tworzenia metryki jednowymiarowej:

//...

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

Uruchomienie przykładowego kodu przez co najmniej 60 sekund powoduje wysłanie trzech odrębnych elementów telemetrii na platformę Azure. Każdy element reprezentuje agregację jednego z trzech czynników formularzy. Tak jak wcześniej, można dokładniej zbadać w widoku Dzienniki (analiza).

W eksploratorze metryk:

Zwróć uwagę, że nie można podzielić metryki przez nowy niestandardowy wymiar ani wyświetlić niestandardowego wymiaru z widokiem metryk.

Domyślnie metryki wielowymiarowe w eksploratorze metryk nie są włączone w zasobach usługi Application Insights.

Włączanie metryk wielowymiarowych

Aby włączyć metryki wielowymiarowe dla zasobu usługi Application Insights, wybierz pozycję Użycie i szacowane koszty>metryki niestandardowe> metryk >OK. Aby uzyskać więcej informacji, zobacz Niestandardowe wymiary metryk i preaggregacja.

Po wprowadzeniu tej zmiany i wysłaniu nowej telemetrii wielowymiarowej możesz wybrać pozycję Zastosuj dzielenie.

Uwaga / Notatka

Tylko nowo wysłane metryki po włączeniu funkcji w portalu mają przechowywane wymiary.

Wyświetl agregacje metryk dla każdego FormFactor wymiaru.

Użyj MetricIdentifier, jeśli istnieje więcej niż trzy wymiary

Obecnie obsługiwane są 10 wymiarów. Użycie więcej niż trzech wymiarów wymaga użycia elementu 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");

Niestandardowa konfiguracja metryki

Jeśli chcesz zmienić konfigurację metryki, musisz wprowadzić zmiany w miejscu, w którym jest inicjowana metryka.

Specjalne nazwy wymiarów

Metryki nie używają kontekstu telemetrii używanego do uzyskiwania TelemetryClient do nich dostępu. Używanie specjalnych nazw wymiarów dostępnych jako stałe w MetricDimensionNames klasie jest najlepszym obejściem tego ograniczenia.

Agregacje metryk wysyłane przez następującą Special Operation Request Size metryki nie mają Context.Operation.Name ustawionej wartości Special Operation. Metoda lub dowolna TrackMetric() inna TrackXXX() metoda została ustawiona OperationName poprawnie na 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);
                //...
            }
                   
        }

W tej sytuacji należy użyć specjalnych nazw wymiarów wymienionych w MetricDimensionNames klasie, aby określić TelemetryContext wartości.

Na przykład gdy agregacja metryki wynikająca z następnej instrukcji jest wysyłana do punktu końcowego chmury usługi Application Insights, jego Context.Operation.Name pole danych ma wartość Special Operation:

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

Wartość tego specjalnego wymiaru jest kopiowana do TelemetryContext i nie jest używana jako normalny wymiar. Jeśli chcesz również zachować wymiar operacji dla normalnej eksploracji metryki, musisz utworzyć oddzielny wymiar dla tego celu:

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

Ograniczenie wymiarów i szeregów czasowych

Aby zapobiec przypadkowemu używaniu zasobów przez podsystem telemetrii, można kontrolować maksymalną liczbę serii danych na metryki. Limity domyślne to nie więcej niż 1000 łącznych serii danych na metryki i nie więcej niż 100 różnych wartości na wymiar.

Ważne

Użyj niskich wartości kardynaalnych dla wymiarów, aby uniknąć ograniczania przepustowości.

W kontekście ograniczenia wymiarów i szeregów czasowych używamy Metric.TrackValue(..) metody , aby upewnić się, że limity są przestrzegane. Jeśli limity zostały już osiągnięte, Metric.TrackValue(..) zwraca wartość False i wartość nie jest śledzona. W przeciwnym razie zwraca True. To zachowanie jest przydatne, jeśli dane metryki pochodzą z danych wejściowych użytkownika.

Konstruktor MetricConfiguration przyjmuje kilka opcji zarządzania różnymi seriami w ramach odpowiedniej metryki i obiektu klasy implementujące IMetricSeriesConfiguration , która określa zachowanie agregacji dla każdej serii metryki:

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 to maksymalna liczba szeregów czasowych danych, które może zawierać metryka. Po osiągnięciu tego limitu wywołania TrackValue() do tego zwykle spowodują zwrócenie nowej serii .false
• valuesPerDimensionLimit ogranicza liczbę unikatowych wartości na wymiar w podobny sposób.
• restrictToUInt32Values określa, czy powinny być śledzone tylko wartości nieujemne.

Oto przykład wysyłania komunikatu w celu określenia, czy limity limitów zostały przekroczone:

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

Śledzenie operacji niestandardowych

Zestawy SDK usługi Application Insights automatycznie śledzą przychodzące żądania HTTP i wywołania usług zależnych, takie jak żądania HTTP i zapytania SQL. Śledzenie i korelacja żądań i zależności zapewnia wgląd w czas odpowiedzi i niezawodność całej aplikacji we wszystkich mikrousługach łączących tę aplikację.

Istnieje klasa wzorców aplikacji, których nie można ogólnie obsługiwać. Odpowiednie monitorowanie takich wzorców wymaga instrumentacji kodu ręcznego. W tej sekcji opisano kilka wzorców, które mogą wymagać ręcznej instrumentacji, takich jak niestandardowe przetwarzanie kolejek i zadania działające w tle przez dłuższy czas.

Ta sekcja zawiera wskazówki dotyczące śledzenia operacji niestandardowych za pomocą zestawu SDK usługi Application Insights.

Przegląd

Operacja jest logicznym elementem pracy uruchamianym przez aplikację. Ma on nazwę, czas rozpoczęcia, czas trwania, wynik i kontekst wykonywania, taki jak nazwa użytkownika, właściwości i wynik. Jeśli operacja A została zainicjowana przez operację B, operacja B jest ustawiona jako element nadrzędny dla A. Operacja może mieć tylko jeden element nadrzędny, ale może mieć wiele operacji podrzędnych. Aby uzyskać więcej informacji na temat operacji i korelacji telemetrii, zobacz Korelacja telemetrii usługi Application Insights.

W zestawie SDK platformy .NET usługi Application Insights operacja jest opisana przez abstrakcyjną klasę OperationTelemetry i jej elementy potomne RequestTelemetry i DependencyTelemetry.

Śledzenie operacji przychodzących

Zestaw SDK sieci Web usługi Application Insights automatycznie zbiera żądania HTTP dla aplikacji ASP.NET uruchamianych w potoku usług IIS i wszystkich aplikacji ASP.NET Core. Istnieją rozwiązania obsługiwane przez społeczność dla innych platform i struktur. Jeśli aplikacja nie jest obsługiwana przez żadne ze standardowych lub obsługiwanych przez społeczność rozwiązań, możesz przeprowadzić instrumentację ręcznie.

Innym przykładem, który wymaga śledzenia niestandardowego, jest proces roboczy, który odbiera elementy z kolejki. W przypadku niektórych kolejek wywołanie dodawania komunikatu do tej kolejki jest śledzone jako zależność. Operacja wysokiego poziomu, która opisuje przetwarzanie komunikatów, nie jest automatycznie zbierana.

Zobaczmy, jak można śledzić takie operacje.

Na wysokim poziomie zadaniem jest utworzenie RequestTelemetry i ustawienie znanych właściwości. Po zakończeniu operacji można śledzić dane telemetryczne. W poniższym przykładzie pokazano to zadanie.

Żądanie HTTP w aplikacji hostowanej samodzielnie przez firmę Owin

W tym przykładzie kontekst śledzenia jest propagowany zgodnie z protokołem HTTP dla korelacji. Należy spodziewać się otrzymania nagłówków, które zostały tam opisane.

Rozwiń, aby wyświetlić kod

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

Protokół HTTP dla korelacji deklaruje Correlation-Context również nagłówek . Pominięto go tutaj dla uproszczenia.

Instrumentacja kolejki

Kontekst śledzenia W3C i protokół HTTP dla szczegółów korelacji przekazywania korelacji z żądaniami HTTP, ale każdy protokół kolejki musi określić, jak te same szczegóły są przekazywane wzdłuż komunikatu kolejki. Niektóre protokoły kolejki, takie jak AMQP, umożliwiają przekazywanie większej liczby metadanych. Inne protokoły, takie jak kolejka usługi Azure Storage, wymagają kodowania kontekstu w ładunku komunikatu.

Uwaga / Notatka

Śledzenie między składnikami nie jest jeszcze obsługiwane w przypadku kolejek.

W przypadku protokołu HTTP, jeśli producent i odbiorca wysyłają dane telemetryczne do różnych zasobów usługi Application Insights, środowisko diagnostyki transakcji i mapa aplikacji pokazują transakcje i mapuj na koniec. W przypadku kolejek ta funkcja nie jest jeszcze obsługiwana.

Kolejka usługi Service Bus

Aby uzyskać informacje o śledzeniu, zobacz Śledzenie rozproszone i korelacja za pośrednictwem komunikatów usługi Azure Service Bus.

Kolejka usługi Azure Storage

W poniższym przykładzie pokazano, jak śledzić operacje kolejki usługi Azure Storage i korelować dane telemetryczne między producentem, konsumentem i usługą Azure Storage.

Kolejka usługi Storage ma interfejs API HTTP. Wszystkie wywołania kolejki są śledzone przez moduł zbierający zależności usługi Application Insights dla żądań HTTP. Jest ona domyślnie konfigurowana w aplikacjach ASP.NET i ASP.NET Core. W przypadku innych rodzajów aplikacji zapoznaj się z dokumentacją aplikacji konsolowych.

Możesz również skorelować identyfikator operacji usługi Application Insights z identyfikatorem żądania magazynu. Aby uzyskać informacje na temat ustawiania i pobierania klienta żądania magazynu oraz identyfikatora żądania serwera, zobacz Monitorowanie, diagnozowanie i rozwiązywanie problemów z usługą Azure Storage.

Kolejka

Ponieważ kolejki usługi Storage obsługują interfejs API HTTP, wszystkie operacje z kolejką są automatycznie śledzone przez usługę Application Insights. W wielu przypadkach instrumentacja ta powinna wystarczyć. Aby skorelować ślady po stronie konsumenta ze śladami producenta, należy przekazać jakiś kontekst korelacji podobnie do tego, jak robimy to w protokole HTTP dla korelacji.

W tym przykładzie pokazano, jak śledzić operację Enqueue . Masz następujące możliwości:

• Koreluj ponawianie prób (jeśli istnieje): wszystkie mają jeden wspólny element nadrzędny, który jest operacją Enqueue . W przeciwnym razie są one śledzone jako elementy podrzędne żądania przychodzącego. Jeśli istnieje wiele logicznych żądań do kolejki, może być trudno znaleźć wywołanie, które spowodowało ponowne próby.
• Skoreluj dzienniki magazynu (w razie potrzeby): są one skorelowane z telemetrią usługi Application Insights.

Operacja Enqueue jest elementem podrzędnym operacji nadrzędnej. Przykładem jest przychodzące żądanie HTTP. Wywołanie zależności HTTP jest elementem podrzędnym Enqueue operacji i wnukiem żądania przychodzącego.

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

Aby zmniejszyć ilość danych telemetrycznych raportów aplikacji lub jeśli nie chcesz śledzić Enqueue operacji z innych powodów, użyj interfejsu Activity API bezpośrednio:

• Utwórz (i uruchom) nową Activity zamiast rozpoczynać operację usługi Application Insights. Nie musisz przypisywać żadnych właściwości poza nazwą operacji.
• Serializuj yourActivity.Id w ładunku komunikatu zamiast operation.Telemetry.Id. Możesz również użyć Activity.Current.Id.

usunięcie z kolejki

Podobnie jak Enqueuew przypadku usługi Application Insights, rzeczywiste żądanie HTTP do kolejki usługi Storage jest automatycznie śledzone przez usługę Application Insights. Prawdopodobnie Enqueue operacja odbywa się w kontekście nadrzędnym, takim jak kontekst żądania przychodzącego. Zestawy SDK usługi Application Insights automatycznie skorelują taką operację i jej część HTTP z żądaniem nadrzędnym i innymi danymi telemetrycznymi zgłoszonymi w tym samym zakresie.

Operacja Dequeue jest trudna. Zestaw SDK usługi Application Insights automatycznie śledzi żądania HTTP. Nie wie jednak kontekstu korelacji, dopóki komunikat nie zostanie przeanalizowany. Nie można skorelować żądania HTTP w celu pobrania komunikatu z pozostałą częścią telemetrii, zwłaszcza w przypadku odebrania więcej niż jednego komunikatu.

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;
}

Proces

W poniższym przykładzie komunikat przychodzący jest śledzony w sposób podobny do przychodzącego żądania 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);
    }
}

Podobnie można instrumentować inne operacje kolejki. Operację wglądu należy instrumentować w podobny sposób jak operacja dequeue. Instrumentacja operacji zarządzania kolejkami nie jest konieczna. Usługa Application Insights śledzi operacje, takie jak HTTP, a w większości przypadków wystarczy.

Podczas instrumentowania usuwania komunikatów upewnij się, że ustawiono identyfikatory operacji (korelacji). Alternatywnie możesz użyć interfejsu Activity API. Następnie nie musisz ustawiać identyfikatorów operacji na elementach telemetrii, ponieważ zestaw SDK usługi Application Insights wykonuje następujące czynności:

• Utwórz nowy Activity element po utworzeniu elementu z kolejki.
• Służy Activity.SetParentId(message.ParentId) do korelowania dzienników konsumentów i producentów.
• Uruchom plik Activity.
• Śledzenie operacji usuwania z kolejki, przetwarzania i usuwania przy użyciu Start/StopOperation pomocników. Zrób to z tego samego przepływu sterowania asynchronicznego (kontekstu wykonywania). W ten sposób są one prawidłowo skorelowane.
• Zatrzymaj element Activity.
• Ręczne używanie Start/StopOperation danych telemetrycznych lub wywoływanie Track ich.

Typy zależności

Usługa Application Insights używa typu zależności do dostosowywania środowisk interfejsu użytkownika. W przypadku kolejek rozpoznaje następujące typy DependencyTelemetry , które zwiększają środowisko diagnostyki transakcji:

• Azure queue dla kolejek usługi Azure Storage
• Azure Event Hubs dla usługi Azure Event Hubs
• Azure Service Bus dla usługi Azure Service Bus

Przetwarzanie wsadowe

W przypadku niektórych kolejek można usunąć kolejkę wielu komunikatów z jednym żądaniem. Przetwarzanie takich komunikatów jest prawdopodobnie niezależne i należy do różnych operacji logicznych. Nie można skorelować Dequeue operacji z przetwarzanym konkretnym komunikatem.

Każdy komunikat powinien być przetwarzany we własnym asynchronicznym przepływie sterowania. Aby uzyskać więcej informacji, zobacz sekcję Śledzenie zależności wychodzących .

Długotrwałe zadania w tle

Niektóre aplikacje uruchamiają długotrwałe operacje, które mogą być spowodowane żądaniami użytkowników. Z perspektywy śledzenia/instrumentacji nie różni się ona od instrumentacji żądań lub zależności:

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

W tym przykładzie telemetryClient.StartOperation tworzy DependencyTelemetry i wypełnia kontekst korelacji. Załóżmy, że masz operację nadrzędną, która została utworzona przez przychodzące żądania, które planowały operację. Tak długo, jak BackgroundTask rozpoczyna się w tym samym przepływie sterowania asynchronicznym co żądanie przychodzące, jest skorelowany z tą operacją nadrzędną. BackgroundTask i wszystkie zagnieżdżone elementy telemetrii są automatycznie skorelowane z żądaniem, które je spowodowało, nawet po zakończeniu żądania.

Gdy zadanie rozpoczyna się od wątku w tle, który nie ma żadnej operacji (Activity) skojarzonej z nim, BackgroundTask nie ma żadnego elementu nadrzędnego. Może jednak mieć zagnieżdżone operacje. Wszystkie elementy telemetrii zgłoszone z zadania są skorelowane z utworzonym elementem DependencyTelemetry w programie BackgroundTask.

Śledzenie zależności wychodzących

Możesz śledzić własny rodzaj zależności lub operację, która nie jest obsługiwana przez usługę Application Insights.

Enqueue Metoda w kolejce usługi Service Bus lub w kolejce usługi Storage może służyć jako przykłady takiego śledzenia niestandardowego.

Ogólne podejście do niestandardowego śledzenia zależności polega na następujących celach:

• Wywołaj metodę TelemetryClient.StartOperation (extension), która wypełnia DependencyTelemetry właściwości wymagane do korelacji i innych właściwości, takich jak start, sygnatura czasowa i czas trwania.
• Ustaw inne właściwości niestandardowe na DependencyTelemetryobiekcie , takie jak nazwa i dowolny inny kontekst, którego potrzebujesz.
• Utwórz wywołanie zależności i poczekaj na to.
• Zatrzymaj operację StopOperation po zakończeniu.
• Obsługa wyjątków.

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.
        }
    }
}

Usuwanie operacji powoduje zatrzymanie operacji, więc można to zrobić zamiast wywoływać StopOperation.

Ostrzeżenie

W niektórych przypadkach nieobsługiwany wyjątek może uniemożliwićfinally wywoływanie, więc operacje mogą nie być śledzone.

Przetwarzanie i śledzenie operacji równoległych

Wywołanie StopOperation zatrzymuje tylko uruchomioną operację. Jeśli bieżąca uruchomiona operacja jest niezgodna z bieżącą operacją, którą chcesz zatrzymać, StopOperation nic nie robi. Taka sytuacja może wystąpić, jeśli równolegle uruchomisz wiele operacji w tym samym kontekście wykonywania.

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;

Upewnij się, że zawsze wywołujesz StartOperation operację i przetwarzasz operację w tej samej metodzie asynchronicznej , aby odizolować operacje uruchomione równolegle. Jeśli operacja jest synchroniczna (lub nie asynchroniczna), opakuj proces i śledź za pomocą polecenia 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);
}

Operacje usługi ApplicationInsights a System.Diagnostics.Activity

System.Diagnostics.Activity reprezentuje kontekst śledzenia rozproszonego i jest używany przez struktury i biblioteki do tworzenia i propagowania kontekstu wewnątrz i poza procesem oraz korelowania elementów telemetrii. Activity współpracuje ze sobą jako mechanizm powiadamiania między strukturą System.Diagnostics.DiagnosticSource /biblioteką w celu powiadamiania o interesujących zdarzeniach, takich jak przychodzące lub wychodzące żądania i wyjątki.

Działania to funkcje najwyższego poziomu w usłudze Application Insights. Automatyczne zależności i zbieranie żądań polegają na nich w dużym stopniu wraz ze zdarzeniami DiagnosticSource . Jeśli utworzono Activity aplikację, nie spowoduje to utworzenia telemetrii usługi Application Insights. Usługa Application Insights musi odbierać DiagnosticSource zdarzenia i znać nazwy zdarzeń i ładunki, aby przetłumaczyć je Activity na dane telemetryczne.

Każda operacja usługi Application Insights (żądanie lub zależność) obejmuje .Activity Gdy StartOperation jest wywoływany, tworzy Activity pod spodem. StartOperation to zalecany sposób ręcznego śledzenia telemetrii żądań lub zależności i upewnienia się, że wszystko jest skorelowane.

Counters

Usługa Application Insights obsługuje liczniki wydajności i liczniki zdarzeń. Ten przewodnik zawiera omówienie obu tych elementów, w tym ich przeznaczenia, konfiguracji i użycia w aplikacjach platformy .NET.

• Liczniki wydajności są wbudowane w system operacyjny Windows i oferują wstępnie zdefiniowane metryki, takie jak użycie procesora CPU, zużycie pamięci i aktywność dysku. Te liczniki są idealne do monitorowania standardowych metryk wydajności przy minimalnej konfiguracji. Ułatwiają one śledzenie wykorzystania zasobów lub rozwiązywanie problemów z wąskimi gardłami na poziomie systemu w aplikacjach opartych na systemie Windows, ale nie obsługują niestandardowych metryk specyficznych dla aplikacji.

• Liczniki zdarzeń działają na wielu platformach, w tym w systemach Windows, Linux i macOS. Umożliwiają deweloperom definiowanie i monitorowanie lekkich, dostosowywalnych metryk specyficznych dla aplikacji, co zapewnia większą elastyczność niż liczniki wydajności. Liczniki zdarzeń są przydatne, gdy metryki systemowe są niewystarczające lub gdy szczegółowe dane telemetryczne są potrzebne w aplikacjach międzyplatformowych. Wymagają one jawnej implementacji i konfiguracji, co sprawia, że konfiguracja jest bardziej obciążana.

Liczniki wydajności

System Windows udostępnia różne liczniki wydajności, takie jak te używane do zbierania statystyk użycia procesora, pamięci i dysku. Możesz również zdefiniować własne liczniki wydajności.

Aplikacja obsługuje zbieranie liczników wydajności, jeśli działa w obszarze Internet Information Server (IIS) na hoście lokalnym lub maszynie wirtualnej z dostępem administracyjnym. Aplikacje działające jako usługa Azure Web Apps nie mogą bezpośrednio uzyskiwać dostępu do liczników wydajności, ale usługa Application Insights zbiera podzbiór dostępnych liczników.

Wskazówka

Podobnie jak inne metryki, można ustawić alert , aby wyświetlić ostrzeżenie, jeśli licznik przekroczy określony limit. Aby ustawić alert, otwórz okienko Alerty i wybierz pozycję Dodaj alert.

Wymagania wstępne

Przyznaj konto usługi puli aplikacji uprawnienie do monitorowania liczników wydajności, dodając je do grupy Użytkownicy monitora wydajności .

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Wyświetlanie liczników

Okienko Metryki zawiera domyślny zestaw liczników wydajności.

ASP.NET

Domyślne liczniki dla aplikacji internetowych ASP.NET:

• % proces\czas procesora
• % Proces\Znormalizowany czas procesora
• Pamięć\Dostępne bajty
• żądania ASP.NET na sekundę
• Zgłoszone wyjątki środowiska uruchomieniowego języka wspólnego platformy .NET (CLR) na sekundę
• ASP.NET ApplicationsRequest Czas wykonywania
• Proces\Bajty prywatne
• Proces\Bajty danych we/wy na sekundę
• ASP.NET Applications\Requests w kolejce aplikacji
• Procesor (_Total)\ czas procesora%

ASP.NET Core

Domyślne liczniki dla aplikacji internetowych platformy ASP.NET Core:

• % proces\czas procesora
• % Proces\Znormalizowany czas procesora
• Pamięć\Dostępne bajty
• Proces\Bajty prywatne
• Proces\Bajty danych we/wy na sekundę
• Procesor (_Total)\ czas procesora%

Uwaga / Notatka

Obsługa liczników wydajności w ASP.NET Core jest ograniczona:

• Zestaw SDK w wersji 2.4.1 lub nowszej zbiera liczniki wydajności, jeśli aplikacja jest uruchomiona w usłudze Azure Web Apps (Windows).
• Zestaw SDK w wersji 2.7.1 lub nowszej zbiera liczniki wydajności, jeśli aplikacja jest uruchomiona w systemie Windows i elementy docelowe NETSTANDARD2.0 lub nowsze.
• W przypadku aplikacji przeznaczonych dla platformy .NET Framework wszystkie wersje zestawu SDK obsługują liczniki wydajności.
• Zestaw SDK w wersji 2.8.0 lub nowszej obsługuje licznik procesora CPU/pamięci w systemie Linux. Żaden inny licznik nie jest obsługiwany w systemie Linux. Aby uzyskać liczniki systemowe w systemie Linux (i innych środowiskach innych niż Windows), użyj liczników zdarzeń.

Dodawanie liczników

Jeśli żądany licznik wydajności nie znajduje się na liście metryk, możesz go dodać.

ASP.NET

Opcja 1. Konfiguracja w ApplicationInsights.config

1. Dowiedz się, jakie liczniki są dostępne na serwerze przy użyciu tego polecenia programu PowerShell na serwerze lokalnym:

   Get-Counter -ListSet *
   

   Aby uzyskać więcej informacji, zobacz Get-Counter.

2. Otwórz ApplicationInsights.config.

   W przypadku dodania usługi Application Insights do aplikacji podczas programowania:

   1. Edytuj ApplicationInsights.config w projekcie.
   2. Ponownie wdróż go na serwerach.

3. Edytuj dyrektywę modułu zbierającego wydajność:

   
       <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>
   

Przechwytujesz zarówno standardowe liczniki, jak i liczniki, które implementujesz samodzielnie. \Objects\Processes jest przykładem standardowego licznika dostępnego we wszystkich systemach Windows. \Sales(photo)\# Items Sold jest przykładem niestandardowego licznika, który może zostać zaimplementowany w usłudze internetowej.

Format to \Category(instance)\Counter, lub dla kategorii, które nie mają wystąpień, tylko \Category\Counter.

Parametr ReportAs jest wymagany dla nazw liczników, które nie są zgodne [a-zA-Z()/-_ \.]+.

Jeśli określisz wystąpienie, stanie się to wymiarem CounterInstanceName zgłoszonej metryki.

Opcja 2. Konfiguracja w kodzie

Zobacz następującą sekcję.

ASP.NET Core

Skonfiguruj PerformanceCollectorModule po metodzie w pliku 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();

Zbieranie liczników wydajności w kodzie dla aplikacji internetowych ASP.NET lub aplikacji konsolowych .NET/.NET Core

Aby zebrać liczniki wydajności systemu i wysłać je do usługi Application Insights, możesz dostosować następujący fragment kodu:

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

Możesz też wykonać to samo za pomocą utworzonych metryk niestandardowych:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Liczniki wydajności aplikacji działających w kontenerach usługi Azure Web Apps i Windows w usłudze Azure App Service

Aplikacje ASP.NET i ASP.NET Core wdrożone w usłudze Azure Web Apps są uruchamiane w specjalnym środowisku piaskownicy. Aplikacje wdrożone w usłudze Azure App Service mogą korzystać z kontenera systemu Windows lub być hostowane w środowisku piaskownicy. Jeśli aplikacja jest wdrożona w kontenerze systemu Windows, wszystkie standardowe liczniki wydajności są dostępne w obrazie kontenera.

Środowisko piaskownicy nie zezwala na bezpośredni dostęp do liczników wydajności systemu. Jednak ograniczony podzbiór liczników jest uwidaczniony jako zmienne środowiskowe, zgodnie z opisem w temacie Liczniki wydajności uwidocznione jako zmienne środowiskowe. W tym środowisku jest dostępny tylko podzbiór liczników. Aby uzyskać pełną listę, zobacz Liczniki wydajności uwidocznione jako zmienne środowiskowe.

Zestaw SDK usługi Application Insights dla ASP.NET i ASP.NET Core wykrywa, czy kod jest wdrażany w aplikacji internetowej lub w kontenerze innym niż Windows. Wykrywanie określa, czy zbiera liczniki wydajności w środowisku piaskownicy, czy korzysta ze standardowego mechanizmu zbierania, gdy jest hostowany w kontenerze systemu Windows lub maszynie wirtualnej.

Zapytania usługi Log Analytics dotyczące liczników wydajności

Raporty liczników wydajności można przeszukiwać i wyświetlać w usłudze Log Analytics.

Schemat performanceCounters uwidacznia categorynazwę counter i instance nazwę każdego licznika wydajności. W telemetrii dla każdej aplikacji są widoczne tylko liczniki dla tej aplikacji. Aby na przykład zobaczyć, jakie liczniki są dostępne:

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

Instance W tym miejscu odwołuje się do wystąpienia licznika wydajności, a nie roli lub wystąpienia maszyny serwera. Nazwa wystąpienia licznika wydajności zwykle segmentuje liczniki, takie jak czas procesora, według nazwy procesu lub aplikacji.

Aby uzyskać wykres dostępnej pamięci w ostatnim okresie:

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

Podobnie jak inne dane telemetryczne, funkcja performanceCounters zawiera również kolumnę cloud_RoleInstance wskazującą tożsamość wystąpienia serwera hosta, na którym działa aplikacja. Aby na przykład porównać wydajność aplikacji na różnych maszynach:

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

Liczniki wydajności — często zadawane pytania

Aby zapoznać się z często zadawanymi pytaniami, zobacz Często zadawane pytania dotyczące liczników wydajności.

Liczniki zdarzeń

EventCounter to mechanizm .NET/.NET Core do publikowania i korzystania z liczników lub statystyk. EventCounters są obsługiwane na wszystkich platformach systemu operacyjnego — Windows, Linux i macOS. Można go traktować jako odpowiednik międzyplatformowy dla elementów PerformanceCounters , które są obsługiwane tylko w systemach Windows.

Chociaż użytkownicy mogą publikować dowolne niestandardowe liczniki zdarzeń w celu spełnienia ich potrzeb, platforma .NET domyślnie publikuje zestaw tych liczników. W tym dokumencie przedstawiono kroki wymagane do zbierania i wyświetlania liczników zdarzeń (zdefiniowanych przez system lub zdefiniowanych przez użytkownika) w usłudze Azure Application Insights.

Wskazówka

Podobnie jak inne metryki, można ustawić alert , aby wyświetlić ostrzeżenie, jeśli licznik przekroczy określony limit. Aby ustawić alert, otwórz okienko Alerty i wybierz pozycję Dodaj alert.

Zbieranie zdarzeń przy użyciu usługi Application Insights

Usługa Application Insights obsługuje zbieranie EventCounters za pomocą elementu EventCounterCollectionModule, który jest częścią nowo wydanego pakietu NuGet Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule funkcja jest automatycznie włączana w przypadku korzystania z elementu AspNetCore lub WorkerService. EventCounterCollectionModule zbiera liczniki z niekonfiguralną częstotliwością zbierania 60 sekund. Do zbierania zdarzeń nie są wymagane żadne specjalne uprawnienia. W przypadku aplikacji ASP.NET Core należy również dodać pakiet Microsoft.ApplicationInsights.AspNetCore .

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Zebrane liczniki domyślne

Począwszy od wersji 2.15.0 zestawu ASPNetCore SDK lub zestawu WorkerService SDK, domyślnie nie są zbierane żadne liczniki. Sam moduł jest włączony, dzięki czemu użytkownicy mogą dodawać odpowiednie liczniki w celu ich zbierania.

Aby uzyskać listę dobrze znanych liczników opublikowanych przez środowisko uruchomieniowe platformy .NET, zobacz dokument Dostępne liczniki .

Dostosowywanie liczników do zbierania

W poniższym przykładzie pokazano, jak dodawać/usuwać liczniki. To dostosowanie zostanie wykonane w ramach konfiguracji usługi aplikacji po włączeniu zbierania danych telemetrycznych usługi Application Insights przy użyciu polecenia AddApplicationInsightsTelemetry() lub AddApplicationInsightsWorkerService(). Poniżej znajduje się przykładowy kod z aplikacji ASP.NET Core. W przypadku innych typów aplikacji zapoznaj się z tematem Konfigurowanie modułów telemetrii.

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"));
        }
    );

Wyłączanie modułu kolekcji EventCounter

EventCounterCollectionModule można wyłączyć za pomocą polecenia ApplicationInsightsServiceOptions.

W poniższym przykładzie użyto zestawu ASP.NET Core SDK.

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

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

Podobne podejście można również zastosować dla zestawu SDK usługi Worker, ale tę przestrzeń nazw trzeba zmienić, jak to pokazano w poniższym przykładzie.

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

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

Zapytania usługi Log Analytics dotyczące liczników zdarzeń

Raporty liczników zdarzeń można przeszukiwać i wyświetlać w usłudze Log Analytics w tabeli customMetrics .

Uruchom na przykład następujące zapytanie, aby zobaczyć, jakie liczniki są zbierane i dostępne do wykonywania zapytań:

customMetrics | summarize avg(value) by name

Aby uzyskać wykres określonego licznika (na przykład: ThreadPool Completed Work Item Count) w ostatnim okresie, uruchom następujące zapytanie.

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

Podobnie jak inne dane telemetryczne, usługa customMetrics ma również kolumnę cloud_RoleInstance wskazującą tożsamość wystąpienia serwera hosta, na którym działa aplikacja. Poprzednie zapytanie pokazuje wartość licznika na wystąpienie i może służyć do porównywania wydajności różnych wystąpień serwera.

Liczniki zdarzeń — często zadawane pytania

Aby zapoznać się z często zadawanymi pytaniami, zobacz Często zadawane pytania dotyczące liczników zdarzeń.

Kolekcja migawek

Aby dowiedzieć się, jak skonfigurować zbieranie migawek dla aplikacji ASP.NET i ASP.NET Core, zobacz Włączanie debugera migawek dla aplikacji platformy .NET w usłudze Azure Service Fabric, usługach Cloud Services i maszynach wirtualnych.

Node.js

W tym dziale

• Metryki na żywo
• Śledzenie rozproszone
• Metryki rozszerzone
• API TelemetryClient

Metryki na żywo

Aby włączyć wysyłanie metryk na żywo z aplikacji do platformy Azure, użyj polecenia setSendLiveMetrics(true). Obecnie filtrowanie metryk na żywo w portalu nie jest obsługiwane.

Śledzenie rozproszone

Nowoczesne architektury chmury i mikrousług umożliwiają proste, niezależne wdrażanie usług, które zmniejszają koszty przy jednoczesnym zwiększeniu dostępności i przepływności. Jednak sprawiło to, że ogólne systemy stały się trudniejsze do rozumienia i debugowania. Śledzenie rozproszone rozwiązuje ten problem, udostępniając profiler wydajności, który działa jak stosy wywołań dla architektur chmury i mikrousług.

Usługa Azure Monitor udostępnia dwa środowiska korzystania z rozproszonych danych śledzenia: widok diagnostyki transakcji dla pojedynczej transakcji/żądania i widok mapy aplikacji , aby pokazać, jak systemy współdziałają.

Usługa Application Insights może monitorować poszczególne składniki oddzielnie i wykrywać, który składnik jest odpowiedzialny za awarie lub obniżenie wydajności przy użyciu korelacji rozproszonej telemetrii. W tym artykule wyjaśniono model danych, techniki propagacji kontekstu, protokoły i implementację taktyki korelacji na różnych językach i platformach używanych przez usługę Application Insights.

Włącz śledzenie rozproszone za pośrednictwem usługi Application Insights z wykorzystaniem autoinstrumentacji lub SDK.

Agenty i zestawy SDK usługi Application Insights dla platform .NET, .NET Core, Java, Node.js i JavaScript obsługują naturalną obsługę śledzenia rozproszonego.

Po zainstalowaniu i skonfigurowaniu odpowiedniego SDK usługi Application Insights, autokollektory zależności automatycznie zbierają informacje śledzenia dla popularnych frameworków, bibliotek i technologii. Pełna lista obsługiwanych technologii jest dostępna w dokumentacji autocollection zależności.

Każda technologia może być również śledzona ręcznie za pomocą wywołania funkcji TrackDependency w obiekcie TelemetryClient.

Model danych dla korelacji telemetrii

Usługa Application Insights definiuje model danych dla korelacji rozproszonej telemetrii. Aby skojarzyć dane telemetryczne z operacją logiczną, każdy element telemetrii ma pole kontekstu o nazwie operation_Id. Każdy element telemetrii w rozproszonej trasie posiada ten identyfikator. Nawet jeśli utracisz dane telemetryczne z jednej warstwy, nadal można skojarzyć dane telemetryczne zgłaszane przez inne składniki.

Rozproszona operacja logiczna zwykle składa się z zestawu mniejszych operacji, które są żądaniami przetwarzanymi przez jeden ze składników. Telemetria żądania definiuje te operacje. Każdy element telemetrii żądania ma swój własny id, który identyfikuje go unikatowo i globalnie. Wszystkie elementy telemetrii (takie jak ślady i wyjątki) związane z żądaniem powinny ustawiać operation_parentId na wartość odpowiadającą żądaniu id.

Telemetria zależności reprezentuje każdą operację wychodzącą, taką jak wywołanie HTTP do innego składnika. Definiuje również własną id, która jest globalnie unikalna. Telemetria żądania, zainicjowana przez wywołanie tej zależności, używa tego id jako operation_parentId.

Widok rozproszonej operacji logicznej można utworzyć przy użyciu elementów operation_Id, operation_parentIdi request.id .dependency.id Te pola definiują również kolejność przyczynowości wywołań telemetrycznych.

W środowisku mikrousług ślady ze składników mogą przechodzić do różnych elementów magazynu. Każdy składnik może mieć własne parametry połączenia w usłudze Application Insights. Aby uzyskać dane telemetryczne dla operacji logicznej, usługa Application Insights wysyła zapytania o dane z każdego elementu magazynu.

Gdy liczba elementów magazynu jest duża, potrzebujesz wskazówki dotyczącej tego, gdzie szukać dalej. Model danych usługi Application Insights definiuje dwa pola, aby rozwiązać ten problem: request.source i dependency.target. Pierwsze pole identyfikuje składnik, który zainicjował żądanie zależności. Drugie pole identyfikuje, który składnik zwrócił odpowiedź wywołania zależności.

Aby uzyskać informacje na temat wykonywania zapytań z wielu niezależnych instancji, zobacz Wykonywanie zapytań dotyczących danych w obszarach roboczych, aplikacjach i zasobach usługi Log Analytics w usłudze Azure Monitor.

Example

Przyjrzyjmy się przykładowi. Aplikacja o nazwie Ceny akcji pokazuje bieżącą cenę rynkową akcji przy użyciu zewnętrznego interfejsu API o nazwie Stock. Aplikacja Stock Prices ma stronę o nazwie Stock page (Strona giełdowa), która zostanie otwarta w przeglądarce internetowej klienta przy użyciu polecenia GET /Home/Stock. Aplikacja wysyła zapytanie do interfejsu API stock przy użyciu wywołania GET /api/stock/valueHTTP .

Możesz przeanalizować wynikową telemetrię, uruchamiając zapytanie:

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

W wynikach wszystkie elementy telemetrii dzielą wspólny korzeń operation_Id. Gdy ze strony wykonano wywołanie Ajax, do telemetrii zależności zostanie przypisany nowy unikatowy identyfikator (qJSXU), a identyfikator widoku strony jest używany jako operation_ParentId. Następnie żądanie serwera używa identyfikatora Ajax jako operation_ParentId.

typPrzedmiotu	nazwa	identyfikator	operation_ParentId	Id_operacji
pageView	Strona zapasów	STYz		STYz
zależność	GET /Home/Stock	qJSXU	STYz	STYz
żądanie	GET Strona główna/Akcje	KqKwlrSt9PA=	qJSXU	STYz
zależność	GET /api/stock/value	bBrf2L7mm2g=	KqKwlrSt9PA=	STYz

Po wywołaniu GET /api/stock/value usługi zewnętrznej należy znać tożsamość tego serwera, aby można było odpowiednio ustawić dependency.target pole. Jeśli usługa zewnętrzna nie obsługuje monitorowania, target jest ustawiona na nazwę hosta usługi. Przykładem jest stock-prices-api.com. Jeśli jednak usługa identyfikuje się, zwracając wstępnie zdefiniowany nagłówek HTTP, target zawiera tożsamość usługi, co umożliwia Application Insights tworzenie rozproszonego śledzenia przez wykonywanie zapytań dotyczących danych telemetrycznych z tej usługi.

Nagłówki korelacji z użyciem W3C TraceContext.

Usługa Application Insights przechodzi na kontekst śledzenia W3C, który definiuje:

• traceparent: Zawiera globalnie unikalny identyfikator operacji i unikalny identyfikator wywołania.
• tracestate: niesie kontekst śledzenia specyficzny dla systemu.

Najnowsza wersja zestawu SDK usługi Application Insights obsługuje protokół Trace-Context, ale może być konieczne jego wybranie. (Zachowana jest zgodność z poprzednim protokołem korelacji obsługiwanym przez zestaw SDK usługi Application Insights.)

Protokół HTTP korelacji, nazywany również identyfikatorem żądania, jest przestarzały. Ten protokół definiuje dwa nagłówki:

• Request-Id: Przechowuje globalnie unikalny identyfikator połączenia.
• Correlation-Context: zawiera kolekcję par klucz-wartość dla właściwości śledzenia rozproszonego.

Usługa Application Insights definiuje również rozszerzenie dla korelacyjnego protokołu HTTP. Używa par Request-Context nazwa-wartość do propagowania kolekcji właściwości używanych przez bezpośredniego wywołującego lub wywoływanego. Zestaw SDK usługi Application Insights używa tego nagłówka do ustawiania pól dependency.target i request.source.

Modele danych W3C Trace-Context i Application Insights są odwzorowywane w następujący sposób:

Application Insights	W3C TraceContext
Idi RequestDependency	parent-id
Operation_Id	trace-id
Operation_ParentId	parent-id tego zakresu nadrzędnego. To pole musi być puste, jeśli jest to zakres korzeniowy.

Aby uzyskać więcej informacji, zobacz Model danych telemetrycznych usługi Application Insights.

Włącz obsługę śledzenia rozproszonego W3C

Domyślnie zestaw SDK wysyła nagłówki zrozumiałe dla innych aplikacji lub usług zintegrowanych z zestawem SDK usługi Application Insights. Można włączyć wysyłanie i odbieranie nagłówków kontekstu śledzenia W3C oprócz istniejących nagłówków AI. W ten sposób nie zostanie przerwana korelacja z żadnymi istniejącymi starszymi usługami.

Włączenie nagłówków W3C umożliwia aplikacji skorelowanie z innymi usługami, które nie są instrumentowane za pomocą usługi Application Insights, ale przyjmują ten standard W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

Metryki rozszerzone

Uwaga / Notatka

Możliwość wysyłania rozszerzonych metryk natywnych została dodana w wersji 1.4.0.

Aby włączyć wysyłanie rozszerzonych metryk natywnych z aplikacji do platformy Azure, zainstaluj oddzielny pakiet metryk natywnych. Zestaw SDK jest ładowany automatycznie po zainstalowaniu i rozpoczęciu zbierania Node.js metryk natywnych.

npm install applicationinsights-native-metrics

Obecnie pakiet metryk natywnych wykonuje automatyczne monitorowanie czasu procesora używanego przez zbieranie śmieci, tyków pętli zdarzeń oraz użycia sterty.

• Kolekcja śmieci: czas procesora CPU spędzony na każdym typie kolekcji śmieci oraz liczba wystąpień każdego typu.
• Pętla zdarzeń: ile razy się wykonała i ile czasu CPU zużyto w sumie.
• Sterta vs. pamięć niesterty: ile użycia pamięci aplikacji znajduje się w stercie lub niestercie.

Interfejs API TelemetryClient

Pełny opis interfejsu API TelemetryClient można znaleźć w temacie Application Insights API for custom events and metrics (Interfejs API usługi Application Insights na potrzeby metryk i zdarzeń niestandardowych).

Dowolne żądanie, zdarzenie, metryka lub wyjątek można śledzić przy użyciu biblioteki klienta usługi Application Insights dla Node.js. W poniższym przykładzie kodu pokazano niektóre z interfejsów API, których możesz użyć:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Śledzenie zależności

Aby śledzić zależności, użyj następującego kodu:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Przykładowe narzędzie korzystające z trackMetric do mierzenia czasu planowania pętli zdarzeń.

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Dodawanie właściwości niestandardowych do wszystkich zdarzeń

Aby dodać właściwość niestandardową do wszystkich zdarzeń, użyj następującego kodu:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Śledzenie żądań HTTP GET

Użyj następującego kodu, aby ręcznie śledzić żądania HTTP GET:

Uwaga / Notatka

• Wszystkie żądania domyślnie się śledzi. Aby wyłączyć automatyczne zbieranie danych, wywołaj .setAutoCollectRequests(false) przed wywołaniem start().
• Natywne żądania fetch API nie są automatycznie śledzone przez klasyczne rozwiązanie Application Insights; wymagają ręcznego śledzenia zależności.

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

Alternatywnie możesz śledzić żądania przy użyciu trackNodeHttpRequest metody :

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Śledzenie czasu uruchamiania serwera

Aby śledzić czas uruchamiania serwera, użyj poniższego kodu:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Spłukać

Domyślnie dane telemetryczne są buforowane przez 15 sekund przed ich wysłaniem do serwera zbierania danych. Jeśli aplikacja ma krótki czas działania, taką jak narzędzie CLI, może być konieczne ręczne wyczyszczenie buforowanej telemetrii przy jej zakończeniu przy użyciu polecenia appInsights.defaultClient.flush().

Jeśli zestaw SDK wykryje, że aplikacja crashuje, wywołuje funkcję flush przy użyciu polecenia appInsights.defaultClient.flush({ isAppCrashing: true }). W przypadku opcji isAppCrashingopróżniania przyjmuje się, że aplikacja jest w stanie nietypowym i nie jest odpowiednia do wysyłania danych telemetrycznych. Zamiast tego zestaw SDK zapisuje wszystkie buforowane dane telemetryczne do magazynu trwałego i umożliwia zakończenie działania aplikacji. Gdy aplikacja zostanie uruchomiona ponownie, spróbuje wysłać wszelkie dane telemetryczne zapisane w magazynie trwałym.

Przetwarzanie i filtrowanie danych telemetrycznych

.NET

W tym dziale

• Filtrowanie i wstępne przetwarzanie danych telemetrycznych
• Inicjatory telemetrii
• Procesor telemetrii
• Pobieranie próbek
• Wzbogacanie danych za pośrednictwem protokołu HTTP

Filtrowanie i wstępne przetwarzanie danych telemetrycznych

Możesz napisać kod, aby filtrować, modyfikować lub wzbogacać dane telemetryczne przed wysłaniem ich z zestawu SDK. Przetwarzanie obejmuje dane wysyłane ze standardowych modułów telemetrycznych, takich jak zbieranie żądań HTTP i zbieranie zależności.

• Filtrowanie może modyfikować lub odrzucać dane telemetryczne przed ich wysłaniem z zestawu SDK przez zaimplementowanie elementu ITelemetryProcessor. Można na przykład zmniejszyć wolumen danych telemetrycznych poprzez wykluczenie żądań pochodzących od robotów. W przeciwieństwie do próbkowania masz pełną kontrolę nad tym, co jest wysyłane lub odrzucane, ale ma wpływ na wszystkie metryki oparte na zagregowanych dziennikach. W zależności od sposobu odrzucania elementów możesz również utracić możliwość nawigowania między powiązanymi elementami.

• Dodaj lub zmodyfikuj właściwości do dowolnej telemetrii wysłanej z aplikacji, implementując element ITelemetryInitializer. Można na przykład dodać wartości obliczeniowe lub numery wersji, za pomocą których można filtrować dane w portalu.

• Próbkowanie zmniejsza ilość danych telemetrycznych bez wpływu na statystyki. Przechowuje on powiązane punkty danych, dzięki czemu można nawigować między nimi podczas diagnozowania problemu. W portalu całkowite liczby są mnożone, aby zrekompensować próbkowanie.

Uwaga / Notatka

Interfejs API zestawu SDK służy do wysyłania niestandardowych zdarzeń i metryk.

Filtering

Ta technika zapewnia bezpośrednią kontrolę nad elementami dołączonymi lub wykluczonymi ze strumienia telemetrii. Filtrowanie może służyć do odrzucania elementów telemetrii przed wysłaniem ich do usługi Application Insights. Filtrowanie można używać z próbkowaniem lub oddzielnie.

Aby filtrować dane telemetryczne, należy napisać procesor telemetrii i zarejestrować go w pliku TelemetryConfiguration. Wszystkie dane telemetryczne przechodzą przez procesor. Możesz usunąć go ze strumienia lub przekazać go do następnego procesora w łańcuchu. Dane telemetryczne ze standardowych modułów, takich jak moduł zbierający żądania HTTP i moduł zbierający zależności, oraz dane telemetryczne, które śledziłeś samodzielnie, są uwzględniane. Można na przykład odfiltrować dane telemetryczne dotyczące żądań z robotów lub pomyślnych wywołań zależności.

Ostrzeżenie

Filtrowanie danych telemetrycznych wysyłanych z zestawu SDK przy użyciu procesorów może wypaczyć statystyki widoczne w portalu i utrudniać obserwowanie powiązanych elementów.

Zamiast tego rozważ użycie próbkowania.

ITelemetryProcessor i ITelemetryInitializer

Jaka jest różnica między procesorami telemetrii a inicjatorami telemetrii?

• Niektóre czynności się pokrywają, które można zrobić z ich pomocą. Oba te elementy mogą służyć do dodawania lub modyfikowania właściwości telemetrii, chociaż zalecamy używanie inicjatorów do tego celu.
• Inicjatory telemetrii są zawsze uruchamiane przed procesorami telemetrii.
• Inicjatory telemetrii mogą być wywoływane więcej niż raz. Zgodnie z konwencją nie ustawiają żadnej właściwości, która została już ustawiona.
• Procesory telemetryczne umożliwiają całkowite zastąpienie lub odrzucenie elementu telemetrii.
• Wszystkie zarejestrowane inicjatory telemetrii są wywoływane dla każdego elementu telemetrii. W przypadku procesorów telemetrycznych zestaw SDK gwarantuje wywołanie pierwszego procesora telemetrii. To, czy pozostałe procesory są wywoływane, zależy od poprzedzających procesorów telemetrycznych.
• Użyj inicjatorów telemetrii, aby wzbogacić dane telemetryczne dodatkowymi właściwościami lub nadpisać istniejące. Użyj procesora telemetrii, aby odfiltrować dane telemetryczne.

Dodawanie/modyfikowanie właściwości

Inicjatory telemetrii umożliwiają wzbogacanie telemetrii dodatkowymi informacjami lub zastępowanie właściwości telemetrii ustawionych przez standardowe moduły telemetryczne.

Na przykład usługa Application Insights dla pakietu internetowego zbiera dane telemetryczne dotyczące żądań HTTP. Domyślnie oznacza każde żądanie z kodem odpowiedzi równym 400 jako niepowodzenie. Jeśli zamiast tego chcesz traktować 400 jako sukces, możesz podać inicjator telemetrii, który ustawia właściwość "sukces".

Jeśli podasz inicjator telemetrii, będzie on wywoływany za każdym razem, gdy zostanie wywołana dowolna z metod Track*(). Ten inicjalizator zawiera metody Track(), które są wywoływane przez standardowe moduły telemetrii. Zgodnie z konwencją te moduły nie ustawiają żadnej właściwości, która została już ustawiona przez inicjator. Inicjatory telemetrii są wywoływane przed wywołaniem procesorów telemetrii, więc wszelkie wzbogacania wykonywane przez inicjatory są widoczne dla procesorów.

Inicjatory telemetrii

Aby wzbogacić dane telemetryczne dodatkowymi informacjami lub zastąpić właściwości telemetrii ustawione przez standardowe moduły telemetrii, użyj inicjatorów telemetrii.

Inicjatory telemetrii ustawiają właściwości kontekstu wysyłane wraz z każdym elementem telemetrii. Możesz napisać własne inicjatory, aby ustawić właściwości kontekstu.

Wszystkie standardowe inicjatory są ustawiane przez pakiety NuGet web lub WindowsServer:

Inicjatora	Description
AccountIdTelemetryInitializer	AccountId Ustawia właściwość .
AuthenticatedUserIdTelemetryInitializer	Ustawia właściwość ustawioną AuthenticatedUserId przez zestaw SDK języka JavaScript.
AzureRoleEnvironmentTelemetryInitializer	RoleName Aktualizuje właściwości RoleInstance i Device kontekstu dla wszystkich elementów telemetrii z informacjami wyodrębnianymi ze środowiska uruchomieniowego platformy Azure.
BuildInfoConfigComponentVersionTelemetryInitializer	Version Aktualizuje właściwość Component kontekstu dla wszystkich elementów telemetrii o wartości wyodrębnionej z pliku utworzonego BuildInfo.config przez program MS Build.
ClientIpHeaderTelemetryInitializer	Ip Aktualizuje właściwość Location kontekstu wszystkich elementów telemetrii na X-Forwarded-For podstawie nagłówka HTTP żądania.
DeviceTelemetryInitializer	Aktualizuje następujące właściwości Device kontekstu dla wszystkich elementów telemetrii: • Type jest ustawiona na PCwartość . • Id jest ustawiona na nazwę domeny komputera, na którym działa aplikacja internetowa. • OemName jest ustawiona na wartość wyodrębnianą z Win32_ComputerSystem.Manufacturer pola przy użyciu usługi WMI. • Model jest ustawiona na wartość wyodrębnianą z Win32_ComputerSystem.Model pola przy użyciu usługi WMI. • NetworkType jest ustawiona na wartość wyodrębnianą z NetworkInterface właściwości . • Language jest ustawiona na nazwę CurrentCulture właściwości.
DomainNameRoleInstanceTelemetryInitializer	RoleInstance Aktualizuje właściwość Device kontekstu dla wszystkich elementów telemetrii o nazwie domeny komputera, na którym działa aplikacja internetowa.
OperationNameTelemetryInitializer	Name Aktualizuje właściwość i RequestTelemetry właściwość NameOperation kontekstu wszystkich elementów telemetrii na podstawie metody HTTP oraz nazwy kontrolera ASP.NET MVC i akcji wywoływanej w celu przetworzenia żądania.
OperationIdTelemetryInitializer lub OperationCorrelationTelemetryInitializer	Operation.Id Aktualizuje właściwość kontekstu wszystkich elementów telemetrii śledzonych podczas obsługi żądania przy użyciu automatycznie wygenerowanego RequestTelemetry.Idelementu .
SessionTelemetryInitializer	Id Aktualizuje właściwość Session kontekstu dla wszystkich elementów telemetrii o wartości wyodrębnionej z ai_session pliku cookie wygenerowanego przez ApplicationInsights kod instrumentacji JavaScript uruchomiony w przeglądarce użytkownika.
SyntheticTelemetryInitializer lub SyntheticUserAgentTelemetryInitializer	UserAktualizuje właściwości kontekstu , Sessioni Operation wszystkich elementów telemetrii śledzonych podczas obsługi żądania ze źródła syntetycznego, takiego jak test dostępności lub bot wyszukiwarki. Domyślnie eksplorator metryk nie wyświetla syntetycznych danych telemetrycznych. Zestaw <Filters> identyfikujący właściwości żądań.
UserTelemetryInitializer	Id Aktualizuje właściwości AcquisitionDate i User kontekstu dla wszystkich elementów telemetrii z wartościami wyodrębnianymi z ai_user pliku cookie wygenerowanego przez kod instrumentacji JavaScript usługi Application Insights uruchomiony w przeglądarce użytkownika.
WebTestTelemetryInitializer	Ustawia identyfikator użytkownika, identyfikator sesji i syntetyczne właściwości źródła dla żądań HTTP pochodzących z testów dostępności. Zestaw <Filters> identyfikujący właściwości żądań.

Uwaga / Notatka

W przypadku aplikacji platformy .NET działających w usłudze Azure Service Fabric można uwzględnić Microsoft.ApplicationInsights.ServiceFabric pakiet NuGet. Ten pakiet zawiera FabricTelemetryInitializer właściwość, która dodaje właściwości usługi Service Fabric do elementów telemetrii. Aby uzyskać więcej informacji, zobacz stronę usługi GitHub na temat właściwości dodanych przez ten pakiet NuGet.

Dodaj ITelemetryInitializer

W tym blogu opisano projekt do diagnozowania problemów z zależnościami przez automatyczne wysyłanie regularnych poleceń ping do zależności.

1. Definiowanie inicjatora

   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. Załaduj swój inicjator

ASP.NET

Opcja 1. Konfiguracja w kodzie

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

Opcja 2. Konfiguracja w ApplicationInsights.config

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

Zobacz więcej tego przykładu.

Uwaga / Notatka

Upewnij się, że plik applicationinsights.config znajduje się w katalogu wyjściowym i zawiera wszelkie ostatnie zmiany.

ASP.NET Core

Dodawanie inicjatora przy użyciu polecenia ApplicationInsights.config lub TelemetryConfiguration.Active nie jest prawidłowe w przypadku aplikacji ASP.NET Core.

W przypadku aplikacji napisanych przy użyciu ASP.NET Core dodanie nowego inicjatora telemetrii odbywa się przez dodanie go do kontenera DependencyInjection , jak pokazano poniżej. Ten krok należy wykonać w metodzie Startup.ConfigureServices .

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Uwaga / Notatka

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); działa w przypadku prostych inicjatorów. W przypadku innych jest builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); wymagany.

Usuwanie inicjatorów telemetrii

Domyślnie są obecne inicjatory telemetrii. Aby usunąć wszystkie lub określone inicjatory telemetrii, użyj następującego przykładowego kodu po wywołaniu metody 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();

Usługa procesu roboczego

Dodawanie inicjatora przy użyciu ApplicationInsights.config lub TelemetryConfiguration.Active nie jest prawidłowe dla SDK usługi Worker Service.

W przypadku aplikacji napisanych przy użyciu usługi Worker Service dodanie nowego inicjatora telemetrii odbywa się przez dodanie go do kontenera DependencyInjection , jak pokazano poniżej. Ten krok należy wykonać w metodzie Startup.ConfigureServices .

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

Usuwanie inicjatorów telemetrii

Inicjatory telemetrii są domyślnie obecne. Aby usunąć wszystkie lub określone inicjatory telemetrii, użyj następującego przykładowego kodu po wywołaniu metody 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));
   }

Przykład ITelemetryInitializers

Dodaj właściwość niestandardową

Poniższy przykładowy inicjalizator dodaje właściwość niestandardową do każdej śledzonej telemetrii.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Dodawanie nazwy roli chmury i wystąpienia roli w chmurze

Krok 1: Napisz niestandardowy TelemetryInitializer

Poniższy przykładowy inicjalizator ustawia nazwę roli w chmurze dla każdej śledzonej telemetrii.

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";
            }
        }
    }
}

Krok 2: Załaduj inicjalizator do TelemetryConfiguration

ASP.NET

W pliku ApplicationInsights.config :

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

Alternatywną metodą dla aplikacji internetowych ASP.NET jest utworzenie wystąpienia inicjatora w kodzie. W poniższym przykładzie pokazano kod w pliku Global.aspx.cs :

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

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

ASP.NET Core

Aby dodać nowe wystąpienie TelemetryInitializer, musisz je dodać do kontenera wstrzykiwania zależności. W poniższym przykładzie przedstawiono to podejście. Dodaj ten kod w metodzie ConfigureServices klasy Startup.cs.

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Kontrolowanie adresu IP klienta używanego do mapowania geolokalizacji

Poniższy przykładowy inicjator ustawia adres IP klienta, który jest używany do mapowania geolokalizacji, zamiast adresu IP gniazda klienta podczas pozyskiwania danych telemetrycznych.

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;
}

Procesory telemetrii

Procesory telemetryczne mogą filtrować i modyfikować każdy element telemetrii przed wysłaniem go z zestawu SDK do portalu.

Narzędzie ITelemetryProcessor

Procesory telemetryczne konstruują łańcuch przetwarzania. Podczas instancjowania procesora telemetrycznego uzyskujesz referencję do kolejnego procesora w szeregu. Gdy punkt danych telemetrycznych jest przekazywany do metody procesu, wykonuje swoją pracę, a następnie wywołuje (lub nie wywołuje) następnego procesora telemetrii w łańcuchu.

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;
    }
}

Dodaj swój procesor

ASP.NET

Wstaw ten fragment kodu w ApplicationInsights.config:

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

Wartości ciągów można przekazywać z pliku .config poprzez udostępnienie publicznie dostępnych nazwanych właściwości w klasie.

Ostrzeżenie

Należy zachować ostrożność, aby dopasować nazwę typu i wszystkie nazwy właściwości w pliku .config do nazw klas i właściwości w kodzie. Jeśli plik .config odwołuje się do nieistnienego typu lub właściwości, zestaw SDK może dyskretnie nie wysyłać żadnych danych telemetrycznych.

Alternatywnie można zainicjować filtr w kodzie. W odpowiedniej klasie inicjalizacyjnej, na przykład AppStart w Global.asax.cs, wstaw swój procesor do łańcucha.

Uwaga / Notatka

Poniższy przykład kodu jest przestarzały, ale jest dostępny tutaj dla potomności. Rozważ rozpoczęcie pracy z usługą OpenTelemetry lub migrację do usługi 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();

Klienci telemetrii utworzeni od tego momentu używają twoje procesory.

Adaptacyjny procesor telemetrii próbkowania (z wersji 2.0.0-beta3)

Ta funkcja jest domyślnie włączona. Jeśli aplikacja wysyła znaczną ilość danych telemetrycznych, ten procesor usunie niektóre z nich.

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

Parametr udostępnia element docelowy, który algorytm próbuje osiągnąć. Każde wystąpienie zestawu SDK działa niezależnie. W związku z tym, jeśli serwer jest klastrem kilku maszyn, rzeczywista ilość danych telemetrycznych jest odpowiednio pomnożona.

Dowiedz się więcej o próbkowaniu.

Procesor telemetrii próbkowania o stałej szybkości (z wersji 2.0.0-beta1)

Istnieje również standardowy procesor telemetrii próbkowania (z wersji 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

Uwaga / Notatka

Dodawanie procesora przy użyciu ApplicationInsights.config lub TelemetryConfiguration.Active nie jest prawidłowe w przypadku aplikacji ASP.NET Core ani używania zestawu SDK Microsoft.ApplicationInsights.WorkerService.

W przypadku ASP.NET Core dodanie nowego procesora telemetrii odbywa się przy użyciu AddApplicationInsightsTelemetryProcessor metody rozszerzenia w pliku IServiceCollection, jak pokazano poniżej. Ta metoda jest wywoływana w metodzie ConfigureServices klasy 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();

Aby zarejestrować procesory telemetryczne, które wymagają parametrów w ASP.NET Core, utwórz niestandardową klasę implementjącą ITelemetryProcessorFactory. Wywołaj konstruktor z żądanymi parametrami w metodzie Create , a następnie użyj polecenia AddSingleton<ITelemetryProcessorFactory, MyTelemetryProcessorFactory>().

Usługa procesu roboczego

Uwaga / Notatka

Dodawanie procesora przy użyciu ApplicationInsights.config lub TelemetryConfiguration.Active nie jest prawidłowe w przypadku aplikacji ASP.NET Core ani używania zestawu SDK Microsoft.ApplicationInsights.WorkerService.

Dla Worker Service, dodanie nowego procesora telemetrii odbywa się przy użyciu metody rozszerzenia AddApplicationInsightsTelemetryProcessor na IServiceCollection, jak pokazano. Ta metoda jest wywoływana w metodzie ConfigureServices klasy Startup.cs.

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

Przykładowe filtry

Żądania syntetyczne

Odfiltruj boty i testy internetowe. Mimo że Eksplorator metryk udostępnia opcję filtrowania źródeł syntetycznych, ta opcja zmniejsza rozmiar przepływu danych i ilości pozyskiwanych danych poprzez filtrowanie ich bezpośrednio w zestawie SDK.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Uwierzytelnianie nie powiodło się

Odfiltruj żądania za pomocą odpowiedzi "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);
}

Filtrowanie szybkich wywołań zależności zdalnych

Jeśli chcesz zdiagnozować tylko wolne połączenia, odfiltruj szybkie.

Uwaga / Notatka

To filtrowanie powoduje niesymetryczność statystyk widocznych w portalu.

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

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

Pobieranie próbek

Aby dowiedzieć się, jak skonfigurować próbkowanie dla aplikacji ASP.NET i ASP.NET Core, zobacz Próbkowanie w usłudze Application Insights.

Usługa procesu roboczego

Zestaw SDK usługi Application Insights dla usługi Worker Service obsługuje próbkowanie o stałej szybkości i próbkowanie adaptacyjne. Próbkowanie adaptacyjne jest domyślnie włączone. Próbkowanie można wyłączyć za pomocą funkcji EnableAdaptiveSampling w ApplicationInsightsServiceOptions.

Aby skonfigurować inne ustawienia próbkowania, możesz użyć następującego przykładu:

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

Wzbogacanie danych za pośrednictwem protokołu 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

Node.js

W tym dziale

• Filtrowanie i wstępne przetwarzanie danych telemetrycznych
• Inicjatory telemetrii
• Procesor telemetrii
• Pobieranie próbek
• Wiele ról dla aplikacji wieloskładnikowych

Filtrowanie i wstępne przetwarzanie danych telemetrycznych

Możesz napisać kod, aby filtrować, modyfikować lub wzbogacać dane telemetryczne przed wysłaniem ich z zestawu SDK. Przetwarzanie obejmuje dane wysyłane ze standardowych modułów telemetrycznych, takich jak zbieranie żądań HTTP i zbieranie zależności.

• Filtrowanie może modyfikować lub odrzucać dane telemetryczne przed ich wysłaniem z zestawu SDK przez zaimplementowanie elementu ITelemetryProcessor. Można na przykład zmniejszyć wolumen danych telemetrycznych poprzez wykluczenie żądań pochodzących od robotów. W przeciwieństwie do próbkowania masz pełną kontrolę nad tym, co jest wysyłane lub odrzucane, ale ma wpływ na wszystkie metryki oparte na zagregowanych dziennikach. W zależności od sposobu odrzucania elementów możesz również utracić możliwość nawigowania między powiązanymi elementami.

• Dodaj lub zmodyfikuj właściwości do dowolnej telemetrii wysłanej z aplikacji, implementując element ITelemetryInitializer. Można na przykład dodać wartości obliczeniowe lub numery wersji, za pomocą których można filtrować dane w portalu.

• Próbkowanie zmniejsza ilość danych telemetrycznych bez wpływu na statystyki. Przechowuje on powiązane punkty danych, dzięki czemu można nawigować między nimi podczas diagnozowania problemu. W portalu całkowite liczby są mnożone, aby zrekompensować próbkowanie.

Uwaga / Notatka

Interfejs API zestawu SDK służy do wysyłania niestandardowych zdarzeń i metryk.

Filtering

Ta technika zapewnia bezpośrednią kontrolę nad elementami dołączonymi lub wykluczonymi ze strumienia telemetrii. Filtrowanie może służyć do odrzucania elementów telemetrii przed wysłaniem ich do usługi Application Insights. Filtrowanie można używać z próbkowaniem lub oddzielnie.

Aby filtrować dane telemetryczne, należy napisać procesor telemetrii i zarejestrować go w pliku TelemetryConfiguration. Wszystkie dane telemetryczne przechodzą przez procesor. Możesz usunąć go ze strumienia lub przekazać go do następnego procesora w łańcuchu. Dane telemetryczne ze standardowych modułów, takich jak moduł zbierający żądania HTTP i moduł zbierający zależności, oraz dane telemetryczne, które śledziłeś samodzielnie, są uwzględniane. Można na przykład odfiltrować dane telemetryczne dotyczące żądań z robotów lub pomyślnych wywołań zależności.

Ostrzeżenie

Filtrowanie danych telemetrycznych wysyłanych z zestawu SDK przy użyciu procesorów może wypaczyć statystyki widoczne w portalu i utrudniać obserwowanie powiązanych elementów.

Zamiast tego rozważ użycie próbkowania.

ITelemetryProcessor i ITelemetryInitializer

Jaka jest różnica między procesorami telemetrii a inicjatorami telemetrii?

• Niektóre czynności się pokrywają, które można zrobić z ich pomocą. Oba te elementy mogą służyć do dodawania lub modyfikowania właściwości telemetrii, chociaż zalecamy używanie inicjatorów do tego celu.
• Inicjatory telemetrii są zawsze uruchamiane przed procesorami telemetrii.
• Inicjatory telemetrii mogą być wywoływane więcej niż raz. Zgodnie z konwencją nie ustawiają żadnej właściwości, która została już ustawiona.
• Procesory telemetryczne umożliwiają całkowite zastąpienie lub odrzucenie elementu telemetrii.
• Wszystkie zarejestrowane inicjatory telemetrii są wywoływane dla każdego elementu telemetrii. W przypadku procesorów telemetrycznych zestaw SDK gwarantuje wywołanie pierwszego procesora telemetrii. To, czy pozostałe procesory są wywoływane, zależy od poprzedzających procesorów telemetrycznych.
• Użyj inicjatorów telemetrii, aby wzbogacić dane telemetryczne dodatkowymi właściwościami lub nadpisać istniejące. Użyj procesora telemetrii, aby odfiltrować dane telemetryczne.

Dodawanie/modyfikowanie właściwości

Inicjatory telemetrii umożliwiają wzbogacanie telemetrii dodatkowymi informacjami lub zastępowanie właściwości telemetrii ustawionych przez standardowe moduły telemetryczne.

Na przykład usługa Application Insights dla pakietu internetowego zbiera dane telemetryczne dotyczące żądań HTTP. Domyślnie oznacza każde żądanie z kodem odpowiedzi równym 400 jako niepowodzenie. Jeśli zamiast tego chcesz traktować 400 jako sukces, możesz podać inicjator telemetrii, który ustawia właściwość "sukces".

Jeśli podasz inicjator telemetrii, będzie on wywoływany za każdym razem, gdy zostanie wywołana dowolna z metod Track*(). Ten inicjalizator zawiera metody Track(), które są wywoływane przez standardowe moduły telemetrii. Zgodnie z konwencją te moduły nie ustawiają żadnej właściwości, która została już ustawiona przez inicjator. Inicjatory telemetrii są wywoływane przed wywołaniem procesorów telemetrii, więc wszelkie wzbogacania wykonywane przez inicjatory są widoczne dla procesorów.

Procesory telemetrii

Zebrane dane można przetwarzać i filtrować przed wysłaniem ich do przechowywania przy użyciu procesorów telemetrycznych. Procesory telemetryczne są wywoływane pojedynczo w kolejności, w której zostały dodane przed wysłaniem elementu telemetrii do chmury.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Jeśli procesor telemetrii zwróci wartość false, ten element telemetrii nie jest wysyłany.

Wszystkie procesory telemetryczne odbierają dane telemetryczne i jego kopertę w celu sprawdzenia i zmodyfikowania. Otrzymują również obiekt kontekstu. Zawartość tego obiektu jest definiowana przez parametr contextObjects podczas wywoływania metody track w przypadku ręcznie śledzonej telemetrii. W przypadku automatycznie zebranych danych telemetrycznych ten obiekt jest wypełniany dostępnymi informacjami o żądaniu oraz trwałą zawartością żądania, jak dostarczono przez appInsights.getCorrelationContext() (jeśli włączono automatyczną korelację zależności).

TypeScript dla procesora telemetrii to:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Na przykład procesor, który usuwa dane śledzenia stosów z wyjątków, może zostać zapisany i dodany w następujący sposób:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Dodawanie nazwy roli chmury i wystąpienia roli w chmurze

Ustaw nazwę roli chmury za pomocą bezpośrednich tagów kontekstu:

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Ustaw nazwę roli chmury za pomocą procesora telemetrii:

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

Pobieranie próbek

Domyślnie zestaw SDK wysyła wszystkie zebrane dane do usługi Application Insights. Jeśli chcesz włączyć próbkowanie, aby zmniejszyć ilość danych, ustaw samplingPercentage pole na config obiekcie klienta. Ustawienie samplingPercentage wartości 100 (wartość domyślna) oznacza, że wszystkie dane zostaną wysłane, a 0 oznacza, że nic nie zostanie wysłane.

Jeśli używasz automatycznej korelacji, wszystkie dane skojarzone z pojedynczym żądaniem są dołączane lub wykluczane jako jednostka.

Dodaj kod, jak poniższy, aby włączyć próbkowanie.

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Wiele ról dla aplikacji wieloskładnikowych

W niektórych scenariuszach aplikacja może składać się z wielu składników, które chcesz monitorować przy użyciu tego samego ciągu połączenia. Chcesz nadal widzieć te składniki jako oddzielne jednostki w portalu, tak jakby używały oddzielnych ciągów połączeń. Przykładem są oddzielne węzły na mapie aplikacji. Należy ręcznie skonfigurować RoleName pole, aby odróżnić dane telemetryczne jednego składnika od innych składników, które wysyłają dane do zasobu usługi Application Insights.

Użyj następującego kodu, aby ustawić RoleName pole:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Konfiguracja zestawu SDK

.NET

W tym dziale

• Kanały telemetrii
• Moduły telemetrii
• Wyłączanie telemetrii
• Parametry połączenia
• Dostawca identyfikatora aplikacji

Można dostosować SDK Application Insights dla ASP.NET, ASP.NET Core i usługi Worker Service, aby zmienić konfigurację domyślną.

ASP.NET

Zestaw SDK platformy .NET usługi Application Insights składa się z wielu pakietów NuGet. Pakiet podstawowy udostępnia interfejs API do wysyłania danych telemetrycznych do usługi Application Insights. Więcej pakietów udostępnia moduły telemetrii i inicjatory do automatycznego śledzenia danych telemetrycznych z aplikacji i jej kontekstu. Dostosowując plik konfiguracji, można włączyć lub wyłączyć moduły telemetrii i inicjatory. Można również ustawić parametry dla niektórych z nich.

Plik konfiguracji ma nazwę ApplicationInsights.config lub ApplicationInsights.xml. Nazwa zależy od typu aplikacji. Jest on automatycznie dodawany do projektu podczas instalowania większości wersji zestawu SDK.

Domyślnie, gdy używasz zautomatyzowanego środowiska z projektów szablonów programu Visual Studio, które obsługują dodawanie>telemetrii usługi Application Insights, ApplicationInsights.config plik jest tworzony w folderze głównym projektu. Po skompilowaniu plik zostanie skopiowany do folderu bin. Jest on również dodawany do aplikacji internetowej przez agenta usługi Application Insights na serwerze usług IIS.

Ważne

Plik konfiguracji jest ignorowany, jeśli jest używane rozszerzenie dla witryn internetowych platformy Azure lub rozszerzenia dla maszyn wirtualnych platformy Azure i zestawów skalowania maszyn wirtualnych platformy Azure .

Nie ma równoważnego pliku do kontrolowania zestawu SDK na stronie internetowej.

ASP.NET Core

W aplikacjach ASP.NET Core wszystkie zmiany konfiguracji są wprowadzane w ConfigureServices() metodzie klasy Startup.cs , chyba że zostaną inaczej skierowane.

Uwaga / Notatka

W aplikacjach ASP.NET Core zmiana konfiguracji przez zmodyfikowanie TelemetryConfiguration.Active nie jest obsługiwana.

Usługa procesu roboczego

Wartość domyślna TelemetryConfiguration używana przez zestaw SDK usługi procesu roboczego jest podobna do automatycznej konfiguracji używanej w aplikacji ASP.NET lub ASP.NET Core, pomniejszone o inicjatory telemetrii używane do wzbogacania telemetrii z HttpContext.

Możesz dostosować zestaw SDK usługi Application Insights dla usługi Worker Service, aby zmienić konfigurację domyślną. Użytkownicy zestawu SDK Application Insights ASP.NET Core mogą być zaznajomieni ze zmianą konfiguracji za pomocą wbudowanego wstrzykiwania zależności ASP.NET Core. Zestaw SDK usługi roboczej bazuje na podobnych zasadach. Wprowadź prawie wszystkie zmiany konfiguracji w ConfigureServices() sekcji, wywołując odpowiednie metody na IServiceCollection, zgodnie z opisem w następnej sekcji.

Uwaga / Notatka

Podczas korzystania z zestawu SDK usługi roboczej, zmiana konfiguracji poprzez modyfikację TelemetryConfiguration.Active nie jest obsługiwana i zmiany nie zostaną uwzględnione.

Kanały telemetrii

Kanały telemetryczne są integralną częścią zestawów SDK usługi Application Insights. Zarządzają buforowaniem i przesyłaniem danych telemetrycznych do usługi Application Insights. Wersje zestawów SDK platformy .NET i .NET Core mają dwa wbudowane kanały telemetryczne: InMemoryChannel i ServerTelemetryChannel. W tej sekcji opisano każdy kanał i pokazano, jak dostosować zachowanie kanału.

Uwaga / Notatka

Aby zapoznać się z często zadawanymi pytaniami, zobacz Często zadawane pytania dotyczące kanałów telemetrii

Co to są kanały telemetryczne?

Kanały telemetryczne są odpowiedzialne za buforowanie elementów telemetrii i wysyłanie ich do usługi Application Insights, gdzie są przechowywane na potrzeby wykonywania zapytań i analizy. Kanał telemetrii to dowolna klasa, która implementuje Microsoft.ApplicationInsights.ITelemetryChannel interfejs.

Metoda Send(ITelemetry item) kanału telemetrii jest wywoływana po wywołaniu wszystkich inicjatorów telemetrii i procesorów telemetrii. Dlatego wszystkie elementy porzucone przez procesor telemetrii nie docierają do kanału. Metoda Send() zwykle nie wysyła elementów do zaplecza natychmiast. Zazwyczaj buforuje je w pamięci i wysyła je w partiach w celu wydajnego przesyłania.

Unikaj wywoływania Flush() , chyba że ma kluczowe znaczenie dla natychmiastowego wysyłania buforowanych danych telemetrycznych. Używaj go tylko w scenariuszach, takich jak zamykanie aplikacji, obsługa wyjątków lub w przypadku używania krótkotrwałych procesów, takich jak zadania w tle lub narzędzia wiersza polecenia. W aplikacjach internetowych lub długotrwałych usługach zestaw SDK obsługuje automatyczne wysyłanie danych telemetrycznych. Wywołanie Flush() niepotrzebnie może powodować problemy z wydajnością.

Transmisja strumieniowa metryk na żywo ma również niestandardowy kanał obsługujący transmisję strumieniową na żywo danych telemetrycznych. Ten kanał jest niezależny od zwykłego kanału telemetrii, a ten dokument nie ma do niego zastosowania.

Wbudowane kanały telemetryczne

Zestawy SDK platformy .NET i platformy .NET Core usługi Application Insights są dostarczane z dwoma wbudowanymi kanałami:

• InMemoryChannel: Lekki kanał, który buforuje elementy w pamięci do momentu ich wysłania. Elementy są buforowane w pamięci i opróżniane co 30 sekund lub za każdym razem, gdy buforowane są 500 elementów. Ten kanał oferuje minimalne gwarancje niezawodności, ponieważ nie ponawia próby wysyłania danych telemetrycznych po awarii. Ten kanał nie przechowuje również elementów na dysku. W związku z tym wszelkie niesprawne elementy zostaną trwale utracone po zamknięciu aplikacji, niezależnie od tego, czy jest to łaskawy, czy nie. Ten kanał implementuje metodę Flush() , która może służyć do wymuszania synchronicznego opróżniania wszystkich elementów telemetrycznych w pamięci. Ten kanał jest odpowiedni dla krótko działających aplikacji, w których idealne jest synchroniczne opróżnienie.

  Ten kanał jest częścią większego pakietu NuGet Microsoft.ApplicationInsights i jest domyślnym kanałem używanym przez zestaw SDK, gdy nic innego nie jest skonfigurowane.

• ServerTelemetryChannel: Bardziej zaawansowany kanał, który ma zasady ponawiania prób i możliwość przechowywania danych na dysku lokalnym. Ten kanał ponawia próbę wysyłania danych telemetrycznych, jeśli wystąpią błędy przejściowe. Ten kanał używa również magazynu dysków lokalnych do przechowywania elementów na dysku podczas awarii sieci lub dużych woluminów telemetrycznych. Ze względu na te mechanizmy ponawiania prób i magazyn dysku lokalnego ten kanał jest uważany za bardziej niezawodny. Zalecamy to dla wszystkich scenariuszy produkcyjnych. Ten kanał jest domyślny dla aplikacji ASP.NET i ASP.NET Core skonfigurowanych zgodnie z oficjalną dokumentacją. Ten kanał jest zoptymalizowany pod kątem scenariuszy serwera z długotrwałymi procesami. Flush() Metoda zaimplementowana przez ten kanał nie jest synchroniczna.

  Ten kanał jest dostarczany jako pakiet NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel i jest uzyskiwany automatycznie podczas korzystania z pakietu NuGet Microsoft.ApplicationInsights.Web lub Microsoft.ApplicationInsights.AspNetCore NuGet.

Konfigurowanie kanału telemetrii

Kanał telemetrii można skonfigurować, ustawiając go na aktywną konfigurację telemetrii. W przypadku aplikacji ASP.NET konfiguracja obejmuje ustawienie wystąpienia kanału telemetrii na TelemetryConfiguration.Active lub przez zmodyfikowanie elementu ApplicationInsights.config. W przypadku aplikacji ASP.NET Core konfiguracja obejmuje dodanie kanału do kontenera wstrzykiwania zależności.

W poniższych sekcjach przedstawiono przykłady konfigurowania StorageFolder ustawienia kanału w różnych typach aplikacji. StorageFolder jest tylko jednym z konfigurowalnych ustawień. Pełną listę ustawień konfiguracji można znaleźć w sekcji Konfigurowanie ustawień w kanałach w dalszej części tego artykułu.

ASP.NET

Opcja 1. Konfiguracja w kodzie

Poniższy kod konfiguruje ServerTelemetryChannel wystąpienie z StorageFolder ustawioną lokalizacją niestandardową. Dodaj ten kod na początku aplikacji, zazwyczaj w metodzie Application_Start() w 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;
}

Opcja 2. Konfiguracja w ApplicationInsights.config

W poniższej sekcji z ApplicationInsights.config przedstawiono ServerTelemetryChannel kanał skonfigurowany z StorageFolder ustawieniem lokalizacji niestandardowej:

    <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

Zmodyfikuj metodę ConfigureServicesStartup.cs klasy, jak pokazano poniżej:

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

Ważne

Konfigurowanie kanału przy użyciu programu TelemetryConfiguration.Active nie jest obsługiwane w przypadku aplikacji ASP.NET Core.

Zastępowanie serverTelemetryChannel

Domyślnym kanałem telemetrii jest ServerTelemetryChannel. W poniższym przykładzie pokazano, jak go zastąpić.

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

Uwaga / Notatka

Jeśli chcesz opróżnić bufor, zobacz Opróżnianie danych. Na przykład może być konieczne opróżnienie buforu, jeśli używasz zestawu SDK w aplikacji, która zostanie zamknięta.

Usługa procesu roboczego

Domyślnym kanałem jest ServerTelemetryChannel. Można go zastąpić, jak pokazano w poniższym przykładzie:

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

Konfiguracja w kodzie dla aplikacji konsolowych

W przypadku aplikacji konsolowych kod jest taki sam zarówno dla platformy .NET, jak i platformy .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Szczegóły operacyjne serverTelemetryChannel

ServerTelemetryChannel przechowuje przychodzące elementy w buforze w pamięci. Elementy są serializowane, skompresowane i przechowywane w wystąpieniu Transmission co 30 sekund lub gdy buforowane są 500 elementów. Pojedyncze Transmission wystąpienie zawiera maksymalnie 500 elementów i reprezentuje partię danych telemetrycznych wysyłanych za pośrednictwem jednego wywołania HTTPS do usługi Application Insights.

Domyślnie można wysyłać równolegle maksymalnie 10 Transmission wystąpień. Jeśli dane telemetryczne docierają szybciej lub jeśli sieć lub zaplecze usługi Application Insights działa wolno, Transmission wystąpienia są przechowywane w pamięci. Domyślna pojemność tego buforu w pamięci Transmission wynosi 5 MB. Po przekroczeniu Transmission pojemności w pamięci wystąpienia są przechowywane na dysku lokalnym do limitu 50 MB.

Transmission wystąpienia są przechowywane na dysku lokalnym również wtedy, gdy występują problemy z siecią. Tylko te elementy, które są przechowywane na dysku lokalnym, przetrwają awarię aplikacji. Są one wysyłane za każdym razem, gdy aplikacja zostanie uruchomiona ponownie. Jeśli problemy z siecią będą się powtarzać, ServerTelemetryChannel użyj logiki wycofywania wykładniczego z zakresu od 10 sekund do 1 godziny przed ponowieniem próby wysłania danych telemetrycznych.

Konfigurowalne ustawienia w kanałach

Aby uzyskać pełną listę konfigurowalnych ustawień dla każdego kanału, zobacz:

• InMemoryChannel
• ServerTelemetryChannel

Poniżej przedstawiono najczęściej używane ustawienia dla programu ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: maksymalna ilość pamięci w bajtach używana przez kanał do buforowania transmisji w pamięci. Po osiągnięciu tej pojemności nowe elementy są przechowywane bezpośrednio na dysku lokalnym. Wartość domyślna to 5 MB. Ustawienie wyższej wartości prowadzi do mniejszego użycia dysku, ale pamiętaj, że elementy w pamięci zostaną utracone w przypadku awarii aplikacji.

• MaxTransmissionSenderCapacity: maksymalna liczba Transmission wystąpień wysyłanych do usługi Application Insights w tym samym czasie. Wartość domyślna to 10. To ustawienie można skonfigurować do większej liczby, która jest zalecana w przypadku wygenerowania ogromnej ilości danych telemetrycznych. Duża ilość zwykle występuje podczas testowania obciążenia lub gdy próbkowanie jest wyłączone.

• StorageFolder: folder używany przez kanał do przechowywania elementów na dysku zgodnie z potrzebami. W systemie Windows %LOCALAPPDATA% lub %TEMP% jest używana, jeśli nie określono jawnie żadnej innego ścieżki. W środowiskach innych niż Windows domyślnie są używane następujące lokalizacje (w kolejności): %TMPDIR%, /var/tmp/ lub /tmp/.

Którego kanału należy używać?

Zalecamy ServerTelemetryChannel korzystanie z większości scenariuszy produkcyjnych obejmujących długotrwałe aplikacje. Aby uzyskać więcej informacji na temat opróżniania danych telemetrycznych, przeczytaj o korzystaniu z usługi Flush().

Kiedy należy używać funkcji Flush()

Metoda Flush() natychmiast wysyła wszelkie buforowane dane telemetryczne. Jednak należy go używać tylko w określonych scenariuszach.

Użyj Flush(), gdy:

• Aplikacja ma zostać zamknięta i chcesz upewnić się, że dane telemetryczne są wysyłane przed zakończeniem pracy.
• Jesteś w procedurze obsługi wyjątków i musisz zagwarantować, że dane telemetryczne są dostarczane.
• Piszesz krótkotrwały proces, taki jak zadanie w tle lub narzędzie interfejsu wiersza polecenia, które szybko kończy działanie.

Unikaj używania Flush() w długotrwałych aplikacjach, takich jak usługi internetowe. Zestaw SDK automatycznie zarządza buforowaniem i przesyłaniem. Wywołanie Flush() niepotrzebnie może powodować problemy z wydajnością i nie gwarantuje, że wszystkie dane są wysyłane, zwłaszcza w przypadku korzystania z ServerTelemetryChannelmetody , która nie jest opróżniona synchronicznie.

Moduły telemetrii

Usługa Application Insights automatycznie zbiera dane telemetryczne dotyczące określonych obciążeń bez konieczności ręcznego śledzenia przez użytkownika.

Domyślnie są włączone następujące moduły automatycznego zbierania danych. Można je wyłączyć lub skonfigurować w celu zmiany ich domyślnego zachowania.

ASP.NET

Każdy moduł telemetrii zbiera określony typ danych i używa podstawowego interfejsu API do wysyłania danych. Moduły są instalowane przez różne pakiety NuGet, które również dodają wymagane wiersze do pliku .config.

Area	Description
Śledzenie żądań	Zbiera dane telemetryczne żądania (czas odpowiedzi, kod wyniku) dla przychodzących żądań internetowych. Moduł:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule NuGet:Microsoft.ApplicationInsights.Web
Śledzenie zależności	Zbiera dane telemetryczne dotyczące zależności wychodzących (wywołania HTTP, wywołania SQL). Aby pracować w usługach IIS, zainstaluj agenta usługi Application Insights. Możesz również napisać niestandardowe śledzenie zależności przy użyciu interfejsu API TrackDependency. Obsługuje autoinstrumentację za pomocą usługi App Service oraz monitorowanie maszyn wirtualnych i zestawów skalowania maszyn wirtualnych. Moduł:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule NuGet:Microsoft.ApplicationInsights.DependencyCollector
liczniki wydajności	Zbiera liczniki wydajności systemu Windows (procesor CPU, pamięć, obciążenie sieciowe z instalacji usług IIS). Określ liczniki (w tym niestandardowe). Aby uzyskać więcej informacji, zobacz Zbieranie liczników wydajności systemu. Moduł:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Liczniki zdarzeń	Zbiera zdarzenia platformy .NET. Zalecane w przypadku ASP.NET Core i międzyplatformowych liczników wydajności systemu Windows. Moduł:EventCounterCollectionModule (Zestaw SDK ≥ 2.8.0)
Metryki na żywo (QuickPulse)	Zbiera dane telemetryczne dla okienka Metryki na żywo. Moduł:QuickPulseTelemetryModule
Pulsy (App Service)	Wysyła pulsy i metryki niestandardowe dla środowiska usługi App Service. Moduł:AppServicesHeartbeatTelemetryModule
Pulsy (maszyny wirtualne i zestawy skalowania maszyn wirtualnych)	Wysyła pulsy i metryki niestandardowe dla środowiska maszyn wirtualnych platformy Azure. Moduł:AzureInstanceMetadataTelemetryModule
Telemetria diagnosyjna	Zgłasza błędy w kodzie instrumentacji usługi Application Insights (na przykład brakujące liczniki, ITelemetryInitializer wyjątki). Dane telemetryczne śledzenia są wyświetlane w wyszukiwaniu diagnostycznym. Moduł:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule NuGet:Microsoft.ApplicationInsights Nuta: Jeśli zainstalujesz tylko ten pakiet, plik ApplicationInsights.config nie zostanie automatycznie utworzony.
Tryb dewelopera (dołączony debuger)	Wymusza TelemetryChannel natychmiastowe wysyłanie elementów po dołączeniu debugera. Zmniejsza opóźnienie, ale zwiększa obciążenie procesora CPU/sieci. Moduł:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule NuGet:Application Insights Windows Server
Śledzenie wyjątków (sieć Web)	Śledzi nieobsługiwane wyjątki w aplikacjach internetowych. Zobacz Błędy i wyjątki. Moduł:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule NuGet:Microsoft.ApplicationInsights.Web
Śledzenie wyjątków (nieobserwowane/nieobsługiwane)	Śledzi nieobserwowane wyjątki zadań i nieobsługiwane wyjątki dla ról procesów roboczych, usług systemu Windows i aplikacji konsolowych. Moduły:  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule NuGet:Microsoft.ApplicationInsights.WindowsServer
Śledzenie źródła zdarzeń	Wysyła skonfigurowane zdarzenia EventSource do usługi Application Insights jako ślady. Moduł:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule NuGet:Microsoft.ApplicationInsights.EventSourceListener
Moduł zbierający ETW	Wysyła skonfigurowane zdarzenia dostawcy ETW do usługi Application Insights jako ślady. Moduł:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule NuGet:Microsoft.ApplicationInsights.EtwCollector
Podstawowy interfejs API (nie moduł)	Podstawowy interfejs API używany przez inne składniki telemetrii i niestandardowe dane telemetryczne. Moduł:Microsoft.ApplicationInsights package NuGet:Microsoft.ApplicationInsights Nuta: Jeśli zainstalujesz tylko ten pakiet, plik ApplicationInsights.config nie zostanie automatycznie utworzony.

ASP.NET Core

Area	Description
Śledzenie żądań	Wbudowane śledzenie żądań za pośrednictwem integracji usługi ASP.NET Core Application Insights. Module:Brak oddzielnej klasy modułu. NuGet:Microsoft.ApplicationInsights.AspNetCore
Śledzenie zależności	Za pośrednictwem modułu zbierającego zależności. NuGet:Microsoft.ApplicationInsights.DependencyCollector
liczniki wydajności	Tylko system Windows! Na wielu platformach użyj polecenia EventCounterCollectionModule (zobacz następny wiersz). NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Liczniki zdarzeń	Zbiera zdarzenia platformy .NET. Zalecane w przypadku ASP.NET Core i międzyplatformowych liczników wydajności systemu Windows. Moduł:EventCounterCollectionModule (Zestaw SDK 2.8.0 i nowsze) NuGet:Microsoft.ApplicationInsights.EventCounterCollector
Metryki na żywo (QuickPulse)	Metryki na żywo włączone w ASP.NET Podstawowej integracji usługi Application Insights. Module:Brak oddzielnej klasy modułu. NuGet:Microsoft.ApplicationInsights.AspNetCore
Moduł zbierający puls (App Service)	Wysyła pulsy (jako metryki niestandardowe) ze szczegółowymi informacjami o środowisku usługi App Service. Wbudowane za pośrednictwem podstawowego zestawu SDK, gdy są hostowane w usłudze App Service. Module:Brak oddzielnej klasy modułu. NuGet:Microsoft.ApplicationInsights.AspNetCore
Moduł zbierający pulsy (maszyny wirtualne i zestawy skalowania maszyn wirtualnych)	Wysyła pulsy (jako metryki niestandardowe) ze szczegółowymi informacjami na temat środowiska maszyny wirtualnej platformy Azure. Wbudowane za pośrednictwem podstawowego zestawu SDK hostowanego na maszynach wirtualnych platformy Azure i zestawach skalowania maszyn wirtualnych platformy Azure. Module:Brak oddzielnej klasy modułu. NuGet:Microsoft.ApplicationInsights.AspNetCore
Telemetria diagnosyjna	Zgłasza błędy w samym kodzie instrumentacji usługi Application Insights (na przykład nie można uzyskać dostępu do liczników wydajności, ITelemetryInitializer zgłasza wyjątek). Dane telemetryczne śledzenia są wyświetlane w wyszukiwaniu diagnostycznym. Moduł:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule NuGet:Microsoft.ApplicationInsights
Tryb dewelopera (dołączony debuger)	To samo zachowanie jest dostępne; klasa jest częścią pakietu systemu Windows Server. Moduł:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule NuGet:Microsoft.ApplicationInsights.WindowsServer
Śledzenie wyjątków (sieć Web)	Automatyczne śledzenie wyjątków w integracji usługi ASP.NET Core Application Insights Module:Brak oddzielnej klasy modułu. NuGet:Microsoft.ApplicationInsights.AspNetCore
Śledzenie wyjątków (nieobserwowane/nieobsługiwane)	Podobne zachowanie za pośrednictwem środowiska uruchomieniowego ASP.NET Core/integracji; nazwy klas są specyficzne dla systemu Windows Server. NuGet:Microsoft.ApplicationInsights.WindowsServer
Śledzenie źródła zdarzeń	Wysyła skonfigurowane zdarzenia EventSource do usługi Application Insights jako ślady. Moduł:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule NuGet:Microsoft.ApplicationInsights.EventSourceListener
Moduł zbierający ETW	Tylko system Windows (ETW). Wysyła skonfigurowane zdarzenia dostawcy ETW do usługi Application Insights jako ślady. Moduł:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule NuGet:Microsoft.ApplicationInsights.EtwCollector
Podstawowy interfejs API (nie moduł)	Podstawowy interfejs API używany przez inne składniki telemetrii i niestandardowe dane telemetryczne. Moduł:Microsoft.ApplicationInsights package NuGet:Microsoft.ApplicationInsights

Konfigurowanie modułów telemetrii

ASP.NET

TelemetryModules Użyj sekcji w ApplicationInsights.config, aby skonfigurować, dodać lub usunąć moduły. Następujące przykłady:

• Skonfiguruj DependencyTrackingTelemetryModule (włącz iniekcję nagłówka W3C).
• Skonfiguruj EventCounterCollectionModule (wyczyść wartości domyślne i dodaj pojedynczy licznik).
• Wyłącz zbieranie liczników wydajności przez usunięcie PerformanceCollectorModuleelementu .

<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>

Uwaga / Notatka

Dokładny zestaw modułów znajdujących się w pliku ApplicationInsights.config zależy od zainstalowanych pakietów ZESTAWU SDK.

ASP.NET Core

Opcja 1. Konfigurowanie modułów telemetrii przy użyciu modułu ConfigureTelemetryModule

Aby skonfigurować dowolny domyślny TelemetryModule, użyj metody rozszerzenia ConfigureTelemetryModule<T> na IServiceCollection, jak pokazano w poniższym przykładzie:

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

Opcja 2. Konfigurowanie modułów telemetrii przy użyciu usługi ApplicationInsightsServiceOptions

W zestawie SDK w wersji 2.12.2 lub nowszej można zmodyfikować kilka typowych ustawień, przekazując ApplicationInsightsServiceOptions do AddApplicationInsightsTelemetryelementu , jak w tym przykładzie:

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

Ta tabela zawiera pełną listę ApplicationInsightsServiceOptions ustawień:

Setting	Description	Default
Moduł zbierania liczników wydajności (EnablePerformanceCounterCollectionModule)	Włącz/wyłącz PerformanceCounterCollectionModule.	Prawda
WłączModułTelemetriiŚledzeniaŻądań	Włącz/wyłącz RequestTrackingTelemetryModule.	Prawda
WłączModułZbieraniaLicznikówZdarzeń	Włącz/wyłącz EventCounterCollectionModule.	Prawda
WłączModułTelemetriiŚledzeniaZależności	Włącz/wyłącz DependencyTrackingTelemetryModule.	Prawda
Włącz moduł telemetrii bicia serca usług aplikacji	Włącz/wyłącz AppServicesHeartbeatTelemetryModule.	Prawda
WłączAzureInstanceMetadataTelemetryModule	Włącz/wyłącz AzureInstanceMetadataTelemetryModule.	Prawda
Włącz Strumień Szybkiego Pulsu Metrycznego	Włącz/wyłącz funkcję LiveMetrics.	Prawda
Włącz adaptacyjne próbkowanie	Włączanie/wyłączanie próbkowania adaptacyjnego.	Prawda
Włącz bicie serca	Włącz/wyłącz funkcję pulsów. Okresowo (15-minutowa wartość domyślna) wysyła niestandardową metrykę o nazwie o nazwie HeartbeatState z informacjami o środowisku uruchomieniowym, takimi jak wersja platformy .NET i informacje o środowisku platformy Azure, jeśli ma to zastosowanie.	Prawda
DodajEkstraktorAutomatycznieZbieranychMetric	Włącz/wyłącz element AutoCollectedMetrics extractor. Ten procesor telemetrii wysyła wstępnie zagregowane metryki dotyczące żądań/zależności przed rozpoczęciem próbkowania.	Prawda
OpcjeZbieraniaŻądań.ŚledzenieWyjątków	Włącz/wyłącz raportowanie śledzenia nieobsługiwanych wyjątków przez moduł zbierania żądań.	Fałsz w netstandard2.0 (ponieważ wyjątki są śledzone za pomocą ApplicationInsightsLoggerProvider). W przeciwnym razie jest prawdą.
ModułDiagnostykiWyślijTelemetrię	Włącz/wyłącz DiagnosticsTelemetryModule. Wyłączenie powoduje ignorowanie następujących ustawień: EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModulei EnableAppServicesHeartbeatTelemetryModule.	Prawda

Aby uzyskać najbardziej aktualną listę, zobacz ustawienia konfigurowalne w ApplicationInsightsServiceOptions.

Zalecenie dotyczące konfiguracji zestawu Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 i nowszych

W zestawie Microsoft.ApplicationInsights.AspNetCore SDK w wersji 2.15.0 lub nowszej skonfiguruj każde dostępne ustawienie w programie w ApplicationInsightsServiceOptionstym ConnectionString. Użyj wystąpienia aplikacji IConfiguration . Ustawienia muszą znajdować się w sekcji ApplicationInsights, jak pokazano w poniższym przykładzie. Poniższa sekcja z appsettings.json konfiguruje parametry połączenia i wyłącza zbieranie próbkowania adaptacyjnego i licznika wydajności.

{
    "ApplicationInsights": {
    "ConnectionString": "<YOUR-CONNECTION-STRING>",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Jeśli builder.Services.AddApplicationInsightsTelemetry(aiOptions) w przypadku ASP.NET Core 6.0 lub services.AddApplicationInsightsTelemetry(aiOptions) ASP.NET Core 3.1 i starszych jest używany, zastępuje ustawienia z .Microsoft.Extensions.Configuration.IConfiguration

Usługa procesu roboczego

Opcja 1. Konfigurowanie modułów telemetrii przy użyciu modułu ConfigureTelemetryModule

Usługa Application Insights używa modułów telemetrycznych do automatycznego zbierania danych telemetrycznych dotyczących określonych obciążeń bez konieczności ręcznego śledzenia.

Następujące moduły autokolekcji są włączone domyślnie. Te moduły są odpowiedzialne za automatyczne zbieranie danych telemetrycznych. Można je wyłączyć lub skonfigurować w celu zmiany ich domyślnego zachowania.

• DependencyTrackingTelemetryModule
• PerformanceCollectorModule
• QuickPulseTelemetryModule
• AppServicesHeartbeatTelemetryModule (Obecnie występuje problem z tym modułem telemetrii. Aby uzyskać tymczasowe obejście, zobacz Problem z usługą GitHub 1689.
• AzureInstanceMetadataTelemetryModule

Aby skonfigurować dowolny domyślny moduł telemetrii, użyj metody rozszerzenia ConfigureTelemetryModule na IServiceCollection, jak pokazano w poniższym przykładzie:

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

Opcja 2. Konfigurowanie modułów telemetrii przy użyciu usługi ApplicationInsightsServiceOptions

Możesz zmodyfikować kilka typowych ustawień, przekazując ApplicationInsightsServiceOptions do AddApplicationInsightsTelemetryWorkerService, jak w tym przykładzie:

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

W ApplicationInsightsServiceOptions tym zestawie SDK znajduje się przestrzeń nazw Microsoft.ApplicationInsights.WorkerService , a nie Microsoft.ApplicationInsights.AspNetCore.Extensions w ASP.NET Core SDK.

W poniższej tabeli wymieniono często używane ustawienia w programie ApplicationInsightsServiceOptions.

Setting	Description	Default
Włącz Strumień Szybkiego Pulsu Metrycznego	Włącz/wyłącz funkcję metryk na żywo.	Prawda
Włącz adaptacyjne próbkowanie	Włączanie/wyłączanie próbkowania adaptacyjnego.	Prawda
Włącz bicie serca	Włącz/Wyłącz funkcję Pulsy, która okresowo (15-minutowa wartość domyślna) wysyła niestandardową metrykę o nazwie "HeartBeatState" z informacjami na temat środowiska uruchomieniowego, takiego jak wersja platformy .NET i środowisko platformy Azure, jeśli ma to zastosowanie.	Prawda
DodajEkstraktorAutomatycznieZbieranychMetric	Włącz/wyłącz wyodrębniacz AutoCollectedMetrics, który jest procesorem telemetrii wysyłającym wstępnie agregowane metryki dotyczące żądań/zależności, zanim próbkowanie się rozpocznie.	Prawda
ModułDiagnostykiWyślijTelemetrię	Włącz/wyłącz DiagnosticsTelemetryModule. Wyłączenie tego ustawienia powoduje zignorowanie następujących ustawień: EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModulei EnableAppServicesHeartbeatTelemetryModule.	Prawda

Aby zobaczyć najbardziej aktualną listę, zobacz konfigurowalne ustawienia w pliku ApplicationInsightsServiceOptions.

Wyłączanie telemetrii

ASP.NET

W pliku konfiguracji dla każdego modułu znajduje się węzeł. Aby wyłączyć moduł, usuń węzeł lub oznacz go jako komentarz.

ASP.NET Core

Jeśli chcesz wyłączyć telemetrię warunkowo i dynamicznie, możesz wywołać wystąpienie TelemetryConfiguration przy użyciu kontenera do iniekcji zależności ASP.NET Core w dowolnym miejscu w kodzie i ustawić na nim flagę 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();

Powyższy przykładowy kod uniemożliwia wysyłanie danych telemetrycznych do usługi Application Insights. Nie zapobiega to zbieraniu danych telemetrycznych przez żadne moduły automatycznej kolekcji. Jeśli chcesz usunąć konkretny moduł autocollection, zobacz moduły telemetrii.

Usługa procesu roboczego

Jeśli chcesz wyłączyć telemetrię warunkowo i dynamicznie, możesz wywołać wystąpienie TelemetryConfiguration przy użyciu kontenera do iniekcji zależności ASP.NET Core w dowolnym miejscu w kodzie i ustawić na nim flagę DisableTelemetry.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

Łańcuch połączenia

To ustawienie określa zasób usługi Application Insights, w którym są wyświetlane dane. Zazwyczaj należy utworzyć oddzielny zasób z oddzielnymi parametrami połączenia dla każdej aplikacji.

Zobacz Parametry połączenia w usłudze Application Insights , aby zapoznać się z przykładami kodu.

Jeśli chcesz ustawić parametry połączenia dynamicznie, na przykład w celu wysyłania wyników z aplikacji do różnych zasobów, możesz pominąć parametry połączenia z pliku konfiguracji i ustawić je w kodzie.

ASP.NET

Aby ustawić parametry połączenia dla wszystkich wystąpień programu , w tym standardowych modułów telemetrycznych TelemetryClient, wykonaj ten krok w metodzie inicjowania, takiej jak global.aspx.cs w usłudze 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);

Jeśli chcesz wysłać określony zestaw zdarzeń do innego zasobu, możesz ustawić klucz dla określonego klienta telemetrii:

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
    tc.TrackEvent("myEvent");
    // ...

Aby uzyskać nowe parametry połączenia, utwórz nowy zasób w portalu usługi Application Insights.

ASP.NET Core

W ASP.NET Core skonfiguruj parametry połączenia podczas Program.cs uruchamiania aplikacji przy użyciu TelemetryConfiguration kontenera wstrzykiwania zależności (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();

Jeśli chcesz wysłać określony zestaw zdarzeń do innego zasobu, możesz utworzyć nowe TelemetryClient wystąpienie i jawnie ustawić jego parametry połączenia:

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
tc.TrackEvent("myEvent");
// ...

Dostawca identyfikatora aplikacji

Uwaga / Notatka

W przypadku ASP.NET ten dostawca jest dostępny począwszy od zestawu SDK w wersji 2.6.0*.

Celem tego dostawcy jest wyszukanie identyfikatora aplikacji na podstawie parametrów połączenia. Identyfikator aplikacji jest uwzględniony i RequestTelemetryDependencyTelemetry służy do określania korelacji w portalu.

Ta funkcja jest dostępna przez ustawienie .TelemetryConfiguration.ApplicationIdProvider

Interfejs: IApplicationIdProvider

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

Udostępniamy dwie implementacje w zestawie MICROSOFT.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider i DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Ta otoka jest dla naszego interfejsu API profilu. Ogranicza żądania i buforuje wyniki. Ten dostawca jest automatycznie dołączany podczas instalacji microsoft.ApplicationInsights.DependencyCollector lub Microsoft.ApplicationInsights.Web.

Klasa uwidacznia opcjonalną właściwość o nazwie ProfileQueryEndpoint. Domyślnie jest ustawiona wartość https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Jeśli musisz skonfigurować serwer proxy, zalecamy użycie serwera proxy adresu podstawowego i upewnienie się, że ścieżka zawiera /api/profiles/{0}/appIdelement . Podczas działania programu {0} jest zastępowany łańcuchem połączenia dla każdego żądania.

ASP.NET

Przykładowa konfiguracja za pośrednictwem 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>

Przykładowa konfiguracja za pomocą kodu

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

ASP.NET Core

Uwaga / Notatka

W ASP.NET Core nie ma plikuApplicationInsights.config . Konfiguracja odbywa się za pomocą wstrzykiwania zależności (DI) w Program.cs lub Startup.cs.

Możesz zastąpić domyślnego dostawcę lub dostosować jego 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

Ten statyczny dostawca opiera się na skonfigurowanych parametrach połączenia/parach identyfikatorów aplikacji.

Ta klasa ma właściwość Defined, która jest parą ciągu połączenia i identyfikatora aplikacji Dictionary<string,string>.

Ta klasa ma opcjonalną właściwość Next, która może służyć do konfigurowania innego dostawcy do użycia, gdy wymagane są parametry połączenia, które nie istnieją w konfiguracji.

ASP.NET

Przykładowa konfiguracja za pośrednictwem 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>

Przykładowa konfiguracja za pomocą kodu

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

Node.js

W tym dziale

• Parametry połączenia
• Opcja konfiguracji zaawansowanej
• Automatyczne instrumentacja innych firm

Obiekt appInsights udostępnia wiele metod konfiguracji. Są one wymienione w poniższym fragmencie kodu z ich wartościami domyślnymi.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Aby w pełni skorelować zdarzenia w usłudze, należy ustawić parametr .setAutoDependencyCorrelation(true). Po ustawieniu tej opcji zestaw SDK może śledzić kontekst między asynchronicznymi wywołaniami zwrotnymi w środowisku Node.js.

Przejrzyj ich opisy we wbudowanych podpowiedziach typu IDE lub applicationinsights.ts, aby uzyskać szczegółowe informacje i opcjonalne dodatkowe argumenty.

Uwaga / Notatka

Domyślnie setAutoCollectConsole jest skonfigurowany do wykluczania wywołań do console.log i innych metod konsoli. Zbierane będą tylko wywołania obsługiwanych loggerów innych firm (na przykład winston i bunyan). To zachowanie można zmienić tak, aby uwzględniało wywołania metod console przy użyciu polecenia setAutoCollectConsole(true, true).

Łańcuch połączenia

To ustawienie określa zasób usługi Application Insights, w którym są wyświetlane dane. Zazwyczaj należy utworzyć oddzielny zasób z oddzielnymi parametrami połączenia dla każdej aplikacji.

Zobacz Parametry połączenia w usłudze Application Insights , aby zapoznać się z przykładami kodu.

Jeśli chcesz ustawić parametry połączenia dynamicznie, na przykład w celu wysyłania wyników z aplikacji do różnych zasobów, możesz pominąć parametry połączenia z pliku konfiguracji i ustawić je w kodzie.

Używanie wielu parametry połączenia

Możesz utworzyć wiele zasobów usługi Application Insights i wysłać różne dane do każdego przy użyciu odpowiednich parametry połączenia.

Przykład:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Zaawansowane opcje konfiguracji

Obiekt klienta zawiera config właściwość z wieloma opcjonalnymi ustawieniami dla zaawansowanych scenariuszy. Aby je ustawić, użyj:

client.config.PROPERTYNAME = VALUE;

Te właściwości są specyficzne dla klienta, więc można skonfigurować appInsights.defaultClient oddzielnie od klientów utworzonych za pomocą new appInsights.TelemetryClient()programu .

Majątek	Description
Parametry połączenia	Identyfikator zasobu usługi Application Insights.
endpointUrl	Punkt końcowy pozyskiwania do wysyłania ładunków telemetrii do.
quickPulseHost	Host strumienia metryk na żywo do wysyłania telemetrii na żywo.
proxyHttpUrl	Serwer proxy dla ruchu HTTP SDK. (Opcjonalnie. Wartość domyślna jest pobierana ze http_proxy zmiennej środowiskowej).
proxyHttpsUrl	Serwer proxy do obsługi ruchu HTTPS dla zestawu SDK. (Opcjonalnie. Wartość domyślna jest pobierana ze https_proxy zmiennej środowiskowej).
httpAgent	Agent HTTP do używania dla ruchu HTTP w SDK. (Opcjonalnie. Wartość domyślna jest niezdefiniowana).
httpsAgent	Https. Agent do użycia na potrzeby ruchu HTTPS zestawu SDK. (Opcjonalnie. Wartość domyślna jest niezdefiniowana).
maxBatchSize (maksymalny rozmiar wsadu)	Maksymalna liczba elementów telemetrii do uwzględnienia w pakiecie do końcowego punktu odbioru danych. (Wartość domyślna to 250.)
maxBatchIntervalMs	Maksymalny czas oczekiwania na ładunek, aby osiągnąć wartość maxBatchSize. (Wartość domyślna to 15000.)
wyłączAppInsights	Flaga wskazująca, czy transmisja danych telemetrycznych jest wyłączona. (Wartość domyślna to false.)
procent próbkowania	Procent śledzonych elementów telemetrii, które powinny być przesyłane. (Wartość domyślna to 100.)
correlationIdInterwałPonownejPróbyMs	Czas oczekiwania przed ponowną próbą pobrania identyfikatora korelacji między składnikami. (Wartość domyślna to 30000.)
nagłówkiKorelacyjneWykluczoneDomeny	Lista domen do wykluczenia z iniekcji nagłówków korelacyjnych między komponentami. (Ustawienie domyślne. Zobacz Config.ts.

Automatyczna instrumentacja firm zewnętrznych

Aby śledzić kontekst między wywołaniami asynchronicznymi, niektóre zmiany są wymagane w bibliotekach innych firm, takich jak MongoDB i Redis. Domyślnie usługa Application Insights używa diagnostic-channel-publishers funkcji monkey-patch niektórych z tych bibliotek. Tę funkcję można wyłączyć, ustawiając zmienną APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL środowiskową.

Uwaga / Notatka

Ustawiając tę zmienną środowiskową, zdarzenia mogą nie być poprawnie skojarzone z właściwą operacją.

Poszczególne poprawki małpy można wyłączyć, ustawiając APPLICATION_INSIGHTS_NO_PATCH_MODULES zmienną środowiskową na rozdzielaną przecinkami listę pakietów do wyłączenia. Na przykład użyj APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis, aby uniknąć stosowania poprawek do pakietów console i redis.

Obecnie instrumentowane są dziewięć pakietów: bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg i pg-pool. Aby uzyskać informacje o tym, które wersje tych pakietów są załatane, zobacz plik README diagnostic-channel-publishers.

Poprawki bunyan, winstoni console generują zdarzenia śledzenia usługi Application Insights na podstawie tego, czy setAutoCollectConsole jest włączona. Pozostałe elementy generują zdarzenia zależnościowe usługi Application Insights na podstawie tego, czy setAutoCollectDependencies jest aktywowane.

Dodawanie monitorowania po stronie klienta

.NET

W poprzednich sekcjach przedstawiono wskazówki dotyczące metod automatycznego i ręcznego konfigurowania monitorowania po stronie serwera. Aby dodać monitorowanie po stronie klienta, użyj zestawu SDK języka JavaScript po stronie klienta. Możesz monitorować transakcje po stronie klienta dowolnej strony internetowej, dodając skrypt ładowania JavaScript (Web) SDK przed tagiem zamykającym </head> kodu HTML strony.

Mimo że istnieje możliwość ręcznego dodania skryptu modułu ładującego zestawu SDK JavaScript (Web) do nagłówka każdej strony HTML, zalecamy dodanie skryptu modułu ładującego zestawu SDK JavaScript (Web) do strony głównej. Ta akcja powoduje wstrzyknięcie skryptu modułu ładującego zestawu JAVAScript (Web) SDK do wszystkich stron witryny.

ASP.NET

W przypadku aplikacji MVC opartej ASP.NET na szablonach z tego artykułu plik, który należy edytować, to _Layout.cshtml. Można go znaleźć w obszarze Widoki>udostępnione. Aby dodać monitorowanie po stronie klienta, otwórz plik _Layout.cshtml i postępuj zgodnie z instrukcjami dotyczącymi konfiguracji opartymi na skrypcie ładowania zestawu SDK JavaScript (Web) z artykułu na temat konfiguracji zestawu SDK JavaScript po stronie klienta.

ASP.NET Core

Jeśli aplikacja ma składniki po stronie klienta, wykonaj następne kroki, aby rozpocząć zbieranie danych telemetrycznych użycia przy użyciu iniekcji skryptu modułu ładującego zestawu SDK języka JavaScript (Web) według konfiguracji.

1. W pliku _ViewImports.cshtml dodaj iniekcję:

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. W pliku _Layout.cshtml wstaw HtmlHelper na końcu <head> sekcji, ale przed innym skryptem. Jeśli chcesz zgłosić dowolną niestandardową telemetrię języka JavaScript ze strony, wstrzykuj ją po tym fragmencie kodu:

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

Alternatywą dla używania FullScript jest dostępność ScriptBody począwszy od wersji 2.14 SDK Application Insights dla platformy ASP.NET Core. Użyj ScriptBody, jeśli musisz kontrolować znacznik <script>, aby ustawić Politykę Zabezpieczeń Treści.

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

Nazwy plików cshtml , do których odwołuje się wcześniej, pochodzą z domyślnego szablonu aplikacji MVC. Ostatecznie, jeśli chcesz prawidłowo włączyć monitorowanie po stronie klienta dla aplikacji, skrypt modułu ładującego zestawu SDK języka JavaScript (Web) musi zostać wyświetlony w <head> sekcji każdej strony aplikacji, którą chcesz monitorować. Dodaj skrypt modułu ładującego zestawu JAVAScript (Web) SDK do pliku _Layout.cshtml w szablonie aplikacji, aby umożliwić monitorowanie po stronie klienta.

Jeśli projekt nie zawiera pliku _Layout.cshtml, nadal możesz dodać monitorowanie po stronie klienta, dodając skrypt modułu ładującego zestawu JAVAScript (Web) SDK do równoważnego pliku, który kontroluje <head> wszystkie strony w aplikacji. Alternatywnie można dodać skrypt modułu ładującego zestawu JAVAScript (Web) SDK do wielu stron, ale nie zalecamy go.

Uwaga / Notatka

Iniekcja języka JavaScript zapewnia domyślne środowisko konfiguracji. Jeśli potrzebujesz konfiguracji poza ustawieniem parametrów połączenia, musisz usunąć autoinjection zgodnie z opisem i ręcznie dodać zestaw SDK języka JavaScript.

Node.js

Uwaga / Notatka

Dostępna jako publiczna wersja zapoznawcza. Dodatkowe warunki użytkowania dotyczące wersji zapoznawczych platformy Microsoft Azure

Automatyczną instrumentację internetową można włączyć dla serwera Node.js za pomocą skryptu ładującego SDK JavaScript (Web) przez konfigurację.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

lub przez ustawienie zmiennej środowiskowej APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true.

Instrumentacja sieci web jest włączona w odpowiedziach serwera węzła, gdy są spełnione wszystkie poniższe wymagania.

• Odpowiedź ma kod stanu 200.
• Metoda odpowiedzi to GET.
• Odpowiedź serwera zawiera Content-Type kod HTML.
• Odpowiedź serwera zawiera tagi <head> i </head> .
• Jeśli odpowiedź jest skompresowana, musi mieć tylko jeden typ Content-Encoding, a typ kodowania musi być jednym z gzip, br lub deflate.
• Odpowiedź nie zawiera bieżących ani zapasowych punktów końcowych web Instrumentation CDN. (bieżące i zapasowe punkty końcowe CDN tutaj)

Punkt końcowy usługi CDN instrumentacji sieci Web można zmienić, ustawiając zmienną środowiskową APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints". Parametry połączenia instrumentacji sieci Web można zmienić, ustawiając zmienną środowiskową APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Uwaga / Notatka

Instrumentacja sieci Web może spowolnić czas odpowiedzi serwera, zwłaszcza gdy rozmiar odpowiedzi jest duży lub odpowiedź jest kompresowana. W przypadku zastosowania niektórych warstw pośrednich może to spowodować, że instrumentacja webowa nie będzie działać i oryginalna odpowiedź zostanie zwrócona.

Podstawowy interfejs API dla zdarzeń niestandardowych i metryk

Wstaw kilka wierszy kodu w aplikacji, aby dowiedzieć się, co użytkownicy robią z nim, lub aby ułatwić diagnozowanie problemów. Dane telemetryczne można wysyłać z aplikacji urządzeń i komputerów stacjonarnych, klientów internetowych i serwerów internetowych. Użyj podstawowego interfejsu API telemetrii usługi Application Insights, aby wysyłać niestandardowe zdarzenia i metryki oraz własne wersje standardowej telemetrii. Ten interfejs API jest tym samym interfejsem API, którego używają standardowe moduły zbierające dane usługi Application Insights.

Podsumowanie interfejsu API

Podstawowy interfejs API jest jednolity na wszystkich platformach, oprócz kilku odmian, takich jak GetMetric (tylko platforma.NET).

Metoda	Używany do
TrackPageView	Strony, ekrany, okienka lub formularze.
TrackEvent	Akcje użytkownika i inne zdarzenia. Służy do śledzenia zachowania użytkownika lub monitorowania wydajności.
GetMetric	Metryki zerowe i wielowymiarowe, centralnie skonfigurowane agregacje, tylko język C#.
TrackMetric	Pomiary wydajności, takie jak długość kolejki, niezwiązane z określonymi zdarzeniami.
TrackException	Rejestrowanie wyjątków dla diagnostyki. Prześledź, gdzie występują w odniesieniu do innych zdarzeń i zbadaj ślady stosu.
TrackRequest	Rejestrowanie częstotliwości i czasu trwania żądań serwera na potrzeby analizy wydajności.
TrackTrace	Komunikaty dziennika diagnostycznego zasobów. Możesz również przechwytywać dzienniki innych firm.
TrackDependency	Rejestrowanie czasu trwania i częstotliwości wywołań do składników zewnętrznych, od których zależy aplikacja.

Do większości tych wywołań telemetrii można dołączyć właściwości i metryki.

Wymagania wstępne

Jeśli nie masz jeszcze odwołania do zestawu SDK usługi Application Insights:

1. Dodaj zestaw SDK usługi Application Insights do projektu.

2. W kodzie urządzenia lub serwera internetowego uwzględnij następujące elementy:

   .NET

   using Microsoft.ApplicationInsights;
   

   Node.js

   var applicationInsights = require("applicationinsights");
   

Uzyskaj instancję TelemetryClient

Pobierz wystąpienie klasy TelemetryClient:

Uwaga / Notatka

Jeśli używasz usługi Azure Functions w wersji 2 lub nowszej lub usługi Azure WebJobs w wersji 3 lub nowszej, zobacz Monitorowanie usługi Azure Functions.

.NET

Uwaga / Notatka

W przypadku aplikacji ASP.NET Core i Innych niż HTTP/Worker dla aplikacji .NET/.NET Core pobierz wystąpienie TelemetryClient z kontenera wstrzykiwania zależności, zgodnie z opisem w odpowiedniej dokumentacji.

private TelemetryClient telemetry = new TelemetryClient();

Jeśli zostanie wyświetlony komunikat informujący o tym, że ta metoda jest przestarzała, zobacz microsoft/ApplicationInsights-dotnet#1152 , aby uzyskać więcej informacji.

Przychodzące żądania HTTP są automatycznie przechwytywane. Możesz chcieć utworzyć więcej wystąpień TelemetryClient dla innych modułów swojej aplikacji. Na przykład może istnieć jedno TelemetryClient wystąpienie w klasie środowiska pośredniczącego do raportowania zdarzeń logiki biznesowej. Możesz ustawić właściwości, takie jak UserId i DeviceId , aby zidentyfikować maszynę. Te informacje są dołączone do wszystkich zdarzeń wysyłanych przez wystąpienie.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Node.js

var telemetry = applicationInsights.defaultClient;

Możesz użyć new applicationInsights.TelemetryClient(instrumentationKey?), aby utworzyć nowe wystąpienie. Zalecamy to podejście tylko w przypadku scenariuszy, które wymagają izolowanej konfiguracji od pojedynczego elementu defaultClient.

Uwaga / Notatka

TelemetryClient jest bezpieczny wątkowo.

TrackEvent

W usłudze Application Insights zdarzenie niestandardowe to punkt danych, który można wyświetlić w Eksploratorze metryk jako zagregowaną liczbę i w wyszukiwaniu diagnostycznym jako pojedyncze wystąpienia. (Nie jest to związane z MVC ani inną strukturą "events".

Wstaw wywołania TrackEvent w kodzie, aby zliczyć różne zdarzenia. Możesz na przykład śledzić, jak często użytkownicy wybierają określoną funkcję. Możesz też chcieć wiedzieć, jak często osiągają określone cele lub popełniają określone błędy.

Na przykład w aplikacji do gry wyślij zdarzenie za każdym razem, gdy użytkownik wygra grę:

.NET

telemetry.TrackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

Zdarzenia niestandardowe w usłudze Log Analytics

Dane telemetryczne są dostępne w customEvents tabeli na karcie Dzienniki usługi Application Insights lub w interfejsie użytkownika. Zdarzenia mogą pochodzić z trackEvent(..)lub wtyczki Autocollection Click Analytics.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań do trackEvent() metody, proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną liczbę zdarzeń niestandardowych, użyj kodu takiego jak customEvents | summarize sum(itemCount).

Uwaga / Notatka

itemCount ma minimalną wartość jedną; sam rekord reprezentuje wpis.

GetMetric

Aby dowiedzieć się, jak skutecznie używać GetMetric() wywołania do przechwytywania lokalnie wstępnie zebranych metryk dla aplikacji .NET i .NET Core, zobacz Zbieranie niestandardowych metryk na platformach .NET i .NET Core.

TrackMetric

Uwaga / Notatka

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric nie jest preferowaną metodą wysyłania metryk. Metryki powinny być zawsze wstępnie agregowane w okresie przed wysłaniem. Użyj jednego z GetMetric(..) przeciążeń, aby uzyskać obiekt metryki na potrzeby uzyskiwania dostępu do funkcji wstępnej agregacji zestawu SDK.

Jeśli implementujesz własną logikę preaggregacji, możesz użyć TrackMetric() metody do wysyłania wynikowych agregacji. Jeśli aplikacja wymaga wysyłania oddzielnego elementu telemetrii przy każdej okazji bez agregacji w czasie, prawdopodobnie istnieje przypadek użycia telemetrii zdarzeń. Zobacz: TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Usługa Application Insights może wyświetlać metryki, które nie są dołączone do określonych zdarzeń. Można na przykład monitorować długość kolejki w regularnych odstępach czasu. W przypadku metryk poszczególne miary są mniej interesujące niż różnice i trendy, dlatego wykresy statystyczne są przydatne.

Aby wysyłać metryki do usługi Application Insights, możesz użyć interfejsu TrackMetric(..) API. Istnieją dwa sposoby na przesłanie metryki:

• Pojedyncza wartość. Za każdym razem, gdy wykonujesz pomiar w aplikacji, wysyłasz odpowiednią wartość do usługi Application Insights.

  Załóżmy na przykład, że masz metrykę opisjącą liczbę elementów w kontenerze. W określonym przedziale czasu najpierw umieścisz trzy elementy w kontenerze, a następnie usuniesz dwa elementy. Zatem należy zadzwonić TrackMetric dwa razy. Najpierw należy przekazać wartość 3 , a następnie przekazać wartość -2. Usługa Application Insights przechowuje obie wartości.

• Agregacja. Podczas pracy z metrykami każda pojedyncza miara jest rzadko interesująca. Zamiast tego ważne jest podsumowanie tego, co wydarzyło się w określonym okresie. Takie podsumowanie jest nazywane agregacją.

  W poprzednim przykładzie suma zagregowanej metryki dla tego okresu to 1 , a liczba wartości metryki to 2. W przypadku korzystania z podejścia agregacji należy wywołać TrackMetric tylko raz w danym okresie i wysłać zagregowane wartości. Zalecamy takie podejście, ponieważ może znacznie zmniejszyć koszty i obciążenie związane z wydajnością, wysyłając mniej punktów danych do usługi Application Insights, jednocześnie zbierając wszystkie istotne informacje.

Przykłady pojedynczej wartości

Aby wysłać pojedynczą wartość metryki:

.NET

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Metryki zdefiniowane przez użytkownika w usłudze Log Analytics

Dane telemetryczne są dostępne w customMetrics tabeli w usłudze Application Insights Analytics. Każdy wiersz reprezentuje wywołanie metody trackMetric(..) w aplikacji.

• valueSum: suma pomiarów. Aby uzyskać średnią wartość, podziel przez valueCount.
• valueCount: liczba pomiarów, które zostały zebrane w tym wywołaniu trackMetric(..).

Uwaga / Notatka

valueCount ma minimalną wartość jedną; sam rekord reprezentuje wpis.

Widoki stron

W aplikacji urządzenia lub strony internetowej dane telemetryczne widoku strony są wysyłane domyślnie po załadowaniu każdego ekranu lub strony. Można jednak zmienić wartość domyślną, aby śledzić wyświetlenia stron w więcej lub innym czasie. Na przykład w aplikacji, która wyświetla karty lub okienka, możesz śledzić stronę za każdym razem, gdy użytkownik otworzy nowe okienko.

Dane użytkownika i sesji są wysyłane jako właściwości wraz z widokami stron, więc wykresy użytkownika i sesji nabierają znaczenia, gdy pojawiają się dane telemetryczne dotyczące wyświetleń strony.

Niestandardowe widoki stron

.NET

telemetry.TrackPageView("GameReviewPage");

Node.js

Nie dotyczy.

Telemetria stron w usłudze Log Analytics

W usłudze Log Analytics dwie tabele pokazują dane z operacji przeglądarki:

• pageViews: zawiera dane dotyczące adresu URL i tytułu strony.
• browserTimings: zawiera dane dotyczące wydajności klienta, takie jak czas potrzebny na przetwarzanie danych przychodzących.

Aby dowiedzieć się, jak długo trwa przetwarzanie różnych stron w przeglądarce:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Aby odkryć popularność różnych przeglądarek:

pageViews
| summarize count() by client_Browser

Aby skojarzyć widoki stron z wywołaniami AJAX, złącz je z zależnościami.

pageViews
| join (dependencies) on operation_Id

TrackRequest

Zestaw SDK serwera używa TrackRequest do rejestrowania żądań HTTP.

Możesz również wywołać je samodzielnie, jeśli chcesz symulować żądania w kontekście, w którym nie masz uruchomionego modułu usługi internetowej.

Zalecanym sposobem wysyłania danych telemetrycznych żądania jest sytuacja, w której żądanie pełni rolę kontekstu operacji.

Kontekst operacji

Elementy telemetryczne można skorelować razem, kojarząc je z kontekstem operacji. Standardowy moduł śledzenia żądań wykonuje go w przypadku wyjątków i innych zdarzeń wysyłanych podczas przetwarzania żądania HTTP. W obszarze Wyszukiwanie i analiza można łatwo znaleźć wszelkie zdarzenia skojarzone z żądaniem przy użyciu jego identyfikatora operacji.

Podczas ręcznego śledzenia danych telemetrycznych najprostszym sposobem zapewnienia korelacji telemetrii jest użycie tego wzorca:

.NET

// 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.

Aby uzyskać więcej informacji na temat korelacji, zobacz Korelacja telemetrii w usłudze Application Insights.

Node.js

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Wraz z ustawieniem kontekstu operacji, StartOperation tworzy element telemetrii określonego przez Ciebie typu. Wysyła element telemetrii podczas usuwania operacji lub w przypadku jawnego wywołania metody StopOperation. Jeśli używasz RequestTelemetry jako typu telemetrii, jego czas trwania jest ustawiony na interwał czasowy między rozpoczęciem a zatrzymaniem.

Elementy telemetryczne zgłaszane w zakresie operacji stają się elementami podrzędnym takiej operacji. Konteksty operacji można zagnieżdżać.

W obszarze Wyszukiwanie kontekst operacji służy do tworzenia listy Powiązane elementy .

Aby uzyskać więcej informacji na temat śledzenia operacji niestandardowych, zobacz Śledzenie operacji niestandardowych za pomocą zestawu SDK platformy .NET usługi Application Insights.

Żądania w usłudze Log Analytics

W usłudze Application Insights Analytics żądania są wyświetlane w requests tabeli.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań do trackRequest() metody, proces próbkowania przesłał tylko jedno z nich. Aby uzyskać prawidłową liczbę żądań i średni czas trwania segmentowany według nazw żądań, użyj kodu takiego jak:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Wysyłanie wyjątków do usługi Application Insights:

• Aby je zliczyć, aby wskazać częstotliwość problemu.
• Aby zbadać poszczególne wystąpienia.

Raporty obejmują ślady stosu.

.NET

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

SDK automatycznie przechwytują wiele wyjątków, więc nie zawsze trzeba wywoływać TrackException wprost.

Wyjątki w usłudze Log Analytics

W usłudze Application Insights Analytics wyjątki są wyświetlane w exceptions tabeli.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań do trackException() metody, proces próbkowania przesłał tylko jedno z nich. Aby uzyskać prawidłową liczbę wyjątków segmentowanych według typu wyjątku, użyj kodu takiego jak:

exceptions
| summarize sum(itemCount) by type

Większość ważnych informacji o stosie jest już wyodrębniona do osobnych zmiennych, ale można rozłożyć strukturę details, aby uzyskać więcej informacji. Ponieważ ta struktura jest dynamiczna, należy przekształcić wynik na oczekiwany typ. Przykład:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Aby skojarzyć wyjątki z powiązanymi żądaniami, użyj operacji łączenia:

exceptions
| join (requests) on operation_Id

TrackTrace

Użyj TrackTrace do diagnozowania problemów przez wysłanie "śladu nawigacyjnego" do usługi Application Insights. Fragmenty danych diagnostycznych można wysyłać i sprawdzać w wyszukiwaniu diagnostycznym.

.NET

W .NET adapterach logów użyj tego interfejsu API, aby wysyłać dzienniki innych firm do portalu.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Rejestrowanie zdarzenia diagnostycznego, takiego jak wprowadzanie lub opuszczanie metody.

Parameter	Description
message	Dane diagnostyczne. Może być znacznie dłuższa niż nazwa.
properties	Mapa ciągu na ciąg. Więcej danych służy do filtrowania wyjątków w portalu. Wartości domyślne są puste.
severityLevel	Obsługiwane wartości: SeverityLevel.ts.

Możesz wyszukiwać zawartość wiadomości, ale w przeciwieństwie do wartości właściwości, nie można jej filtrować.

Limit rozmiaru elementu message jest znacznie wyższy niż limit rozmiaru właściwości. Zaletą TrackTrace jest to, że można umieścić stosunkowo długie dane w komunikacie. Możesz na przykład zakodować tam dane POST.

Możesz również dodać stopień surowości do wiadomości. Podobnie jak inne dane telemetryczne, możesz dodać wartości właściwości, aby ułatwić filtrowanie lub wyszukiwanie różnych zestawów śladów. Przykład:

.NET

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Node.js

Nie dotyczy.

W obszarze Wyszukiwanie można łatwo odfiltrować wszystkie komunikaty określonego poziomu ważności powiązanego z określoną bazą danych.

Ślady w usłudze Log Analytics

W usłudze Application Insights Analytics wywołania pojawiają się w tabeli TrackTrace.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań do trackTrace() metody, proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną liczbę wywołań śledzenia, użyj kodu takiego jak traces | summarize sum(itemCount).

TrackDependency

Użyj wywołania , TrackDependency aby śledzić czasy odpowiedzi i wskaźniki powodzenia wywołań do zewnętrznego fragmentu kodu. Wyniki są wyświetlane na wykresach zależności w portalu. Poniższy fragment kodu musi zostać dodany wszędzie tam, gdzie jest wykonywane wywołanie zależności.

Uwaga / Notatka

W przypadku platformy .NET i .NET Core można również użyć metody rozszerzenia TelemetryClient.StartOperation, która wypełnia właściwości DependencyTelemetry potrzebne do korelacji oraz ustawia inne właściwości, takie jak czas rozpoczęcia i czas trwania. Dzięki temu nie trzeba tworzyć niestandardowego czasomierza jak w poniższych przykładach. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą śledzenia zależności wychodzących w temacie Śledzenie operacji niestandardowych za pomocą .NET SDK usługi Application Insights.

.NET

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

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Należy pamiętać, że zestawy SDK serwera zawierają moduł zależności , który odnajduje i śledzi niektóre wywołania zależności automatycznie, na przykład do baz danych i interfejsów API REST. Aby moduł działał, musisz zainstalować agenta na serwerze.

To wywołanie jest używane, jeśli chcesz śledzić wywołania, których automatyczne śledzenie nie przechwyci.

Aby wyłączyć standardowy moduł śledzenia zależności w języku C#, edytuj ApplicationInsights.config i usuń odwołanie do DependencyCollector.DependencyTrackingTelemetryModule.

Zależności w usłudze Log Analytics

W usłudze Application Insights Analytics wywołania trackDependency są wyświetlane w dependencies tabeli.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań do trackDependency() metody, proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną liczbę zależności segmentowanych według składnika docelowego, użyj kodu takiego jak:

dependencies
| summarize sum(itemCount) by target

Aby skojarzyć zależności z powiązanymi żądaniami, użyj sprzężenia:

dependencies
| join (requests) on operation_Id

Opróżnianie danych

Zwykle zestaw SDK wysyła dane w stałych odstępach czasu, zazwyczaj 30 sekund lub za każdym razem, gdy bufor jest pełny, czyli zazwyczaj 500 elementów. W niektórych przypadkach może być konieczne opróżnienie buforu. Przykładem jest użycie zestawu SDK w aplikacji, która zostanie zamknięta.

.NET

W przypadku korzystania z Flush() zalecamy ten wzorzec:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

W przypadku korzystania z FlushAsync(), zalecamy następujący wzorzec:

await telemetryClient.FlushAsync()
// No need to sleep

Zalecamy zawsze opróżnianie w ramach zamknięcia aplikacji, aby zagwarantować, że dane telemetryczne nie zostaną utracone.

Uwaga / Notatka

Przejrzyj konfigurację Autoflush: włączenie Autoflush w pliku web.config może prowadzić do obniżenia wydajności w aplikacjach platformy .NET instrumentowanych za pomocą usługi Application Insights. Po włączeniu funkcji autoprzepłukiwania System.Diagnostics.Trace.Trace* każde wywołanie metod powoduje wysłanie poszczególnych elementów telemetrii jako oddzielnych żądań sieciowych do usługi pozyskiwania danych. To może spowodować wyczerpanie zasobów sieci i pamięci masowej na serwerach internetowych. Aby zwiększyć wydajność, zaleca się wyłączenie autoprzepłukiwania oraz korzystanie z ServerTelemetryChannel, co zapewnia bardziej efektywną transmisję danych telemetrycznych.

Funkcja jest asynchroniczna dla kanału telemetrii serwera.

Node.js

telemetry.flush();

Uwierzytelnieni użytkownicy

W aplikacji internetowej użytkownicy są domyślnie identyfikowani przez pliki cookie . Użytkownik może być liowany więcej niż raz, jeśli uzyskuje dostęp do aplikacji z innej maszyny lub przeglądarki lub jeśli usunie pliki cookie.

Jeśli użytkownicy logowali się do aplikacji, możesz uzyskać dokładniejszą liczbę, ustawiając uwierzytelniony identyfikator użytkownika w kodzie przeglądarki. Nie jest konieczne użycie rzeczywistej nazwy logowania użytkownika. Musi być tylko identyfikatorem unikatowym dla tego użytkownika. Nie może zawierać spacji ani znaków ,;=|.

Identyfikator użytkownika jest również ustawiany w pliku cookie sesji i wysyłany do serwera. Jeśli zestaw SDK serwera jest zainstalowany, uwierzytelniony identyfikator użytkownika jest wysyłany jako część właściwości kontekstu zarówno telemetrii klienta, jak i serwera. Następnie możesz filtrować i wyszukiwać.

Jeśli aplikacja grupuje użytkowników na kontach, możesz również przekazać identyfikator konta. Obowiązują te same ograniczenia znaków.

W Eksploratorze metryk można utworzyć wykres zliczający użytkowników, uwierzytelnione i konta użytkowników.

Możesz również wyszukać punkty danych klienta powiązane z określonymi nazwami użytkowników i kontami.

Uwaga / Notatka

Właściwość EnableAuthenticationTrackingJavaScript w klasie ApplicationInsightsServiceOptions w zestawie SDK platformy .NET Core upraszcza konfigurację języka JavaScript wymaganą do wstrzykiwania nazwy użytkownika jako identyfikatora uwierzytelniania dla każdego śledzenia wysyłanego przez zestaw SDK języka JavaScript usługi Application Insights.

Gdy ta właściwość jest ustawiona na true, wyświetlana jest nazwa użytkownika z ASP.NET Core oraz telemetria po stronie klienta. Z tego powodu dodawanie appInsights.setAuthenticatedUserContext ręcznie nie jest już wymagane, ponieważ jest już wstrzykiwane przez zestaw SDK dla platformy ASP.NET Core. Identyfikator Auth jest również wysyłany do serwera, gdzie zestaw SDK na platformie .NET Core identyfikuje go i używa dla dowolnej telemetrii po stronie serwera, opisanej w dokumentacji interfejsu API języka JavaScript.

W przypadku aplikacji JavaScript, które nie działają w taki sam sposób jak ASP.NET Core MVC, takich jak aplikacje internetowe SPA, nadal trzeba dodać appInsights.setAuthenticatedUserContext ręcznie.

Filtrowanie, wyszukiwanie i segmentowanie danych przy użyciu właściwości

Właściwości i miary można dołączać do zdarzeń, metryk, widoków stron, wyjątków i innych danych telemetrycznych.

Właściwości to wartości ciągów, których można użyć do filtrowania danych telemetrycznych w raportach użycia. Jeśli na przykład aplikacja udostępnia kilka gier, możesz dołączyć nazwę gry do każdego wydarzenia, aby zobaczyć, które gry są bardziej popularne.

Istnieje ograniczenie długości ciągu do 8,192 znaków. Jeśli chcesz wysłać duże fragmenty danych, użyj parametru komunikatu .TrackTrace

Metryki to wartości liczbowe, które można przedstawiać graficznie. Na przykład możesz sprawdzić, czy występuje stopniowy wzrost wyników osiąganych przez graczy. Wykresy można podzielić na segmenty według właściwości, które są wysyłane ze zdarzeniem, aby można było uzyskać oddzielne lub skumulowane grafy dla różnych gier.

Wartości metryki powinny być większe lub równe 0, aby wyświetlić poprawnie.

Istnieją pewne ograniczenia dotyczące liczby właściwości, wartości właściwości i metryk , których można użyć.

.NET

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

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Ważne

Upewnij się, że nie rejestrujesz informacji umożliwiających identyfikację w ustawieniach.

Alternatywny sposób ustawiania właściwości i metryk

Jeśli jest to wygodniejsze, możesz zebrać parametry zdarzenia w osobnym obiekcie:

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

Ostrzeżenie

Nie używaj tego samego wystąpienia elementu telemetrii (event w tym przykładzie) do powtarzającego się wywoływania Track*(). Takie rozwiązanie może spowodować wysłanie danych telemetrycznych z nieprawidłową konfiguracją.

Niestandardowe pomiary i właściwości w usłudze Log Analytics

W usłudze Log Analytics metryki niestandardowe oraz właściwości są wyświetlane w atrybutach customMeasurements oraz customDimensions każdego rekordu telemetrii.

Jeśli na przykład dodasz właściwość o nazwie "game" do danych telemetrycznych żądania, to zapytanie zlicza wystąpienia różnych wartości "game" i wyświetla średnią metryki niestandardowej "score".

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Zwróć uwagę, że:

• Podczas wyodrębniania wartości z JSON-a customDimensions lub customMeasurements ma ona typ dynamiczny, więc należy ją rzutować na tostring lub todouble.
• Aby wziąć pod uwagę możliwość próbkowania, użyj sum(itemCount), a nie count().

Zdarzenia czasowe

Czasami chcesz utworzyć wykres czasu potrzebnego do wykonania akcji. Na przykład możesz chcieć wiedzieć, jak długo użytkownicy będą rozważać wybory w grze. Aby uzyskać te informacje, użyj parametru pomiaru.

.NET

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

Node.js

Domyślne właściwości niestandardowej telemetrii

Jeśli chcesz ustawić domyślne wartości właściwości dla niektórych zapisywanych zdarzeń niestandardowych, ustaw je w wystąpieniu TelemetryClient . Do każdego elementu telemetrii, który jest wysyłany z tego klienta, są one dołączone.

.NET

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

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Poszczególne wywołania telemetryczne mogą zastąpić wartości domyślne w słownikach właściwości.

Aby dodać właściwości do wszystkich danych telemetrycznych, w tym danych ze standardowych modułów kolekcji, zaimplementuj element ITelemetryInitializer.

Wyłączanie telemetrii

Aby dynamicznie zatrzymywać i uruchamiać zbieranie i przesyłanie danych telemetrycznych:

.NET

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Node.js

telemetry.config.disableAppInsights = true;

Aby wyłączyć wybrane standardowe moduły zbierające, takie jak liczniki wydajności, żądania HTTP lub zależności, podczas inicjalizacji połącz metody konfiguracyjne z kodem inicjalizacji SDK.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Aby wyłączyć te kolektory po zainicjowaniu, użyj obiektu Configuration: applicationInsights.Configuration.setAutoCollectRequests(false).

Tryb programisty

Podczas debugowania przydatne jest szybsze przesyłanie telemetrii przez kanał telemetrii, dzięki czemu wyniki będą widoczne natychmiast. Otrzymujesz również inne komunikaty, które ułatwiają śledzenie wszelkich problemów z telemetrią. Wyłącz ją w środowisku produkcyjnym, ponieważ może spowolnić działanie aplikacji.

.NET

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Node.js

W przypadku Node.js można włączyć tryb dewelopera, włączając rejestrowanie wewnętrzne za pośrednictwem setInternalLogging i ustawiając maxBatchSize na 0, co powoduje wysyłanie danych telemetrycznych natychmiast po ich zebraniu.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Ustaw klucz instrumentacji dla wybranej niestandardowej telemetrii

.NET

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Node.js

Dynamiczny ciąg połączenia

Aby uniknąć mieszania danych telemetrycznych ze środowisk programistycznych, testowych i produkcyjnych, możesz utworzyć oddzielne zasoby usługi Application Insights i zmienić ich klucze w zależności od środowiska.

Zamiast uzyskiwać klucz instrumentacji z pliku konfiguracji, możesz ustawić go w kodzie. Ustaw klucz w metodzie inicjowania, na przykład global.aspx.cs w usłudze ASP.NET:

.NET

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

Node.js

Nie dotyczy.

TelemetriaContext

TelemetryClient ma właściwość Context, która zawiera wartości, które są wysyłane wraz ze wszystkimi danymi telemetrycznymi. Są one zwykle ustawiane przez standardowe moduły telemetryczne, ale można je również ustawić samodzielnie. Przykład:

telemetry.Context.Operation.Name = "MyOperationName";

Jeśli ustawisz dowolną z tych wartości samodzielnie, rozważ usunięcie odpowiedniego wiersza z ApplicationInsights.config , aby wartości i wartości standardowe nie były mylone.

• Składnik: aplikacja i jej wersja.
• Urządzenie: dane dotyczące urządzenia, na którym działa aplikacja. W aplikacjach internetowych jest to serwer lub urządzenie klienckie, z którego są wysyłane dane telemetryczne.
• InstrumentationKey: zasób usługi Application Insights na platformie Azure, na którym jest wyświetlana telemetria. Zazwyczaj jest to pobierane z ApplicationInsights.config.
• Lokalizacja: lokalizacja geograficzna urządzenia.
• Operacja: Bieżące żądanie HTTP w aplikacjach internetowych. W innych typach aplikacji można ustawić tę wartość na grupowanie zdarzeń.
  • ID: wygenerowana wartość, która powiązuje różne zdarzenia, umożliwiając znalezienie powiązanych elementów podczas przeszukiwania diagnostycznego dowolnego zdarzenia.
  • Nazwa: identyfikator, zazwyczaj adres URL żądania HTTP.
  • Syntetyczne źródło: jeśli nie ma wartości null lub jest pusty, ciąg wskazujący, że źródło żądania zostało zidentyfikowane jako robot lub test internetowy. Domyślnie jest on wykluczony z obliczeń w Eksploratorze metryk.
• Sesja: sesja użytkownika. Identyfikator jest ustawiony na wygenerowaną wartość, która jest zmieniana, gdy użytkownik nie był aktywny przez jakiś czas.
• Użytkownik: informacje o użytkowniku.

Limits

Istnieją pewne limity liczby metryk i zdarzeń na aplikację, czyli na ciąg połączenia. Ograniczenia zależą od wybranego planu cenowego.

Resource	Limit domyślny	Maksymalny limit	Notatki
Łączna ilość danych na dzień	100 GB	Skontaktuj się z pomocą techniczną.	Możesz ustawić limit w celu zmniejszenia ilości danych. Jeśli potrzebujesz więcej danych, możesz zwiększyć limit w portalu do 1000 GB. W przypadku pojemności większych niż 1000 GB wyślij wiadomość e-mail na AIDataCap@microsoft.comadres .
Throttling	32 000 zdarzeń na sekundę	Skontaktuj się z pomocą techniczną.	Limit jest mierzony w ciągu minuty.
Dzienniki przechowywania danych	Od 30 do 730 dni	730 dni	Ten zasób jest przeznaczony dla dzienników.
Metryki przechowywania danych	90 dni	90 dni	Ten zasób jest przeznaczony dla Eksploratora metryk.
Utrzymanie szczegółowych wyników wieloetapowego testu dostępności	90 dni	90 dni	Ten zasób zapewnia szczegółowe wyniki każdego kroku.
Maksymalny rozmiar elementu telemetrii	64 KB	64 KB
Maksymalna liczba elementów telemetrii na partię	64,000	64,000
Długość nazwy właściwości i metryki	150	150	Zobacz schematy typów.
Długość ciągu wartości właściwości	8,192	8,192	Zobacz schematy typów.
Długość komunikatu śladu i wyjątku	32,768	32,768	Zobacz schematy typów.
Liczba testów dostępności dla zasobu usługi Application Insights	100	100
Liczba testów dostępności na grupę zasobów	800	800	Zobacz Azure Resource Manager
Maksymalna liczba przekierowań na test dostępności	10	10
Minimalna częstotliwość testów dostępności	300 sekund		Niestandardowe częstotliwości testów lub częstotliwości krótsze niż 5 minut wymagają niestandardowych implementacji TrackAvailability.
Przechowywanie danych programu .NET Profiler i Snapshot Debugger	Dwa tygodnie	Skontaktuj się z pomocą techniczną. Maksymalny limit przechowywania wynosi sześć miesięcy.
Dane profilera .NET wysyłane codziennie	Brak ograniczeń	Brak limitu.
Snapshot Debugger dane wysyłane dziennie	30 migawek dziennie na monitorowaną aplikację	Brak limitu.	Liczbę migawek zebranych na aplikację można modyfikować za pomocą konfiguracji.

Aby uzyskać więcej informacji na temat cen i przydziałów, zobacz Rozliczenia usługi Application Insights.

Aby uniknąć osiągnięcia limitu szybkości danych, użyj próbkowania.

Aby określić, jak długo są przechowywane dane, zobacz Przechowywanie danych i prywatność.

Przykładowe aplikacje

Aplikacja konsolowa platformy .NET Core: użyj tego przykładu, jeśli używasz aplikacji konsolowej napisanej w programie .NET Core (2.0 lub nowszym) lub .NET Framework (4.7.2 lub nowszym).

ASP.NET Core zadania w tle z usługami hostingowymi: użyj tego przykładu, jeśli korzystasz z ASP.NET Core i tworzysz zadania w tle zgodnie z oficjalnymi wskazówkami.

Usługa procesu roboczego platformy .NET Core: użyj tego przykładu, jeśli masz aplikację usługi procesu roboczego platformy .NET zgodnie z oficjalnymi wskazówkami.

Rozwiązywanie problemów

Zobacz dedykowane artykuły dotyczące rozwiązywania problemów dla platformy .NET i Node.js.

Testowanie łączności między hostem aplikacji a usługą zbierania danych

Zestawy SDK i agenci usługi Application Insights wysyłają dane telemetryczne, które są przetwarzane jako wywołania REST do naszych punktów końcowych. Możesz przetestować łączność z serwera webowego lub maszyny hostującej aplikację do punktów końcowych usługi pozyskiwania, używając bezpośrednich klientów REST z poziomu programu PowerShell lub poleceń curl. Zobacz Rozwiązywanie problemów z brakującą telemetrią aplikacji w usłudze Azure Monitor Application Insights.

Zestaw SDK typu open source

Czytaj i współtwórz kod dla .NET i Node.js.

Notatki o wydaniu

• Informacje o wersji usługi Application Insights
• Wersje zestawu .NET SDK w usłudze GitHub
• Wydania SDK Node.js na platformie GitHub

Aktualizacje usługi również podsumowują główne ulepszenia usługi Application Insights.

Dalsze kroki

• Sprawdź, czy używasz obsługiwanej wersji zestawu SDK usługi Application Insights.
• Zobacz model danych dla typów usługi Application Insights i modelu danych.
• Zapoznaj się z podręcznikiem użytkownika System.Diagnostics.Activity , aby zobaczyć, jak korelujemy dane telemetryczne.
• Aby przejrzeć często zadawane pytania, zobacz:
  • ASP.NET — często zadawane pytania
  • ASP.NET Core — często zadawane pytania
  • Serwis roboczy — często zadawane pytania
  • Node.js — często zadawane pytania
  • Interfejs API dla niestandardowych zdarzeń i metryk — często zadawane pytania