Freigeben über


Überwachen von .NET-Anwendungen und -Diensten mit Application Insights (Klassische API)

Hinweis

Lesen Sie den Supportleitfaden des Application Insights SDK für unsere Klassische API SDK-Supportrichtlinie.

Vorsicht

Wir empfehlen die OpenTelemetry-Distribution von Azure Monitor für neue Anwendungen oder Kunden, um Azure Monitor Application Insights zu betreiben. Die OpenTelemetry-Distribution von Azure Monitor bietet eine ähnliche Funktionalität und Benutzererfahrung wie das Application Insights SDK. Es ist möglich, mithilfe der Migrationsleitfäden für .NET, Node.js und Python vom Application Insights SDK zu migrieren, wir arbeiten jedoch an der Integration zusätzlicher Funktionen für die Abwärtskompatibilität.

In diesem Artikel wird erläutert, wie Sie Application Insights für ASP.NET-, ASP.NET Core- und Worker Service-Anwendungen (non-HTTP) aktivieren und konfigurieren. Application Insights kann die folgenden Telemetriedaten aus Ihren Apps erfassen:

  • Requests
  • Abhängigkeiten
  • Exceptions
  • Leistungsindikatoren
  • Ablaufverfolgungen (Protokolle)
  • Herzschläge
  • Benutzerdefinierte Ereignisse und Metriken (erfordert manuelle Instrumentierung)
  • Seitenansichten (erfordert JavaScript SDK für Webseiten)
  • Verfügbarkeitstests (erfordert manuelles Einrichten von Verfügbarkeitstests)

Unterstützte Szenarien

Hinweis

Das Application Insights SDK für ASP.NET Core und SDK for Worker Service kann Ihre Anwendungen unabhängig davon überwachen, wo oder wie sie ausgeführt werden. Wenn Ihre Anwendung ausgeführt wird und über eine Netzwerkverbindung mit Azure verfügt, können Telemetriedaten erfasst werden.

Unterstützt ASP.NET ASP.NET Kern Workerdienst
Betriebssystem Fenster Windows, Linux oder macOS Windows, Linux oder macOS
Hostingmethode In-Prozess (IIS oder IIS Express) Im Prozess oder außerhalb des Prozesses Konsolen- oder Hintergrunddienst (wird als Prozess ausgeführt, in der Regel über dotnet CLI oder als Windows-Dienst/Linux-Daemon)
Bereitstellungsmethode Webbereitstellung, MSI oder manuelle Dateikopie Framework-abhängig oder komplett eigenständig Framework-abhängig oder komplett eigenständig
Webserver Internetinformationsdienste (IIS) Internetinformationsserver (IIS) oder Kestrel Nicht anwendbar (kein Webserver; entwickelt für Nicht-HTTP-Workloads wie Messaging, Hintergrundaufgaben und Konsolen-Apps)
Hostingplattform Azure App Service (Windows), Virtuelle Azure-Computer oder lokale Server Das Web-Apps-Feature von Azure App Service, Azure Virtual Machines, Docker und Azure Kubernetes Service (AKS) Azure Virtual Machines, Azure Kubernetes Service (AKS), Container oder eine beliebige Umgebung, in der .NET Core unterstützt wird
.NET-Version .NET Framework 4.6.1 und höher Alle offiziell unterstützten .NET-Versionen , die sich nicht in der Vorschau befinden Alle offiziell unterstützten .NET-Versionen , die sich nicht in der Vorschau befinden
IDE Visual Studio Visual Studio, Visual Studio Code oder Befehlszeile Visual Studio, Visual Studio Code oder Befehlszeile

Hinweis

Ein Workerdienst ist eine lang andauernde Hintergrundanwendung, die Aufgaben außerhalb einer HTTP-Anforderungs-/Antwortpipeline ausführt. Das Application Insights SDK for Worker Service kann in den neu eingeführten .NET Core Worker Service, Hintergrundaufgaben in ASP.NET Core- und Konsolen-Apps wie .NET Core und .NET Framework verwendet werden.

Das Worker Service SDK führt keine Telemetriesammlung eigenständig durch. Stattdessen werden andere bekannte Application Insights-Autosammler wie DependencyCollector, PerfCounterCollector und ApplicationInsightsLoggingProvider verwendet. Dieses SDK bietet Erweiterungsmethoden für IServiceCollection an, um die Telemetriesammlung zu aktivieren und zu konfigurieren.

Hinzufügen von Application Insights

Voraussetzungen

Erstellen einer einfachen Webanwendung

Wenn Sie noch keine funktionierende Webanwendung haben, können Sie den folgenden Leitfaden verwenden, um eine Webanwendung zu erstellen.

  1. Öffnen Sie Visual Studio.
  2. Wählen Sie Neues Projekt erstellen aus.
  3. Wählen Sie ASP.NET Webanwendung (.NET Framework) mit C# und dann "Weiter" aus.
  4. Geben Sie einen Projektnamen ein, und wählen Sie dann "Erstellen" aus.
  5. Wählen Sie MVC und dann "Erstellen" aus.

Automatisches Hinzufügen von Application Insights (Visual Studio)

Dieser Abschnitt führt Sie durch das automatische Hinzufügen von Application Insights zu einer vorlagenbasierten Web-App.

Führen Sie in Ihrem ASP.NET-Web-App-Projekt in Visual Studio die folgenden Schritte aus:

  1. Klicken Sie auf Projekt>Application Insights-Telemetrie hinzufügen>Application Insights SDK (lokal)>Weiter>Fertig stellen>Schließen.

  2. Öffnen Sie die Datei ApplicationInsights.config.

  3. Fügen Sie vor dem schließenden </ApplicationInsights>-Tag eine Zeile hinzu, die die Verbindungszeichenfolge für Ihre Application Insights-Ressource enthält. Ihre Verbindungszeichenfolge wird im Übersichtsbereich der neu erstellten Application Insights-Ressource angezeigt.

    <ConnectionString>Copy connection string from Application Insights Resource Overview</ConnectionString>
    
  4. Wählen Sie Projekt>NuGet-Pakete verwalten>Updates aus. Aktualisieren Sie dann jedes Microsoft.ApplicationInsights-NuGet-Paket auf das neueste stabile Release.

  5. Führen Sie Ihre Anwendung aus, indem Sie auf IIS Express klicken. Eine einfache ASP.NET-App wird geöffnet. Wenn Sie auf den Seiten der Website navigieren, werden Telemetriedaten an Application Insights gesendet.

Manuelles Hinzufügen von Application Insights (ohne Visual Studio)

Dieser Abschnitt führt Sie durch das manuelle Hinzufügen von Application Insights zu einer vorlagenbasierten Web-App.

  1. Fügen Sie die folgenden NuGet-Pakete und ihre jeweiligen Abhängigkeiten Ihrem Projekt hinzu:

  2. In einigen Fällen wird die ApplicationInsights.config-Datei automatisch für Sie erstellt. Wenn die Datei bereits vorhanden ist, können Sie mit Schritt 4 fortfahren.

    Erstellen Sie sie selbst, wenn sie fehlt. Erstellen Sie im Stammverzeichnis einer ASP.NET-Anwendung eine neue Datei namens ApplicationInsights.config.

  3. Kopieren Sie die folgende XML-Konfiguration in Ihre neu erstellte Datei:


    Erweitern, um die Konfiguration anzuzeigen
    <?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. Fügen Sie die Verbindungszeichenfolge hinzu. Dazu gibt es zwei Möglichkeiten:

    • (Empfohlen) Legen Sie die Verbindungszeichenfolge in der Konfiguration fest.

      Fügen Sie vor dem schließenden </ApplicationInsights>-Tag in ApplicationInsights.config die Verbindungszeichenfolge für Ihre Application Insights-Ressource hinzu. Ihre Verbindungszeichenfolge wird im Übersichtsbereich der neu erstellten Application Insights-Ressource angezeigt.

      <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
      
    • Legen Sie die Verbindungszeichenfolge im Code fest.

      Geben Sie eine Verbindungszeichenfolge in der program.cs-Klasse an.

      var configuration = new TelemetryConfiguration
      {
          ConnectionString = "Copy the connection string from your Application Insights resource"
      };
      
  5. Erstellen Sie auf derselben Projektebene wie der der ApplicationInsights.config-Datei einen Ordner namens ErrorHandler mit einer neuen C#-Datei namens AiHandleErrorAttribute.cs. Der Inhalt der Datei sieht wie folgt aus:

    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. Öffnen Sie im Ordner App_Start die Datei FilterConfig.cs, und ändern Sie sie so, dass sie dem Beispiel entspricht:

    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. Wenn Web.config bereits aktualisiert wurde, überspringen Sie diesen Schritt. Aktualisieren Sie die Datei andernfalls wie folgt:


    Erweitern, um die Konfiguration anzuzeigen
    <?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>
    

Sie haben nun erfolgreich die serverseitige Anwendungsüberwachung konfiguriert. Wenn Sie Ihre Web-App ausführen, werden in Application Insights Telemetriedaten angezeigt.

Überprüfen, ob Application Insights Telemetrie erhält

Führen Sie Ihre Anwendung aus, und senden Sie Anforderungen an diese. Nun sollten Telemetriedaten an Application Insights übermittelt werden. Mit dem Application Insights SDK werden eingehende Webanforderungen an die Anwendung sowie die folgenden Telemetriedaten automatisch erfasst.

Konfigurieren der Telemetrie

In diesem Abschnitt

Livemetriken

Mit Livemetriken kann schnell überprüft werden, ob die Anwendungsüberwachung mit Application Insights ordnungsgemäß konfiguriert ist. Es kann einige Minuten dauern, bis Telemetriedaten im Azure-Portal angezeigt werden. Im Bereich „Livemetriken“ wird jedoch die CPU-Auslastung des laufenden Prozesses nahezu in Echtzeit angezeigt. Außerdem können andere Telemetriedaten wie z. B. Anforderungen, Abhängigkeiten und Ablaufverfolgungen angezeigt werden.

Hinweis

Livemetriken sind standardmäßig aktiviert, wenn sie deren Onboarding gemäß den empfohlenen Anweisungen für .NET-Anwendungen durchführen.

Aktivieren von Livemetriken für beliebige .NET-Anwendungen mithilfe von Code

So konfigurieren Sie Livemetriken manuell

  1. Installieren Sie das NuGet-Paket Microsoft.ApplicationInsights.PerfCounterCollector.

  2. Im Folgenden finden Sie Beispielcode für die Konsolen-App zum Einrichten von Livemetriken:

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.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
            QuickPulseTelemetryProcessor quickPulseProcessor = null;
            config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
                .Use((next) =>
                {
                    quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
                    return quickPulseProcessor;
                })
                .Build();

            var quickPulseModule = new QuickPulseTelemetryModule();

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

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

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

Ablaufverfolgungen (Protokolle)

In diesem Abschnitt wird erläutert, wie Sie Diagnoseablaufverfolgungsprotokolle von ASP.NET oder ASP.NET Core-Anwendungen an Application Insights senden und diese Protokolle dann im Portal durchsuchen oder erforschen können.

Mithilfe von Ablaufverfolgungsprotokollen können Sie Ablaufverfolgungen identifizieren, die jeder Benutzeranforderung zugeordnet sind, und sie mit anderen Ereignissen und Ausnahmeberichten korrelieren.

Application Insights erfasst Protokolle von ASP.NET Core und anderen .NET-Apps über ILogger und von klassischem ASP.NET (.NET Framework) über das klassische SDK und die Adapter.

Hinweis

  • Standardmäßig sendet der Application Insights-Anbieter nur Protokolle mit einem Schweregrad von Warning oder höher. Um Information-Protokolle oder Protokolle mit einem niedrigeren Protokolliergrad einzuschließen, aktualisieren Sie die Protokolliergradeinstellungen in appsettings.json.

  • Das NuGet-Paket Microsoft.ApplicationInsights.WorkerService, das zum Aktivieren von Application Insights für Hintergrunddienste verwendet wird, liegt außerhalb des Bereichs.

  • Häufig gestellte Fragen (FAQ) finden Sie unter Protokollierung mit .NET FAQ.

Wählen Sie einen Protokollierungsansatz, um Diagnoseprotokolle auszugeben, die von Application Insights gesammelt werden können.

Installieren Sie die Protokollierung in Ihrer App

Konfigurieren Sie für klassische ASP.NET-Apps, die die System.Diagnostics-Ablaufverfolgung verwenden, einen Application Insights TraceListener in der Konfiguration.

Hinzufügen eines Listeners zu web.config oder app.config:

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

Hinweis

Das Protokollerfassungsmodul ist ein nützlicher Adapter für Logger von Drittanbietern. Wenn Sie jedoch noch nicht NLog, log4Net oder System.Diagnostics.Traceverwenden, sollten Sie Application Insights TrackTrace() direkt aufrufen.

Konfigurieren von Application Insights zum Sammeln von Protokollen

Option 1: Fügen Sie Ihrem Projekt Anwendungserkenntnisse hinzu, sofern dies noch nicht geschehen ist. Beim Hinzufügen von Application Insights in Visual Studio gibt es eine Option, den Protokollsammler einzuschließen.

Option 2: Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihr Projekt, um Anwendungserkenntnisse zu konfigurieren. Wählen Sie die Option Ablaufverfolgungssammlung konfigurieren.

Hinweis

Keine Application Insights-Menü- oder Protokollsammleroption? Versuchen Sie es mit der Problembehandlung.

Manuelle Installation

Verwenden Sie diese Methode, wenn Ihr Projekttyp vom Application Insights-Installationsprogramm (z. B. einigen Desktop-/Konsolenszenarien) nicht unterstützt wird oder wenn Sie explizite Steuerung auf Paketebene bevorzugen.

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihr Projekt, und wählen Sie "NuGet-Pakete verwalten" aus.

  2. Suchen Sie nach Application Insights.

  3. Wählen Sie eines der folgenden Pakete aus:

Das NuGet-Paket installiert die erforderlichen Assemblys und ändert web.config oder app.configgegebenenfalls.

Einbauanleitung:

Hinweis

Erweitern Sie einen der folgenden Abschnitte, um paketspezifische Installationsanweisungen zu erhalten.


ILogger
  1. Installieren Sie Microsoft.Extensions.Logging.ApplicationInsights.

  2. Fügen Sie ApplicationInsightsLoggerProvider hinzu:

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

Wenn das NuGet-Paket installiert ist und der Anbieter mit Abhängigkeitsinjektion registriert wird, kann die App Protokollierungen vornehmen. Bei Konstruktorinjektion ist entweder ILogger oder die generische Alternative ILogger<TCategoryName> erforderlich. Wenn diese Implementierungen aufgelöst werden, stellt ApplicationInsightsLoggerProvider diese zur Verfügung. Protokollierte Meldungen oder Ausnahmen werden zu Application Insights gesendet.

Betrachten Sie den folgenden Beispielcontroller:

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

Weitere Informationen finden Sie unter Protokollierung in ASP.NET Core und Welcher Application Insights-Telemetrietyp wird aus ILogger-Protokollen erstellt? Wo kann ich ILogger-Protokolle in Application Insights sehen?.

Einfügen von Diagnoseprotokollaufrufen (System.Diagnostics.Trace / log4net / NLog)

Wenn Sie verwenden System.Diagnostics.Trace, wäre ein typischer Anruf:

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

Wenn Sie log4net oder NLog bevorzugen, verwenden Sie:

    logger.Warn("Slow response - database01");
Verwenden von EventSource-Ereignissen

Sie können System.Diagnostics.Tracing.EventSource-Ereignisse so konfigurieren, dass sie als Ablaufverfolgungen an Application Insights gesendet werden.

  1. Installieren Sie das Microsoft.ApplicationInsights.EventSourceListener NuGet-Paket.

  2. Bearbeiten Sie den TelemetryModules Abschnitt der ApplicationInsights.config Datei:

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

Für jede Quelle können Sie die folgenden Parameter festlegen:

  • Der Name gibt den Namen der zu erfassenden EventSource an.
  • Ebene gibt den zu erfassenden Protokolliergrad an: Kritisch, Fehler, Information, LogAlways, Ausführlich oder Warnung.
  • Schlüsselwörter (optional) geben den ganzzahligen Wert der zu verwendenden Schlüsselwortkombinationen an.
Verwenden von DiagnosticSource-Ereignissen

Sie können System.Diagnostics.DiagnosticSource-Ereignisse so konfigurieren, dass sie als Ablaufverfolgungen an Application Insights gesendet werden.

  1. Installieren Sie das Microsoft.ApplicationInsights.DiagnosticSourceListener NuGet-Paket.

  2. Bearbeiten Sie den TelemetryModules Abschnitt der ApplicationInsights.config Datei:

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

Fügen Sie für jede Diagnosequelle, die Sie nachverfolgen möchten, einen Eintrag hinzu, bei dem das Attribut Name auf den Namen Ihrer Diagnosequelle festgelegt ist.

ETW-Ereignisse verwenden

Sie können ETW-Ereignisse (Ereignisablaufverfolgung für Windows) so konfigurieren, dass sie als Ablaufverfolgungen an Application Insights gesendet werden.

  1. Installieren Sie das Microsoft.ApplicationInsights.EtwCollector NuGet-Paket.

  2. Bearbeiten Sie den Abschnitt "TelemetryModules" der dateiApplicationInsights.config :

Hinweis

ETW-Ereignisse können nur erfasst werden, wenn der Prozess, der das SDK hostet, unter einer Identität ausgeführt wird, die Mitglied von Performance Log Users oder Administratoren ist.

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

Für jede Quelle können Sie die folgenden Parameter festlegen:

  • ProviderName ist der Name des zu erfassenden ETW-Anbieters.
  • ProviderGuid gibt die GUID des zu erfassenden ETW-Anbieters an. Es kann anstelle von ProviderName.
  • Ebene legt den zu erfassenden Protokolliergrad fest. Dieser kann Critical, Error, Informational, LogAlways, Verbose oder Warning sein.
  • Schlüsselwörter (optional) legen den ganzzahligen Wert der zu verwendenden Schlüsselwortkombinationen fest.
Nutzen Sie die Ablaufverfolgungs-API direkt

Sie können die Application Insights-Ablaufverfolgungs-API direkt aufrufen. Die Protokollierungsadapter verwenden diese API. Beispiel:

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

Ein Vorteil TrackTrace ist, dass Sie relativ lange Daten in die Nachricht einfügen können. Beispielsweise können Sie POST-Daten dort codieren.

Sie können Ihrer Nachricht auch einen Schweregradstufe hinzufügen. Wie bei anderen Telemetriedaten auch können Sie Eigenschaftswerte hinzufügen, um zu filtern oder nach verschiedenen Ablaufverfolgungen zu suchen. Beispiel:

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

Jetzt können Sie ganz einfach alle Mitteilungen eines bestimmten Schweregrads in der Transaktionssuche herausfiltern, die sich auf eine bestimmte Datenbank beziehen.

Konsolenanwendung

Um die Application Insights-Protokollierung zu Konsolenanwendungen hinzuzufügen, installieren Sie zuerst die folgenden NuGet-Pakete:

Im folgenden Beispiel wird das Paket Microsoft.Extensions.Logging.ApplicationInsights verwendet und das Standardverhalten für eine Konsolenanwendung veranschaulicht. Das Paket Microsoft.Extensions.Logging.ApplicationInsights sollte in einer Konsolenanwendung verwendet werden oder wann immer Sie eine minimale Mindestimplementierung von Application Insights ohne den vollständigen Funktionssatz benötigen, z. B. Metriken, verteilte Ablaufverfolgung, Sampling und Telemetrieinitialisierer.

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

Weitere Informationen finden Sie unter Welcher Application Insights-Telemetrietyp wird aus ILogger-Protokollen erstellt? Wo kann ich ILogger-Protokolle in Application Insights sehen?.

Protokollierungsbereiche

Hinweis

Die folgenden Richtlinien gelten für ILogger-Szenarien (nur ASP.NET Core und Konsole). Es gilt nicht für klassische ASP.NET.

ApplicationInsightsLoggingProvider unterstützt Protokollbereiche, die standardmäßig aktiviert sind.

Bei einem Bereich vom Typ IReadOnlyCollection<KeyValuePair<string,object>> wird jedes Schlüssel-Wert-Paar in der Sammlung als benutzerdefinierte Eigenschaft zur Application Insights-Telemetrie hinzugefügt. Im folgenden Beispiel werden Protokolle als die Eigenschaften TraceTelemetry und ("MyKey", "MyValue") erfasst.

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

Wenn ein anderer Typ als Umfang verwendet wird, wird er unter der Eigenschaft Scope in der Application Insights-Telemetrie gespeichert. Im folgenden Beispiel verfügt TraceTelemetry über eine Eigenschaft namens Scope, die den Bereich enthält.

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

Ihre Protokolle suchen

Führen Sie Ihre App im Debugmodus aus, oder stellen Sie sie live bereit.

Wählen Sie im Übersichtsbereich Ihrer App im Portal "Application Insights" die Option "Transaktionssuche " aus, in der Sie folgende Aktionen ausführen können:

  • Filtern sie nach Protokollablaufverfolgungen oder auf Elementen mit bestimmten Eigenschaften.
  • Überprüfen Sie ein bestimmtes Element im Detail.
  • Suchen Sie andere Systemprotokolldaten, die sich auf dieselbe Benutzeranforderung beziehen (hat dieselbe Vorgangs-ID).
  • Speichern Sie die Konfiguration einer Seite als Favorit.

Hinweis

Wenn Ihre Anwendung viele Daten sendet und Sie das Application Insights SDK für ASP.NET Version 2.0.0-Beta3 oder höher verwenden, funktioniert das Feature für adaptives Sampling möglicherweise und sendet nur einen Teil Ihrer Telemetrie. Erfahren Sie mehr über Sampling.

Erkunden in Azure Monitor-Protokollen

ILogger-Protokolle werden als Ablaufverfolgungs-Telemetrie (Tabelle traces in Application Insights und AppTraces in Log Analytics) angezeigt.

Beispiel

Wechseln Sie im Azure-Portal zu Application Insights, und führen Sie Folgendes aus:

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

Verteilte Ablaufverfolgung

Moderne Cloud- und Microservices-Architekturen haben einfache, unabhängig bereitgestellte Dienste ermöglicht, die Kosten senken und gleichzeitig die Verfügbarkeit und den Durchsatz erhöhen. Es hat jedoch gesamte Systeme schwieriger gemacht, nachzuvollziehen und zu debuggen. Die verteilte Ablaufverfolgung löst dieses Problem, indem sie einen Leistungsprofiler bereitstellt, der wie Aufrufstapel für Cloud- und Microservices-Architekturen funktioniert.

Azure Monitor bietet zwei Oberflächen für die Verwendung verteilter Ablaufverfolgungsdaten: die Ansicht "Transaktionsdiagnose " für eine einzelne Transaktion/Anforderung und die Anwendungszuordnungsansicht , um zu zeigen, wie Systeme interagieren.

Application Insights kann jede Komponente separat überwachen und erkennen, welche Komponente für Fehler oder Leistungsbeeinträchtigungen mit verteilter Telemetriekorrelation verantwortlich ist. In diesem Artikel werden das Datenmodell, die Kontextverteilungstechniken, Protokolle und die Implementierung von Korrelationstaktiken auf verschiedenen Sprachen und Plattformen erläutert, die von Application Insights verwendet werden.

Verteiltes Tracing mithilfe von Application Insights durch Autoinstrumentierung oder SDKs aktivieren.

Die Application Insights-Agents und SDKs für .NET, .NET Core, Java, Node.js und JavaScript unterstützen verteiltes Tracing nativ.

Wenn das richtige Application Insights SDK installiert und konfiguriert ist, werden Ablaufverfolgungsinformationen für gängige Frameworks, Bibliotheken und Technologien automatisch von der automatischen Erfassung (Autocollectors) für SDK-Abhängigkeiten gesammelt. Die vollständige Liste der unterstützten Technologien finden Sie unter Automatisches Sammeln von Abhängigkeiten.

Jede Technologie kann auch manuell mit einem Aufruf von TrackDependency auf dem TelemetryClient nachverfolgt werden.

Datenmodell für Telemetriekorrelation

Application Insights definiert ein Datenmodell für die verteilte Telemetriekorrelation. Um Telemetrie einem logischen Vorgang zuzuordnen, weist jedes Telemetrieelement ein Kontextfeld auf operation_Id. Jedes Telemetrieelement in der verteilten Nachverfolgung teilt diesen Bezeichner. Selbst wenn Sie die Telemetrie von einer einzelnen Ebene verlieren, können Sie die Telemetrie, die von anderen Komponenten gemeldet wird, weiterhin zuordnen.

Ein verteilter logischer Vorgang besteht typischerweise aus einer Reihe kleinerer Operationen, die als Anfragen von einer der Komponenten verarbeitet werden. Die Telemetrieanforderung definiert diese Vorgänge. Jedes Anforderungstelemetrieelement verfügt über eine eigene id, die es eindeutig und global identifiziert. Für sämtliche Telemetrieelemente (z.B. Ablaufverfolgungen und Ausnahmen), die der Anforderung zugeordnet sind, sollte die operation_parentId auf den Wert der Anforderungs-id festgelegt werden.

Die Abhängigkeits-Telemetrie stellt jeden ausgehenden Vorgang dar, z. B. einen HTTP-Aufruf an eine andere Komponente. Es definiert auch eine eigene id, die global eindeutig ist. Anforderungsabhängigkeiten, die durch diese Anforderungstelemetrie initiiert werden, verwenden diese id als operation_parentId.

Sie können eine Ansicht der verteilten logischen Operation mithilfe von operation_Id, operation_parentId und request.id mit dependency.id erstellen. Diese Felder definieren auch die Kausalitätsreihenfolge von Telemetrieanrufen.

In Microserviceumgebungen können Ablaufverfolgungen von Komponenten an unterschiedliche Speicherelemente weitergeleitet werden. Jede Komponente kann eine eigene Verbindungszeichenfolge in Application Insights haben. Um Telemetrie für den logischen Vorgang abzurufen, fragt Application Insights Daten aus jedem Speicherelement ab.

Wenn die Anzahl der Speicherelemente groß ist, benötigen Sie einen Hinweis dazu, wo Sie als Nächstes suchen können. Das Application Insights-Datenmodell definiert zwei Felder, um dieses Problem zu lösen: request.source und dependency.target. Das erste Feld identifiziert die Komponente, die die Abhängigkeitsanforderung initiiert hat. Das zweite Feld gibt an, welche Komponente die Antwort des Abhängigkeitsaufrufs zurückgegeben hat.

Informationen zum Abfragen von mehreren unterschiedlichen Instanzen finden Sie unter Abfragedaten in Log Analytics-Arbeitsbereichen, Anwendungen und Ressourcen in Azure Monitor.

Example

Schauen wir uns ein Beispiel an. Eine Anwendung namens "Aktienkurse" zeigt den aktuellen Börsenkurs einer Aktie mithilfe einer externen API namens "Aktien" an. Die Anwendung "Aktienkurse" hat eine Seite namens "Aktienseite", die der Client-Webbrowser mithilfe von GET /Home/Stock öffnet. Die Anwendung fragt die Aktien-API mithilfe des HTTP-Aufrufs GET /api/stock/valueab.

Sie können die resultierende Telemetrie analysieren, indem Sie eine Abfrage ausführen:

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

In den Ergebnissen teilen alle Telemetrieelemente den Stamm operation_Id. Wenn ein Ajax-Aufruf von der Seite aus erfolgt, wird der Abhängigkeits-Telemetrie eine neue eindeutige ID (qJSXU) zugewiesen, und die ID der pageView wird als operation_ParentId verwendet. Die Serveranforderung verwendet dann die Ajax-ID als operation_ParentId.

Elementtyp name ID operation_ParentId operation_Id
pageView Stock page STYz STYz
Abhängigkeit GET /Home/Stock qJSXU STYz STYz
request GET Home/Stock KqKwlrSt9PA= qJSXU STYz
Abhängigkeit GET /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

Wenn der Aufruf GET /api/stock/value an einen externen Dienst erfolgt, müssen Sie die Identität dieses Servers kennen, damit Sie das dependency.target Feld entsprechend festlegen können. Wenn der externe Dienst die Überwachung nicht unterstützt, wird target auf den Hostnamen des Dienstes festgelegt. Beispiel ist stock-prices-api.com. Wenn sich der Dienst jedoch durch Zurückgeben eines vordefinierten HTTP-Headers identifiziert, enthält er die Dienstidentität, target mit der Application Insights eine verteilte Ablaufverfolgung erstellen kann, indem Telemetrie von diesem Dienst abgefragt wird.

Korrelationsheader mit W3C TraceContext

Application Insights wechselt in den W3C-Ablaufverfolgungskontext, der Folgendes definiert:

  • traceparent: Trägt die global eindeutige Vorgangs-ID und den eindeutigen Bezeichner des Aufrufs.
  • tracestate: Enthält einen systemspezifischen Ablaufverfolgungskontext.

Die neueste Version des Application Insights SDK unterstützt das Trace-Context-Protokoll, sie müssen sich aber möglicherweise anmelden. (Die Abwärtskompatibilität mit dem vorherigen Korrelationsprotokoll, das vom Application Insights SDK unterstützt wird, wird beibehalten.)

Das Korrelations-HTTP-Protokoll, auch als Anforderungs-ID bezeichnet, ist veraltet. Dieses Protokoll definiert zwei Header:

  • Request-Id: Trägt die global eindeutige ID des Anrufs.
  • Correlation-Context: Enthält die Sammlung von Name/Wert-Paaren der Eigenschaften von verteilten Ablaufverfolgungen.

Application Insights definiert auch die Erweiterung für das Korrelations-HTTP-Protokoll. Er verwendet Name/Wert-Paare für Request-Context, die die vom unmittelbaren Aufrufer oder Aufgerufenen verwendete Sammlung von Eigenschaften propagieren. Das Application Insights SDK verwendet diesen Header, um die Felder dependency.target und request.source festzulegen.

Die Datenmodelle "W3C Trace-Context" und "Application Insights" werden wie folgt zugeordnet:

Application Insights W3C TraceContext
Id von Request und Dependency parent-id
Operation_Id Trace-ID
Operation_ParentId parent-id der übergeordneten Spanne dieser Spanne. Dieses Feld muss leer sein, wenn es sich um eine Wurzelspanne handelt.

Weitere Informationen finden Sie im Telemetriemodell von Application Insights.

Aktivieren der Unterstützung für verteilte W3C-Ablaufverfolgung

Die auf W3C TraceContext basierende verteilte Ablaufverfolgung ist in allen zuletzt verwendeten .NET Framework/.NET Core SDKs standardmäßig aktiviert, zusammen mit der Abwärtskompatibilität mit dem Legacyprotokoll Request-Id .

Telemetriekorrelation

Die Korrelation wird beim Onboarding einer App standardmäßig behandelt. Es sind keine besonderen Aktionen erforderlich.

.NET-Laufzeitumgebung unterstützt verteilte Systeme mithilfe von Activity und DiagnosticSource

Das Application Insights .NET SDK verwendet DiagnosticSource und Activity, um Telemetrie zu sammeln und zu korrelieren.

Fehlerbehebung bei Trace-Protokollen

Hier finden Sie Antworten auf häufig gestellte Fragen.


Erweitern, um Themen zur Problembehandlung anzuzeigen
Was bewirkt verzögerte Telemetrie, ein überlastetes Netzwerk und eine ineffiziente Übertragung?

System.Diagnostics.Tracing verfügt über ein Autoflush-Feature. Dieses Feature führt dazu, dass das SDK bei jedem Telemetrieelement eine Leerung durchführt. Dies ist nicht erwünscht und kann zu Problemen mit dem Protokollierungsadapter führen, z. B. zu verzögerter Telemetrie, einer Überlastung des Netzwerks sowie ineffizienter Übertragung.

Wie kann ich dies für Java tun?

In der codelosen Java-Instrumentierung, die empfohlen wird, werden die Protokolle sofort erfasst. Verwenden Sie den Java 3.0-Agent.

Der Java-Agent von Application Insights sammelt Protokolle aus Log4j, Logback und java.util.logging standardmäßig.

Warum gibt es keine Option "Application Insights" im Kontextmenü des Projekts?
  • Stellen Sie sicher, dass Die Entwickleranalysetools auf dem Entwicklungscomputer installiert sind. Wechseln Sie in Visual Studio zu Tools-Erweiterungen>und -Updates, und suchen Sie nach Developer Analytics-Tools. Wenn sie sich nicht auf der Registerkarte "Installiert " befindet, öffnen Sie die Registerkarte "Online ", und installieren Sie sie.
  • Dieser Projekttyp kann einer sein, der von den Developer Analytics-Tools nicht unterstützt wird. Manuelle Installation verwenden.
Warum gibt es keine Protokolladapteroption im Konfigurationstool?
  • Installieren Sie zuerst das Protokollierungsframework.
  • Wenn Sie System.Diagnostics.Trace verwenden, stellen Sie sicher, dass Sie sie in web.configkonfiguriert haben.
  • Stellen Sie sicher, dass Sie über die neueste Version von Application Insights verfügen. Wechseln Sie in Visual Studio zu "Extras>Erweiterungen und Updates ", und öffnen Sie die Registerkarte "Updates ". Wenn die Entwickleranalysetools vorhanden sind, wählen Sie sie aus, um sie zu aktualisieren.
Warum erhalte ich die Fehlermeldung "Instrumentierungsschlüssel darf nicht leer sein"?

Sie haben wahrscheinlich das NuGet-Paket des Protokollierungsadapters installiert, ohne Application Insights zu installieren. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste aufApplicationInsights.config, und wählen Sie "Anwendungserkenntnisse aktualisieren" aus. Sie werden aufgefordert, sich bei Azure anzumelden und eine Application Insights-Ressource zu erstellen oder eine vorhandene Ressource wiederzuverwenden. Es sollte das Problem beheben.

Es kann eine Weile dauern, bis alle Ereignisse und Anforderungen über die Pipeline abgerufen werden.

Wie viele Daten werden aufbewahrt?

Mehrere Faktoren wirken sich auf die Datenmenge aus, die aufbewahrt wird. Weitere Informationen finden Sie im Abschnitt "Grenzwerte" der Seite "Kundenereignismetriken".

Warum werden einige von mir erwartete Protokolleinträge nicht angezeigt?

Vielleicht sendet Ihre Anwendung voluminöse Datenmengen und Sie verwenden das Application Insights SDK für ASP.NET Version 2.0.0-Beta3 oder höher. In diesem Fall kann die adaptive Sampling-Funktion funktionieren und nur einen Teil Ihrer Telemetrie senden. Erfahren Sie mehr über Sampling.

Abhängigkeiten

Automatisch nachverfolgte Abhängigkeiten

Application Insights-SDKs für .NET und .NET Core werden mit DependencyTrackingTelemetryModule ausgeliefert, einem Telemetriemodul, das Abhängigkeiten automatisch erfasst. Das Modul DependencyTrackingTelemetryModule wird als Microsoft.ApplicationInsights.DependencyCollector-NuGet-Paket ausgeliefert und automatisch bereitgestellt, wenn Sie entweder das Microsoft.ApplicationInsights.Web-NuGet-Paket oder das Microsoft.ApplicationInsights.AspNetCore-NuGet-Paket verwenden.

Derzeit verfolgt DependencyTrackingTelemetryModule automatisch die folgenden Abhängigkeiten:

Abhängigkeiten Einzelheiten
HTTP/HTTPS Lokale oder Remote-HTTP/HTTPS-Aufrufe.
WCF-Aufrufe Wird nur automatisch verfolgt, wenn HTTP-basierte Bindungen verwendet werden.
SQL Aufrufe mit SqlClient. Informationen zum Erfassen von SQL-Abfragen finden Sie im Abschnitt Erweitertes SQL-Tracking, um eine vollständige SQL-Abfrage zu erhalten.
Azure Blob Storage, Table Storage, oder Queue Storage Aufrufe mit dem Azure Storage-Client.
Azure Event Hubs-Client-SDK Verwenden Sie das neueste Paket: https://nuget.org/packages/Azure.Messaging.EventHubs.
Azure Service Bus-Client-SDK Verwenden Sie das neueste Paket: https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB Wird automatisch nachverfolgt, wenn HTTP/HTTPS verwendet wird. Die Ablaufverfolgung für Vorgänge im direkten Modus mit TCP wird auch automatisch mithilfe des Vorschaupakets >= 3.33.0-preview erfasst. Weitere Details finden Sie in der Dokumentation.

Wenn die Abhängigkeit nicht automatisch erfasst wird, können Sie sie manuell mit einem Track-Abhängigkeitsaufruf nachverfolgen.

Weitere Informationen zur Funktionsweise der Abhängigkeitsnachverfolgung finden Sie unter Abhängigkeitsnachverfolgung in Application Insights.

Richten Sie die automatische Abhängigkeitsverfolgung in Konsolen-Apps ein

Um Abhängigkeiten in .NET-Konsolen-Apps automatisch nachzuverfolgen, installieren Sie das NuGet-Paket Microsoft.ApplicationInsights.DependencyCollector, und initialisieren Sie DependencyTrackingTelemetryModule wie folgt:

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

Hinweis

Für .NET Core-Konsolenanwendungen ist TelemetryConfiguration.Active veraltet.

Manuelle Nachverfolgung von Abhängigkeiten

Die folgenden Beispiele für Abhängigkeiten, die nicht automatisch erfasst werden, erfordern eine manuelle Nachverfolgung:

  • Azure Cosmos DB wird nur dann automatisch nachverfolgt, wenn HTTP/HTTPS verwendet wird. Der TCP-Modus wird von Application Insights für SDK-Versionen nach 2.22.0-Beta1 nicht automatisch erfasst.
  • Redis

Abhängigkeiten, die nicht automatisch vom SDK erfasst werden, können Sie manuell nachverfolgen, indem Sie dieTrackDependency-API verwenden, die von den standardmäßigen automatischen Erfassungsmodulen verwendet wird.

Beispiel

Wenn Sie Ihren Code mit einer Assembly erstellen, die Sie nicht selbst geschrieben haben, können Sie alle Aufrufe zeitlich festlegen. In diesem Szenario könnten Sie herausfinden, welche Beiträge sie zu Ihren Reaktionszeiten leisten.

Damit diese Daten in den Abhängigkeitsdiagrammen in Application Insights angezeigt werden, senden Sie sie mit 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);
    }

Alternativ stellt TelemetryClient die Erweiterungsmethoden StartOperation and StopOperationbereit, die zum manuellen Verfolgen von Abhängigkeiten verwendet werden können, wie in Verfolgung ausgehender Abhängigkeiten gezeigt.

Deaktivierung des Standardmoduls zur Abhängigkeitsverfolgung

Weitere Informationen finden Sie unter Telemetriemodule.


Erweitertes SQL-Tracking, um eine vollständige SQL-Abfrage zu erhalten

Bei SQL-Aufrufen wird immer der Name des Servers und der Datenbank gesammelt und als Name des gesammelten DependencyTelemetry gespeichert. Ein weiteres Feld namens data kann den vollständigen SQL-Abfragetext enthalten.

Hinweis

Azure Functions erfordert separate Einstellungen, um die SQL-Texterfassung zu aktivieren. Weitere Informationen finden Sie unter Aktivieren der SQL-Abfragesammlung.

Für ASP.NET-Anwendungen wird der vollständige SQL-Abfragetext mit Hilfe der Bytecode-Instrumentierung erfasst, was die Verwendung des Instrumentierungsmoduls oder die Verwendung des Microsoft.Data.SqlClient-NuGet-Pakets anstelle der System.Data.SqlClient-Bibliothek erfordert. Plattformspezifische Schritte zum Aktivieren der vollständigen SQL-Abfragesammlung werden in der folgenden Tabelle beschrieben.

Plattform Erforderliche Schritte, um eine vollständige SQL-Abfrage zu erhalten
Web-Apps in Azure App Service In der Systemsteuerung Ihrer Web-App öffnen Sie das Application Insights-Bereich, und aktivieren Sie SQL-Befehle unter .NET.
IIS-Server (Azure Virtual Machines, lokal und so weiter) Verwenden Sie entweder das NuGet-Paket Microsoft.Data.SqlClient oder das Application Insights Agent-PowerShell-Modul, um die Instrumentierungs-Engine zu installieren und IIS neu zu starten.
Azure Cloud Services Fügen Sie eine Startaufgabe zum Installieren von StatusMonitor hinzu.
Ihre App sollte zur Erstellungszeit in das ApplicationInsights-SDK integriert werden, indem NuGet-Pakete für ASP.NET- oder ASP.NET Core-Anwendungen installiert werden.
IIS Express Verwenden Sie das NuGet-Paket Microsoft.Data.SqlClient.
WebJobs in Azure App Service Verwenden Sie das NuGet-Paket Microsoft.Data.SqlClient.

Zusätzlich zu den vorangegangenen plattformspezifischen Schritten müssen Sie sich auch ausdrücklich für die Aktivierung der SQL-Befehlssammlung anmelden, indem Sie die ApplicationInsights.config-Datei mit dem folgenden Code ändern:

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

In den vorstehenden Fällen besteht die ordnungsgemäße Methode zum Überprüfen, ob die Instrumentierungs-Engine korrekt installiert ist, darin, zu überprüfen, ob die SDK-Version des erfassten DependencyTelemetryrddp ist. Die Verwendung von rdddsd oder rddf zeigt an, dass Abhängigkeiten über DiagnosticSource oder EventSource-Callbacks gesammelt werden, sodass die vollständige SQL-Abfrage nicht erfasst wird.

Exceptions

Ausnahmen in Webanwendungen können mit Application Insights gemeldet werden. Sie können Anforderungsfehler mit Ausnahmen und anderen Ereignissen auf dem Client und auf dem Server zueinander in Beziehung setzen und dadurch die Ursachen schnell diagnostizieren. In diesem Abschnitt wird beispielsweise erläutert, wie Sie die Ausnahmeberichterstattung einrichten, Ausnahmen explizit melden und Fehler diagnostizieren.

Einrichten der Ausnahmeerfassung

Sie können Application Insights so einrichten, dass Ausnahmen gemeldet werden, die entweder auf dem Server oder auf dem Client auftreten. Abhängig von der Plattform, von der Ihre Anwendung abhängig ist, benötigen Sie die entsprechende Erweiterung oder das entsprechende SDK.

Berücksichtigen Sie die folgenden Szenarien, damit Ausnahmen von Ihrer serverseitigen Anwendung gemeldet werden:

Von Bedeutung

Dieser Abschnitt konzentriert sich auf .NET Framework-Apps aus codebeispielbezogener Sicht. Einige der Methoden, die für .NET Framework eingesetzt werden, sind im .NET Core SDK veraltet.

Diagnostizieren von Fehlern und Ausnahmen

Application Insights umfasst eine zusammengestellte Application Performance Management-Benutzeroberfläche, die Sie beim Diagnostizieren von Fehlern in Ihren überwachten Anwendungen unterstützt.

Ausführliche Anweisungen finden Sie unter Untersuchen von Fehlern, Leistung und Transaktionen mit Application Insights.

Benutzerdefinierte Ablaufverfolgung und Protokolldaten

Um spezifische Diagnosedaten für Ihre App zu erhalten, können Sie Code zum Senden Ihrer eigenen Telemetriedaten einfügen. Ihre benutzerdefinierten Telemetrie- oder Protokolldaten werden in der Diagnosesuche zusammen mit der Anforderung, der Seitenansicht und anderen automatisch gesammelten Daten angezeigt.

Wenn Sie Microsoft.VisualStudio.ApplicationInsights.TelemetryClient verwenden, sind mehrere APIs verfügbar:

Um diese Ereignisse anzuzeigen, öffnen Sie im linken Menü die Suche. Wählen Sie das Dropdownmenü Ereignistypen aus, und wählen Sie dann Benutzerdefiniertes Ereignis, Ablaufverfolgung oder Ausnahme aus.

Screenshot: Suchbildschirm

Hinweis

Wenn die Anwendung große Mengen Telemetriedaten generiert, reduziert das Modul zur adaptiven Stichprobenerstellung automatisch die an das Portal gesendete Datenmenge, indem nur ein repräsentativer Bruchteil der Ereignisse gesendet wird. Ereignisse, die Teil des gleichen Vorgangs sind, werden als Gruppe aus- oder abgewählt, sodass Sie zwischen verwandten Ereignissen navigieren können. Weitere Informationen finden Sie unter Erstellen von Stichproben in Application Insights.

Anzeigen der POST-Daten von Anforderungen

Anforderungsdetails enthalten nicht die Daten, die in einem POST-Aufruf an Ihre App gesendet wurden. So werden diese Daten gemeldet:

Standardmäßig werden nicht alle Ausnahmen, die zu Fehlern in Ihrer Anwendung führen, im Portal angezeigt. Wenn Sie das JavaScript SDK auf Ihren Webseiten verwenden, werden Browser-Ausnahmen angezeigt. Die meisten serverseitigen Ausnahmen werden jedoch von IIS abgefangen, sodass Sie zusätzlichen Code hinzufügen müssen, um sie zu erfassen und zu melden.

Sie haben folgende Möglichkeiten:

  • Ausnahmen explizit protokollieren durch Einfügen von Code in Ausnahmehandlern, um Ausnahmen zu melden.
  • Ausnahmen automatisch erfassen durch Konfigurieren Ihres ASP.NET-Frameworks. Die erforderlichen Änderungen unterscheiden sich für verschiedene Frameworktypen.
Explizites Melden von Ausnahmen

Das Melden erfolgt am einfachsten, indem Sie in einem Ausnahmehandler einen Aufruf von trackException() einfügen.

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

Die Eigenschaften und Messparameter sind optional, aber hilfreich zum Filtern und Hinzufügen zusätzlicher Informationen. Wenn Sie z. B. eine Anwendung haben, die mehrere Spiele ausführen kann, können Sie alle im Zusammenhang mit einem bestimmten Spiel stehenden Ausnahmeberichte ermitteln. Sie können jedem Wörterbuch beliebig viele Elemente hinzufügen.

Browserausnahmen

Die meisten Browserausnahmen werden gemeldet.

Wenn Ihre Webseite Skriptdateien aus Content Delivery Networks oder anderen Domänen umfasst, stellen Sie sicher, dass Ihr Skripttag das Attribut crossorigin="anonymous" aufweist und dass der Server CORS-Header sendet. Durch dieses Verhalten können Sie eine Stapelüberwachung und Details zu nicht behandelten JavaScript-Ausnahmen von diesen Ressourcen abrufen.

Wiederverwenden Ihres Telemetrieclients

Hinweis

Es wird empfohlen, den TelemetryClient einmal zu instanziieren und während der gesamten Lebensdauer einer Anwendung wiederzuverwenden.

Mit der Abhängigkeitsinjektion (Dependency Injection, DI) in .NET, dem entsprechenden .NET SDK und einer ordnungsgemäß konfigurierten Application Insights-Instanz für die Abhängigkeitsinjektion können Sie TelemetryClient als Konstruktorparameter anfordern.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

Im vorherigen Beispiel wird TelemetryClient in die ExampleController-Klasse eingefügt.

Webformulare

Für Webformulare kann das HTTP-Modul die Ausnahmen erfassen, wenn keine Umleitungen mit CustomErrors konfiguriert sind. Wenn jedoch aktive Umleitungen bestehen, fügen Sie der Application_Error-Funktion in Global.asax.cs die folgenden Zeilen hinzu.

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

Im vorherigen Beispiel ist _telemetryClient eine klassenspezifische Variable vom Typ TelemetryClient.

MVC

Ab Application Insights Web SDK-Version 2.6 (Beta 3 und höher) sammelt Application Insights Ausnahmefehler automatisch, die in den MVC 5+-Controllermethoden ausgelöst werden. Falls Sie bereits einen benutzerdefinierten Handler zum Nachverfolgen solcher Ausnahmen hinzugefügt haben, können Sie ihn entfernen, um eine doppelte Nachverfolgung von Ausnahmen zu verhindern.

Es gibt mehrere Szenarien, in denen ein Ausnahmefilter Fehler nicht ordnungsgemäß behandeln kann, wenn Ausnahmen ausgelöst werden:

  • Über Controllerkonstruktoren
  • Über Meldungshandler
  • Während des Routings
  • Während der Serialisierung des Antwortinhalts
  • Während des Anwendungsstarts
  • Bei Hintergrundaufgaben

Alle Ausnahmen die von der Anwendung verarbeitet werden, müssen weiterhin manuell nachverfolgt werden. Ausnahmefehler, die von Controllern ausgehen, führen normalerweise zu Antwort 500 (Interner Serverfehler). Wenn eine Antwort dieser Art aufgrund einer behandelten Ausnahme (oder keiner Ausnahme) manuell erstellt wird, wird sie in der dazugehörigen Anforderungstelemetrie mit ResultCode 500 nachverfolgt. Mit dem Application Insights SDK kann die entsprechende Ausnahme jedoch nicht nachverfolgt werden.

Unterstützung von früheren Versionen

Wenn Sie MVC 4 (und früher) des Application Insights Web SDK 2.5 (und früher) verwenden, sind die folgenden Beispiele zum Nachverfolgen von Ausnahmen hilfreich.


Erweitern, um Anweisungen für frühere Versionen anzuzeigen

Wenn die CustomErrors-Konfiguration Off lautet, stehen für das HTTP-Modul zu erfassende Ausnahmen zur Verfügung. Lautet sie allerdings RemoteOnly (Standardeinstellung) oder On, wird die Ausnahme gelöscht und steht für die automatische Erfassung durch Application Insights nicht zur Verfügung. Dieses Verhalten können Sie beheben, indem Sie die System.Web.Mvc.HandleErrorAttribute-Klasse außer Kraft setzen und die außer Kraft gesetzte Klasse wie hier gezeigt für die verschiedenen MVC-Versionen anwenden (GitHub-Quelle):

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

Ersetzen Sie das HandleError-Attribut durch das neue Attribut in Ihren Controllern:

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

Beispiel

MVC 3

Registrieren Sie AiHandleErrorAttribute als globalen Filter in Global.asax.cs:

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

Beispiel

MVC 4, MVC 5

Registrieren Sie AiHandleErrorAttribute als globalen Filter in FilterConfig.cs:

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

Beispiel

Web-API

Ab Application Insights Web SDK-Version 2.6 (Beta 3 und höher) erfasst Application Insights Ausnahmefehler, die in den Controllermethoden ausgelöst werden, für Web-API 2+ automatisch. Wenn Sie vorher bereits einen benutzerdefinierten Handler zum Nachverfolgen dieser Ausnahmen hinzugefügt haben (wie in den folgenden Beispielen beschrieben), können Sie ihn entfernen, um eine doppelte Nachverfolgung von Ausnahmen zu verhindern.

Es gibt eine Reihe von Fällen, die von den Ausnahmefiltern nicht verarbeitet werden können. Beispiel:

  • Von Controllerkonstruktoren ausgelöste Ausnahmen.
  • Von Meldungshandlern ausgelöste Ausnahmen.
  • Während des Routings ausgelöste Ausnahmen.
  • Während der Serialisierung von Antwortinhalten ausgelöste Ausnahmen.
  • Während des Anwendungsstarts ausgelöste Ausnahme.
  • In Hintergrundaufgaben ausgelöste Ausnahme.

Alle Ausnahmen die von der Anwendung verarbeitet werden, müssen weiterhin manuell nachverfolgt werden. Ausnahmefehler, die von Controllern ausgehen, führen normalerweise zu Antwort 500 (Interner Serverfehler). Wenn eine Antwort dieser Art aufgrund einer behandelten Ausnahme (oder keiner Ausnahme) manuell erstellt wird, wird sie in der dazugehörigen Anforderungstelemetrie mit ResultCode 500 nachverfolgt. Mit dem Application Insights SDK kann die entsprechende Ausnahme jedoch nicht nachverfolgt werden.

Unterstützung von früheren Versionen

Wenn Sie Web-API 1 (und früher) des Application Insights Web SDK 2.5 (und früher) verwenden, sind die folgenden Beispiele zum Nachverfolgen von Ausnahmen hilfreich.


Erweitern, um Anweisungen für frühere Versionen anzuzeigen

Web-API 1.x

Überschreiben Sie 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);
    }
    }
}

Sie könnten dieses außer Kraft gesetzte Attribut bestimmten Controllern oder der globalen Filterkonfiguration in der WebApiConfig-Klasse hinzufügen:

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

Beispiel

Web-API 2.x

Fügen Sie eine Implementierung von IExceptionLogger hinzu:

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

Fügen Sie diesen Codeschnipsel den Diensten in WebApiConfig hinzu:

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

Beispiel

Als Alternativen können Sie folgende Aktionen ausführen:

  • Ersetzen Sie die einzige ExceptionHandler-Instanz durch eine benutzerdefinierte Implementierung von IExceptionHandler. Dieser Ausnahmehandler wird nur aufgerufen, wenn das Framework weiterhin wählen kann, welche Antwortnachricht gesendet wird (nicht wenn z. B. die Verbindung abgebrochen wird).
  • Verwenden Sie Ausnahmefilter (wie im obigen Abschnitt zu Web-API 1.x-Controllern beschrieben). Diese werden nicht in allen Fällen aufgerufen.

WCF

Fügen Sie eine Klasse hinzu, die Attribute erweitert sowie IErrorHandler und IServiceBehavior implementiert.

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

Fügen Sie das Attribut den Dienstimplementierungen hinzu:

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

Beispiel

Ausnahmeleistungsindikatoren

Wenn Sie den Azure Monitor Application Insights-Agenten auf Ihrem Server installiert haben, können Sie ein Diagramm mit der von .NET gemessenen Ausnahmenrate abrufen. Dieses enthält sowohl behandelte als auch nicht behandelte .NET-Ausnahmen.

Öffnen Sie eine Registerkarte im Metrik-Explorer, und fügen Sie ein neues Diagramm hinzu. Wählen Sie unter Leistungsindikatoren die Ausnahmerate aus.

.NET Framework berechnet die Rate, indem die Anzahl von Ausnahmen innerhalb eines Intervalls gezählt und durch die Länge des Intervalls geteilt wird.

Diese Anzahl unterscheidet sich von der Anzahl der Ausnahmen, die vom Application Insights-Portal durch Zählen von TrackException-Meldungen berechnet wird. Die Samplingintervalle sind unterschiedlich, und das SDK sendet keine TrackException-Meldungen für alle behandelten und nicht behandelten Ausnahmen.

Benutzerdefinierte Metriksammlung

Die .NET und .NET Core SDKs für Azure Monitor Application Insights bieten zum Sammeln benutzerdefinierter Metriken zwei unterschiedliche Methoden:

  • Die TrackMetric()-Methode ohne Vorabaggregation.
  • Die GetMetric()-Methode mit Vorabaggregation.

Da die Verwendung von Aggregation empfohlen wird, ist TrackMetric() nicht länger die bevorzugte Methode zum Erfassen benutzerdefinierter Metriken. In diesem Artikel erfahren Sie mehr über die Logik der GetMetric()-Methode und ihre Funktionsweise.


Erweitern Sie, um mehr über voraggregierte und nicht voraggregierte APIs zu erfahren.

Die TrackMetric()-Methode sendet rohe Telemetriedaten, die eine Metrik angeben. Es ist ineffizient, für jeden Wert ein einzelnes Telemetrieelement zu senden. Die TrackMetric()-Methode ist auch in Bezug auf die Leistung ineffizient, da jedes TrackMetric(item)-Element die vollständige SDK-Pipeline von Telemetrie-Initialisierern und -Prozessoren durchläuft.

Im Gegensatz zu TrackMetric() übernimmt GetMetric() für Sie die lokale Vorabaggregation und übermittelt dann nur in einem festen Intervall von einer Minute eine aggregierte zusammenfassende Metrik. Wenn Sie eine bestimmte benutzerdefinierte Metrik auf Sekunden- oder sogar Millisekundenebene genau überwachen müssen, können Sie dies tun, während Ihnen nur die Kosten für Speicher und Netzwerkdatenverkehr für eine minütliche Überwachung entstehen. Dieses Verhalten verringert auch das Risiko einer Drosselung erheblich, da die Gesamtzahl der Telemetrieelemente, die für eine aggregierte Metrik gesendet werden müssen, erheblich reduziert wird.

In Application Insights unterliegen benutzerdefinierte Metriken, die über TrackMetric() und GetMetric() erfasst wurden, nicht der Stichprobenentnahme. Die Stichprobenentnahme wichtiger Metriken kann zu Situationen führen, in denen auf diesen Metriken basierende Warnmeldungen unzuverlässig werden. Dadurch, dass Sie keine Stichproben Ihrer benutzerdefinierten Metriken entnehmen, können Sie sich im Allgemeinen darauf verlassen, dass bei Überschreitung Ihrer Warnschwellenwerte eine Warnung ausgelöst wird. Da für benutzerdefinierte Metriken keine Stichproben entnommen werden, gibt es möglicherweise einige Bedenken.

Die Nachverfolgung von Metriktrends im Sekundentakt oder einem noch kleineren Intervall kann zu Folgendem führen:

  • Höhere Datenspeicherkosten. Für die an Azure Monitor gesendete Datenmenge fallen Kosten an. Je mehr Daten Sie senden, desto höher sind die gesamten Überwachungskosten.
  • Es entsteht höherer Aufwand für Netzwerkdatenverkehr oder Leistung. In einigen Szenarien kann dieser Mehraufwand sowohl monetäre Kosten als auch Kosten für die Anwendungsleistung bedeuten.
  • Risiko der Erfassungsdrosselung. Azure Monitor entfernt Datenpunkte (Drosselung), wenn Ihre App in kurzen Abständen eine große Menge an Telemetriedaten sendet.

Die Drosselung ist ein Problem, da sie zu verpassten Warnungen führen kann. Es kann vorkommen, dass die Bedingung zum Auslösen einer Warnung lokal auftritt und dann am Erfassungsendpunkt aufgrund zu vieler gesendeter Daten verloren geht. Aus diesem Grund raten wir dazu, TrackMetric() nur dann für .NET und .NET Core zu verwenden, wenn Sie Ihre eigene lokale Aggregationslogik implementiert haben. Wenn Sie alle Instanzen eines Ereignisses innerhalb einer bestimmten Zeitspanne nachverfolgen möchten, ist TrackEvent() möglicherweise besser geeignet. Beachten Sie, dass benutzerdefinierte Ereignisse im Gegensatz zu benutzerdefinierten Metriken der Stichprobenentnahme unterliegen. Sie können TrackMetric() immer noch verwenden, auch ohne Ihre eigene lokale Voraggregation zu schreiben. Seien Sie sich aber der Fallstricke bewusst, wenn Sie sich dafür entscheiden.

Zusammenfassend ist GetMetric() der empfohlene Ansatz, da er eine Voraggregation durchführt, Werte aus allen Track()-Aufrufen sammelt und einmal pro Minute eine Zusammenfassung/Aggregation sendet. Die GetMetric()-Methode kann den Kosten- und Leistungsaufwand erheblich reduzieren, da weniger Datenpunkte gesendet, aber dennoch alle relevanten Informationen erfasst werden.

Erste Schritte mit GetMetric

Für unsere Beispiele verwenden wir eine einfache .NET Core 3.1-Workerdienstanwendung. Wenn Sie die mit diesen Beispielen verwendete Testumgebung replizieren möchten, führen Sie die Schritte 1 bis 6 unter .NET Core Worker Service-Anwendung aus. Mithilfe dieser Schritte wird Application Insights einer einfachen Workerdienstprojektvorlage hinzugefügt. Die Konzepte gelten für alle allgemeinen Anwendungen, für die das SDK verwendet werden kann, einschließlich Web- und Konsolen-Apps.

Senden von Metriken

Ersetzen Sie den Inhalt der Datei worker.cs durch folgenden Code:

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

Wenn Sie den Beispielcode ausführen, wird die while-Schleife wiederholt ausgeführt, ohne dass Telemetriedaten an das Visual Studio-Ausgabefenster gesendet werden. Nach etwa 60 Sekunden wird ein einzelnes Telemetrieelement gesendet. Das sieht in unserem Test folgendermaßen aus:

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

Dieses einzelne Telemetrieelement stellt ein Aggregat von Messungen 41 verschiedener Metriken dar. Da wir immer wieder denselben Wert senden, haben wir eine Standardabweichung (stDev) von 0 mit identischen Maximal- (max) und Minimalwerten (min). Die Eigenschaft value stellt die Summe aller aggregierten Einzelwerte dar.

Hinweis

Die GetMetric-Methode unterstützt die Nachverfolgung des letzten Werts (z. B gauge) oder die Nachverfolgung von Histogrammen oder Distributionen nicht.

Wenn wir unsere Application Insights-Ressource auf der Oberfläche Protokolle (Analytics) untersuchen, sieht das einzelne Telemetrieelement wie im folgenden Screenshot aus.

Screenshot: Abfrageansicht für „Protokolle (Analytics)“

Hinweis

Da das rohe Telemetrieelement nach der Erfassung weder eine explizite Summeneigenschaft noch ein explizites Summenfeld enthielt, erstellen wir dies für Sie. In diesem Fall stellen die Eigenschaften value und valueSum dasselbe dar.

Sie können auf Ihre benutzerdefinierten Metriktelemetriedaten auch im Abschnitt Metriken des Portals sowohl als protokollbasierte als auch als benutzerdefinierte Metrik zugreifen. Der folgende Screenshot zeigt ein Beispiel einer protokollbasierten Metrik.

Screenshot: Metrik-Explorer-Ansicht

Referenz zur Zwischenspeicherung von Metriken für Nutzung mit hohem Durchsatz

In einigen Fällen werden Metrikwerte möglicherweise in kurzen Abständen beobachtet. Beispielsweise kann für einen Dienst mit hohem Durchsatz, der 500 Anforderungen pro Sekunde verarbeitet, der Wunsch bestehen, für jede Anforderung 20 Telemetriemetriken zu senden. Das bedeutet, dass 10.000 Werte pro Sekunde nachverfolgt werden müssen. In solchen Szenarien mit hohem Durchsatz müssen Benutzende das SDK möglicherweise unterstützen, indem bestimmte Lookups vermieden werden.

Im vorherigen Beispiel wurde beispielsweise ein Lookup nach einem Handle für die Metrik „ComputersSold“ durchgeführt und dann der beobachtete Wert „42“ nachverfolgt. Stattdessen kann der Handle für Aufrufe mehrerer Nachverfolgungen möglicherweise zwischengespeichert werden:

//...

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

Zusätzlich zur Zwischenspeicherung des Metrikhandles reduzierte das vorherige Beispiel auch Task.Delay auf 50 Millisekunden, sodass die Schleife häufiger ausgeführt wurde. Das Ergebnis lautet 772 TrackValue()-Aufrufe.

Mehrdimensionale Metriken

Die Beispiele im vorherigen Abschnitt zeigen Metriken ohne Dimensionen. Metriken können auch mehrdimensional sein. Wir unterstützen derzeit bis zu 10 Dimensionen.

Hier sehen Sie ein Beispiel für das Erstellen einer eindimensionalen Metrik:

//...

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

Das Ausführen des Beispielcodes für mindestens 60 Sekunden führt zu drei verschiedenen Telemetrieelementen, die an Azure gesendet werden. Jedes Element stellt die Aggregation eines der drei Formfaktoren dar. Wie zuvor kann zur weiteren Untersuchung die Ansicht Protokolle (Analytics) verwendet werden.

Screenshot: Ansicht „Protokolle (Analytics)“ für mehrdimensionale Metriken

Im Metrik-Explorer:

Screenshot: Benutzerdefinierte Metriken

Beachten Sie, dass Sie die Metrik nicht nach Ihrer neuen benutzerdefinierten Dimension teilen oder Ihre benutzerdefinierte Dimension mit der Ansicht „Metriken“ anzeigen können.

Screenshot: Nachricht zur Teilungsunterstützung

Standardmäßig sind mehrdimensionale Metriken innerhalb des Metrik-Explorers in Application Insights-Ressourcen nicht aktiviert.

Mehrdimensionale Metriken aktivieren

Um mehrdimensionale Metriken für eine Application Insights-Ressource zu aktivieren, wählen Sie Nutzung und geschätzte Kosten>Benutzerdefinierte Metriken>Dimensionswarnungen für benutzerdefinierte Metriken aktivieren>OK aus. Weitere Informationen finden Sie unter Benutzerdefinierte Metrikdimensionen und Vorabaggregation.

Nachdem Sie diese Änderung vorgenommen und neue mehrdimensionale Telemetriedaten gesendet haben, können Sie Teilung anwenden auswählen.

Hinweis

Nur für neu gesendete Metriken, die nach dem Aktivieren der Funktion im Portal gesendet wurden, werden Dimensionen gespeichert.

Screenshot: Option „Teilung anwenden“

Zeigen Sie Ihre Metrikaggregationen für jede FormFactor-Dimension an.

Screenshot: Formfaktoren

Verwenden von MetricIdentifier, wenn mehr als drei Dimensionen vorhanden sind

Derzeit werden 10 Dimensionen unterstützt. Die Verwendung von mehr als drei Dimensionen erfordert die Verwendung von 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");

Konfiguration benutzerdefinierter Metriken

Wenn Sie die Metrikkonfiguration ändern möchten, müssen Sie Änderungen an der Stelle vornehmen, an der die Metrik initialisiert wird.

Besondere Dimensionsnamen

Metriken verwenden nicht den Telemetriekontext des TelemetryClient, der für den Zugriff auf sie verwendet wird. Diese Einschränkung umgehen Sie am besten durch die Verwendung spezieller Dimensionsnamen, die als Konstanten in der MetricDimensionNames-Klasse verfügbar sind.

Bei Metrikaggregaten, die von der folgenden Special Operation Request Size-Metrik gesendet werden, muss Context.Operation.Name auf Special Operation festgelegt werden. Bei der TrackMetric()- oder jeder anderen TrackXXX()-Methode ist OperationName ordnungsgemäß auf Special Operation festgelegt.

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

Verwenden Sie in diesem Fall die speziellen Dimensionsnamen, die in der MetricDimensionNames-Klasse aufgeführt sind, um die TelemetryContext-Werte anzugeben.

Wenn z. B. das Metrikaggregat, das sich aus der nächsten Anweisung ergibt, an den Cloudendpunkt von Application Insights gesendet wird, wird sein Context.Operation.Name-Datenfeld auf „Special Operation“ festgelegt:

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

Der Wert dieser speziellen Dimension wird in TelemetryContext kopiert und wird nicht als normale Dimension verwendet. Wenn Sie eine Vorgangsdimension auch für die normale Erkundung von Metriken beibehalten möchten, müssen Sie für diesen Zweck eine separate Dimension erstellen:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");
Obergrenzen von Dimensionen und Zeitreihen

Um zu verhindern, dass das Telemetriesubsystem versehentlich Ihre Ressourcen ausschöpft, können Sie die maximale Anzahl von Datenreihen pro Metrik steuern. Die Standardgrenzwerte sind höchstens insgesamt 1.000 Datenreihen pro Metrik und höchstens 100 verschiedene Werte pro Dimension.

Von Bedeutung

Verwenden Sie für Dimensionen niedrige Kardinalwerte, um Drosselungen zu vermeiden.

Im Zusammenhang mit der Obergrenze für Dimensionen und Zeitreihen verwenden wir Metric.TrackValue(..), um sicherzustellen, dass die Grenzwerte eingehalten werden. Wenn die Grenzwerte bereits erreicht sind, gibt Metric.TrackValue(..)False“ zurück, und der Wert wird nicht nachverfolgt. Andernfalls wird Truezurückgegeben. Dieses Verhalten ist nützlich, wenn die Daten für eine Metrik aus Benutzereingaben stammen.

Der Konstruktor MetricConfiguration übernimmt einige Optionen, wie verschiedene Reihen innerhalb der jeweiligen Metrik und ein Objekt einer Klasse zu verwalten sind, die IMetricSeriesConfiguration implementiert, die das Aggregationsverhalten für jede einzelne Reihe der Metrik angibt:

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 does not track the metric, and returns false.
  • seriesCountLimit ist die maximale Anzahl von Datenzeitreihen, die eine Metrik enthalten kann. Wenn dieser Grenzwert erreicht wird, geben Aufrufe von TrackValue(), die normalerweise zu einer neuen Reihe führen würden, „false“ zurück.
  • valuesPerDimensionLimit begrenzt auf ähnliche Weise die Anzahl der verschiedenen Werte pro Dimension.
  • restrictToUInt32Values bestimmt, ob nur nicht negative ganzzahlige Werte nachverfolgt werden sollen oder nicht.

Das folgende Beispiel zeigt, wie Sie eine Nachricht senden, um zu erfahren, ob Obergrenzen überschritten werden:

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

Nachverfolgung benutzerdefinierter Vorgänge

Mit Application Insights SDKs werden eingehende HTTP-Anforderungen und Aufrufe abhängiger Dienste wie HTTP-Anforderungen und SQL-Abfragen automatisch nachverfolgt. Dank der Nachverfolgung und Korrelation von Anforderungen und Abhängigkeiten erhalten Sie Einblicke in die Reaktionsfähigkeit und Zuverlässigkeit der gesamten Anwendung für alle Microservices, die diese Anwendung vereint.

Es gibt eine Klasse von Anwendungsmustern, die nicht generisch unterstützt werden kann. Für die richtige Überwachung dieser Muster ist eine manuelle Codeinstrumentierung erforderlich. In diesem Abschnitt werden einige Muster behandelt, die möglicherweise manuelle Instrumentierung erfordern, z. B. die benutzerdefinierte Warteschlangenverarbeitung und das Ausführen von lang andauernden Hintergrundaufgaben.

Dieser Abschnitt enthält eine Anleitung zum Nachverfolgen von benutzerdefinierten Vorgängen mit dem Application Insights SDK.

Überblick

Ein Vorgang ist ein logisches Stück Arbeit, das von einer Anwendung ausgeführt wird. Er verfügt über Name, Startzeit, Dauer, Ergebnis und Ausführungskontext, z.B. Benutzername, Eigenschaften und Ergebnis. Wenn Vorgang A von Vorgang B initiiert wurde, dann ist Vorgang B ein übergeordneter Vorgang von A. Ein Vorgang kann nur über einen übergeordneten Vorgang verfügen, aber über mehrere untergeordnete Vorgänge. Weitere Informationen zu Vorgängen und zur Telemetriekorrelation finden Sie unter Korrelation der Application Insights-Telemetrie.

Im Application Insights .NET SDK wird ein Vorgang mit der abstrakten OperationTelemetry-Klasse und ihren Nachfolgerelementen RequestTelemetry und DependencyTelemetry beschrieben.

Nachverfolgen von eingehenden Vorgängen

Das Application Insights-Web SDK sammelt automatisch HTTP-Anforderungen für ASP.NET-Anwendungen, die in einer IIS-Pipeline und allen ASP.NET Core-Anwendungen ausgeführt werden. Es sind auch Lösungen mit Community-Support für andere Plattformen und Frameworks vorhanden. Falls die Anwendung von keiner Standardlösung oder Lösung mit Community-Support unterstützt wird, können Sie sie manuell instrumentieren.

Ein weiteres Beispiel, für das die benutzerdefinierte Nachverfolgung erforderlich ist, ist der Worker, der Elemente aus der Warteschlange erhält. Für einige Warteschlangen wird der Aufruf zum Hinzufügen einer Nachricht zur Warteschlange als Abhängigkeit nachverfolgt. Der allgemeine Vorgang, der die Nachrichtenverarbeitung beschreibt, wird nicht automatisch erfasst.

Wir sehen uns nun an, wie Vorgänge dieser Art nachverfolgt werden können.

Auf allgemeiner Ebene besteht die Aufgabe darin, RequestTelemetry zu erstellen und bekannte Eigenschaften festzulegen. Nachdem der Vorgang abgeschlossen ist, wird die Telemetrie nachverfolgt. Das folgende Beispiel veranschaulicht diese Aufgabe.

HTTP-Anforderung in selbstgehosteter Owin-App

In diesem Beispiel wird der Kontext der Ablaufverfolgung gemäß dem HTTP-Protokoll für die Korrelation verteilt. Sie sollten davon ausgehen, die hier beschriebenen Header zu erhalten.


Erweitern Sie, um Code anzuzeigen
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);
    }
}

Das HTTP-Protokoll für die Korrelation deklariert außerdem den Correlation-Context-Header. Er wird hier zur Vereinfachung weggelassen.

Warteschlangeninstrumentierung

Der W3C Trace Context und ein HTTP-Protokoll für die Korrelation übergeben Korrelationsdetails mit HTTP-Anforderungen, aber für jedes Warteschlangenprotokoll muss definiert werden, wie die gleichen Details für die Warteschlangennachricht übergeben werden. Einige Warteschlangenprotokolle, z. B. AMQP, ermöglichen das Übergeben weiterer Metadaten. Andere Protokolle, z. B. die Azure Storage-Warteschlange, setzen voraus, dass der Kontext in der Nachrichtennutzlast codiert wird.

Hinweis

Die komponentenübergreifende Ablaufverfolgung wird für Warteschlangen noch nicht unterstützt.

Wenn mit HTTP Ihr Producer und Consumer Telemetriedaten an verschiedene Application Insights-Ressourcen senden, zeigen die Oberfläche zur Transaktionsdiagnose und die Anwendungsübersicht Transaktionen und Übersicht End-to-End an. Für Warteschlangen wird diese Funktion noch nicht unterstützt.

Service Bus-Warteschlange

Informationen zur Ablaufverfolgung finden Sie unter Verteilte Ablaufverfolgung und Korrelation über Service Bus-Messaging.

Azure Storage-Warteschlange

Im folgenden Beispiel wird veranschaulicht, wie Sie Vorgänge der Azure Storage-Warteschlange nachverfolgen und die Telemetrie zwischen Producer, Consumer und Azure Storage korrelieren.

Die Storage-Warteschlange verfügt über eine HTTP-API. Alle Aufrufe der Warteschlange werden von der Application Insights-Abhängigkeitserfassung für HTTP-Anforderungen nachverfolgt. Sie ist standardmäßig für ASP.NET- und ASP.NET Core-Anwendungen konfiguriert. Weitere Arten von Anwendungen finden Sie in der Dokumentation zu Konsolenanwendungen.

Zudem sollten Sie die Vorgangs-ID von Application Insights mit der Anforderungs-ID von Storage korrelieren. Informationen zum Festlegen und Abrufen eines Storage-Anforderungsclients und einer Serveranforderungs-ID erhalten Sie unter Überwachung, Diagnose und Problembehandlung in Azure Storage.

Da Storage-Warteschlangen die HTTP-API unterstützen, werden alle Vorgänge der Warteschlange von Application Insights automatisch nachverfolgt. In vielen Fällen sollte diese Instrumentierung ausreichend sein. Zum Korrelieren von Ablaufverfolgungen auf Consumerseite mit Ablaufverfolgungen für Producer müssen Sie auf ähnliche Weise Korrelationskontext übergeben, wie wir dies für das HTTP-Protokoll für die Korrelation getan haben.

In diesem Beispiel wird gezeigt, wie Sie den Enqueue-Vorgang nachverfolgen. Sie haben folgende Möglichkeiten:

  • Korrelieren von erneuten Versuchen (falls vorhanden): Alle davon verfügen über ein gemeinsames übergeordnetes Element, und zwar den Enqueue-Vorgang. Andernfalls werden sie als untergeordnete Elemente der eingehenden Anforderung nachverfolgt. Wenn also mehrere logische Anforderungen für die Warteschlange vorhanden sind, lässt sich unter Umständen nur schwer ermitteln, welcher Aufruf zu den erneuten Versuchen geführt hat.
  • Korrelieren von Storage-Protokollen (falls erforderlich): Diese werden mit Application Insights-Telemetrie korreliert.

Der Enqueue-Vorgang ist das untergeordnete Element eines übergeordneten Vorgangs. Ein Beispiel ist eine eingehende HTTP-Anforderung. Der HTTP-Abhängigkeitsaufruf ist dem Enqueue-Vorgang untergeordnet und der eingehenden Anforderung auf zweiter Ebene untergeordnet.

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

Wenn Sie die Menge an Telemetriedaten, die von Ihrer Anwendung gemeldet werden, reduzieren oder den Enqueue-Vorgang aus anderen Gründen nachverfolgen möchten, können Sie die Activity-API direkt verwenden:

  • Erstellen (und starten) Sie eine neue Activity, anstatt den Application Insights-Vorgang zu starten. Sie müssen ihm keine Eigenschaften zuweisen, mit Ausnahme des Vorgangsnamens.
  • Serialisieren Sie yourActivity.Id anstelle von operation.Telemetry.Id für die Nachrichtennutzlast. Sie können auch Activity.Current.Id verwenden.

Auch andere Warteschlangenvorgänge können so instrumentiert werden. Ein Peekvorgang sollte ähnlich wie ein Vorgang zur Entfernung aus der Warteschlange instrumentiert werden. Das Instrumentieren von Vorgängen der Warteschlangenverwaltung ist nicht erforderlich. Mit Application Insights werden Vorgänge wie HTTP-Vorgänge nachverfolgt, und in den meisten Fällen ist dies ausreichend.

Stellen Sie beim Instrumentieren der Nachrichtenlöschung sicher, dass Sie die Vorgangsbezeichner (für die Korrelation) festlegen. Alternativ können Sie auch die Activity-API verwenden. Das Festlegen von Vorgangsbezeichnern für die Telemetrieelemente ist dann nicht erforderlich, da das Application Insights SDK diese Aufgabe für Sie übernimmt:

  • Erstellen Sie nach Erhalt eines Elements aus der Warteschlange eine neue Activity.
  • Verwenden Sie Activity.SetParentId(message.ParentId) zum Korrelieren von Consumer- und Producerprotokollen.
  • Starten Sie die Activity.
  • Verfolgen Sie Vorgänge zum Entfernen aus der Warteschlange, Verarbeiten und Löschen nach, indem Sie Start/StopOperation-Hilfsprogramme verwenden. Führen Sie dies über die gleiche asynchrone Ablaufsteuerung (Ausführungskontext) durch. Auf diese Weise werden sie richtig korreliert.
  • Beenden Sie die Activity.
  • Verwenden Sie Start/StopOperation, oder rufen Sie Track der Telemetrie manuell auf.
Abhängigkeitstypen

Application Insights verwendet Abhängigkeitstypen, um Benutzeroberflächen anzupassen. Für Warteschlangen werden folgende Typen von DependencyTelemetry erkannt, die die Oberfläche zur Transaktionsdiagnose verbessern:

  • Azure queue für Azure Storage-Warteschlangen
  • Azure Event Hubs für Azure Event Hubs
  • Azure Service Bus für Azure Service Bus
Batchverarbeitung

Bei einigen Warteschlangen können Sie mehrere Nachrichten mit einer Anforderung aus der Warteschlange entfernen. Die Verarbeitung solcher Nachrichten ist vermutlich unabhängig und gehört zu den verschiedenen logischen Vorgängen. Es ist nicht möglich, den Dequeue-Vorgang mit einer bestimmten Nachricht zu korrelieren, die verarbeitet wird.

Jede Nachricht sollte in einer eigenen asynchronen Ablaufsteuerung verarbeitet werden. Weitere Informationen erhalten Sie im Abschnitt Nachverfolgung von ausgehenden Abhängigkeiten.

Hintergrundaufgaben mit langer Ausführungsdauer

Einige Anwendungen starten einen Vorgang mit langer Ausführungsdauer, der unter Umständen durch Benutzeranforderungen verursacht wird. Aus Sicht der Nachverfolgung bzw. Instrumentierung unterscheidet sich dies nicht von der Instrumentierung von Anforderungen oder Abhängigkeiten:

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

In diesem Beispiel wird mit telemetryClient.StartOperation das Element DependencyTelemetry erstellt und der Korrelationskontext eingefügt. Angenommen, Sie verfügen über einen übergeordneten Vorgang, der von eingehenden Anforderungen für die Planung des Vorgangs erstellt wurde. Sofern BackgroundTask in derselben asynchronen Ablaufsteuerung wie eine eingehende Anforderung gestartet wird, wird die Korrelation mit diesem übergeordneten Vorgang durchgeführt. BackgroundTask und alle geschachtelten Telemetrieelemente werden automatisch mit der Anforderung korreliert, die der Auslöser war. Dies gilt auch nach Abschluss der Anforderung.

Wenn der Task über den Hintergrundthread gestartet wird, dem kein Vorgang (Activity) zugeordnet ist, weist BackgroundTask kein übergeordnetes Element auf. Geschachtelte Vorgänge können jedoch vorhanden sein. Alle Telemetrieelemente, die von dem Task gemeldet werden, werden mit dem in DependencyTelemetry erstellten BackgroundTask-Element korreliert.

Nachverfolgung von ausgehenden Abhängigkeiten

Sie können Ihre eigene Art von Abhängigkeit oder einen Vorgang nachverfolgen, der nicht von Application Insights unterstützt wird.

Die Enqueue-Methode in der Service Bus-Warteschlange oder Storage-Warteschlange kann als Beispiel für diese benutzerdefinierte Nachverfolgung dienen.

Der allgemeine Ansatz für die benutzerdefinierte Nachverfolgung von Abhängigkeiten lautet wie folgt:

  • Rufen Sie die TelemetryClient.StartOperation-Methode (Erweiterungsmethode) auf, mit der die für die Korrelation erforderlichen DependencyTelemetry-Eigenschaften und einige andere Eigenschaften wie Start, Zeitstempel und Dauer aufgefüllt werden.
  • Legen Sie weitere benutzerdefinierte Eigenschaften wie den Namen und anderen benötigten Kontext für DependencyTelemetry fest.
  • Rufen Sie eine Abhängigkeit auf und warten Sie darauf.
  • Beenden Sie den Vorgang mit StopOperation, wenn er abgeschlossen wurde.
  • Behandeln Sie Ausnahmen.
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.
        }
    }
}

Das Beenden eines Vorgangs führt dazu, dass der Vorgang gestoppt wird, sodass Sie dies tun können, anstatt den Befehl StopOperation aufzurufen.

Warnung

In einigen Fällen kann eine nicht behandelte Ausnahme verhindern, dass finally aufgerufen wird, sodass Vorgänge möglicherweise nicht nachverfolgt werden.

Verarbeitung und Nachverfolgung von parallelen Vorgängen

Das Aufrufen von StopOperation beendet nur den Vorgang, der gestartet wurde. Wenn der aktuell ausgeführte Vorgang nicht mit dem zu stoppenden übereinstimmt, wird von StopOperation keine Aktion ausgeführt. Dies kann der Fall sein, wenn Sie mehrere Vorgänge parallel in demselben Ausführungskontext starten.

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;

Stellen Sie sicher, dass Sie immer StartOperation aufrufen und den Vorgang in derselben async-Methode verarbeiten, um parallel ausgeführte Vorgänge zu isolieren. Wenn der Vorgang synchron (bzw. nicht asynchron) ist, können Sie den Vorgang per Wrapper umschließen und mit Task.Run nachverfolgen.

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

Application Insights-Vorgänge im Vergleich zu System.Diagnostics.Activity

System.Diagnostics.Activity stellt den verteilten Ablaufverfolgungskontext dar und wird von Frameworks und Bibliotheken verwendet, um Kontext zu erstellen sowie innerhalb und außerhalb des Prozesses weiterzugeben und um Telemetrieelemente zu korrelieren. Activity arbeitet mit System.Diagnostics.DiagnosticSource zusammen, dem Benachrichtigungsmechanismus des Frameworks bzw. der Bibliothek zum Benachrichtigen bei interessanten Ereignissen wie eingehenden oder ausgehenden Anforderungen und Ausnahmen.

Aktivitäten sind Features der obersten Ebene in Application Insights. Automatische Abhängigkeit und Anforderungssammlung basieren zusammen mit DiagnosticSource-Ereignissen stark auf ihnen. Wenn Sie eine Activity in Ihrer Anwendung erstellen, führt dies nicht zur Erstellung von Application Insights-Telemetrie. Application Insights muss DiagnosticSource-Ereignisse empfangen und die Namen und Nutzlasten der Ereignisse kennen, um eine Activity in Telemetrie zu übersetzen.

Jeder Application Insights-Vorgang (Anforderung oder Abhängigkeit) umfasst Activity. Wenn StartOperation aufgerufen wird, wird Activity darunter erstellt. StartOperation ist die empfohlene Methode, um Anforderungs- oder Abhängigkeitstelemetrien manuell nachzuverfolgen und sicherzustellen, dass alle Elemente korreliert sind.

Zähler in Application Insights

Application Insights unterstützt Leistungsindikatoren und Ereigniszähler. Dieses Handbuch bietet eine Übersicht über beides, einschließlich Zweck, Konfiguration und Verwendung in .NET-Anwendungen.

Überblick

  • Leistungsindikatoren sind in das Windows-Betriebssystem integriert und bieten vordefinierte Metriken wie CPU-Auslastung, Arbeitsspeicherverbrauch und Datenträgeraktivität. Diese Leistungsindikatoren eignen sich ideal für die Überwachung von Standardleistungsmetriken mit minimalem Setup. Sie erleichtern das Nachverfolgen der Ressourcenauslastung oder die Problembehandlung von Engpässen auf Systemebene in Windows-basierten Anwendungen, unterstützen jedoch keine benutzerdefinierten anwendungsspezifischen Metriken.

  • Ereigniszähler funktionieren auf mehreren Plattformen, einschließlich Windows, Linux und macOS. Sie ermöglichen es Fachkräften in der Entwicklung, einfache, anpassbare anwendungsspezifische Metriken, die mehr Flexibilität als Leistungsindikatoren bieten, zu definieren und zu überwachen. Ereignisindikatoren sind nützlich, wenn Systemmetriken unzureichend sind oder detaillierte Telemetriedaten in plattformübergreifenden Anwendungen benötigt werden. Sie erfordern eine explizite Implementierung und Konfiguration, wodurch das Setup auswändiger ist.

Leistungsindikatoren

Windows bietet eine Vielzahl von Leistungsindikatoren, wie z. B. diejenigen zum Erfassen von Statistiken zur Prozessor-, Arbeitsspeicher- und Datenträgerauslastung. Sie können auch eigene Leistungsindikatoren definieren.

Ihre Anwendung unterstützt die Leistungsindikatorsammlung, wenn sie unter Internetinformationsserver (IIS) auf einem lokalen Host oder einem virtuellen Computer mit Administratorzugriff ausgeführt wird. Anwendungen, die als Azure Web Apps ausgeführt werden, können nicht direkt auf Leistungsindikatoren zugreifen, aber ein Teil der verfügbaren Leistungsindikatoren wird von Application Insights erfasst.

Tipp

Wie andere Metriken können Sie eine Warnung festlegen, um zu warnen, wenn ein Zähler außerhalb eines angegebenen Grenzwerts liegt. Um eine Warnung festzulegen, öffnen Sie den Bereich Warnungen und wählen Warnung hinzufügen aus.

Voraussetzungen

Erteilen Sie dem App-Pooldienstkonto die Berechtigung zum Überwachen von Leistungsindikatoren, indem Sie es der Gruppe Leistungsmonitorbenutzer hinzufügen.

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

Anzeigen von Indikatoren

Im Bereich Metriken wird die Standardmenge von Leistungsindikatoren angezeigt.

Standardleistungsindikatoren für ASP.NET-Webanwendungen:

  • % Prozess\Prozessorzeit
  • % Prozess\Prozessorzeit normalisiert
  • Arbeitsspeicher\Verfügbare Bytes
  • ASP.NET Anforderungen/Sek.
  • .NET Common Language Runtime (CLR) Ausnahmen ausgelöst/ Sek.
  • Ausführungszeit von ASP.NET-Anfragen
  • Prozess\Private Bytes
  • Prozess\E/A-Datenbytes/s
  • ASP.NET Anwendungen\Anforderungen in der Anwendungswarteschlange
  • Processor(_Total)\% Prozessorzeit

Hinzufügen von Leistungsindikatoren

Wenn der gewünschte Leistungsindikator nicht in der Liste der Metriken enthalten ist, können Sie ihn hinzufügen.

Option 1: Konfiguration in ApplicationInsights.config

  1. Welche Leistungsindikatoren in Ihrem Server verfügbar sind, können Sie ermitteln, indem Sie diesen PowerShell-Befehl auf dem lokalen Server verwenden:

    Get-Counter -ListSet *
    

    Weitere Informationen finden Sie unter Get-Counter.

  2. Öffnen Sie ApplicationInsights.config.

    Wenn Sie Application Insights während der Entwicklung Ihrer App hinzugefügt haben, gehen Sie folgendermaßen vor:

    1. Bearbeiten Sie ApplicationInsights.config in Ihrem Projekt.
    2. Stellen Sie es erneut auf Ihren Servern bereit.
  3. Bearbeiten Sie Leistungserfassungsanweisung:

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

Sie erfassen sowohl Standardindikatoren und -zähler als auch Indikatoren, die Sie selbst implementieren. \Objects\Processes ist ein Beispiel für einen Standardindikator, der auf allen Windows-Systemen verfügbar ist. \Sales(photo)\# Items Sold ist ein Beispiel für einen benutzerdefinierten Indikator, der in einem Webdienst implementiert sein kann.

Das Format lautet \Category(instance)\Counter bzw. für Kategorien, die keine Instanzen besitzen, einfach \Category\Counter.

Der Parameter ReportAs ist für Leistungsindikatornamen erforderlich, die nicht mit [a-zA-Z()/-_ \.]+ übereinstimmen,

Wenn Sie eine Instanz angeben, wird sie zu einer Dimension CounterInstanceName der gemeldeten Metrik.

Option 2: Konfiguration im Code

Informationen hierzu finden Sie im nächsten Abschnitt.

Erfassen von Leistungsindikatoren im Code für ASP.NET-Webanwendungen oder .NET/.NET Core-Konsolenanwendungen

Um Systemleistungsindikatoren zu erfassen und an Application Insights zu senden, können Sie den folgenden Codeschnipsel anpassen:

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

Alternativ können Sie dieselben Schritte mit von Ihnen erstellten benutzerdefinierten Metriken ausführen:

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

Leistungsindikatoren für Anwendungen, die in Azure-Web-Apps ausgeführt werden sowie für Windows-Container in Azure App Service

Sowohl ASP.NET- als auch ASP.NET Core-Anwendungen, die in Azure-Web-Apps bereitgestellt werden, werden in einer speziellen Sandkastenumgebung ausgeführt. Anwendungen, die in Azure App Service bereitgestellt werden, können einen Windows-Container verwenden oder in einer Sandboxumgebung gehostet werden. Wenn die Anwendung in einem Windows-Container bereitgestellt wird, sind alle Standardleistungsindikatoren im Containerimage verfügbar.

In der Sandboxumgebung ist der direkte Zugriff auf Systemleistungsindikatoren nicht möglich. Eine begrenzte Teilmenge von Indikatoren wird jedoch, wie unter Perf Counters exposed as environment variables beschrieben, als Umgebungsvariablen verfügbar gemacht. In dieser Umgebung ist nur eine Teilmenge der Indikatoren verfügbar. Die vollständige Liste finden Sie unter Perf Counters exposed as environment variables.

Das Application Insights SDK für ASP.NET und ASP.NET Core erkennt, ob Code in einer Web-App oder einem Nicht-Windows-Container bereitgestellt wurde. Während dieser Erkennung bestimmt das SDK, ob Leistungsindikatoren in einer Sandboxumgebung erfasst werden sollen oder ob der Standarderfassungsmechanismus beim Hosten in einem Windows-Container oder auf einer Windows-VM genutzt werden soll.

Log Analytics-Abfragen für Leistungsindikatoren

In Log Analytics können Sie nach Leistungsindikatorberichten suchen und diese anzeigen.

Das Schema performanceCounters zeigt die category, den counter-Namen und instance-Namen der einzelnen Leistungsindikatoren. In den Telemetriedaten jeder Anwendung werden nur die Indikatoren für die betreffende Anwendung angezeigt. Beispielsweise, um verfügbare Leistungsindikatoren anzuzeigen:

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

Hier bezieht sich Instance auf die Instanz des Leistungsindikators, nicht auf die Rolle oder die Servercomputerinstanz. Leistungsindikatoren wie z. B. Prozessorzeit werden vom Namen der Leistungsindikatorinstanz in der Regel nach dem Namen des Prozesses oder der Anwendung segmentiert.

So erhalten Sie ein Diagramm des verfügbaren Arbeitsspeichers im aktuellen Zeitraum:

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

Wie andere Telemetriedaten umfasst auch performanceCounters eine Spalte cloud_RoleInstance, die die Identität der Hostserverinstanz angibt, auf dem Ihre Anwendung ausgeführt wird. Geben Sie beispielsweise Folgendes ein, um die Leistung Ihrer App auf verschiedenen Computern vergleichen:

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

Häufig gestellte Fragen zu Leistungsindikatoren

Häufig gestellte Fragen (FAQ) finden Sie unter Häufig gestellte Fragen zu Leistungsindikatoren.

Ereignisindikatoren

EventCounter ist ein .NET/.NET Core-Mechanismus zum Veröffentlichen und Verwenden von Indikatoren oder Statistiken. EventCounters werden auf allen Betriebssystemplattformen unterstützt: Windows, Linux und macOS. Sie kann als plattformübergreifende Entsprechung für performanceCounters betrachtet werden, die nur in Windows-Systemen unterstützt wird.

Während Benutzer beliebige benutzerdefinierte Ereigniszähler veröffentlichen können, um ihre Anforderungen zu erfüllen, veröffentlicht .NET standardmäßig einen Satz dieser Indikatoren. Dieses Dokument führt Sie durch die erforderlichen Schritte zum Erfassen und Anzeigen von Ereigniszählern (systemdefiniert oder benutzerdefiniert) in Azure Application Insights.

Tipp

Wie andere Metriken können Sie eine Warnung festlegen, um zu warnen, wenn ein Zähler außerhalb eines angegebenen Grenzwerts liegt. Um eine Warnung festzulegen, öffnen Sie den Bereich Warnungen und wählen Warnung hinzufügen aus.

Verwenden von Application Insights für das Erfassen von EventCounters

Application Insights unterstützt das Erfassen von EventCounters mit EventCounterCollectionModule, einem Bestandteil des neu veröffentlichten NuGet-Pakets Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule wird bei Verwendung von AspNetCore oder WorkerService automatisch aktiviert. EventCounterCollectionModule erfasst Zähler mit einer nicht konfigurierbaren Erfassungshäufigkeit von 60 Sekunden. Zum Erfassen von EventCounters sind keine speziellen Berechtigungen erforderlich. Für ASP.NET Core-Anwendungen möchten Sie auch das Paket Microsoft.ApplicationInsights.AspNetCore hinzufügen.

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

Erfasste Standardindikatoren

Ab Version 2.15.0 von entweder AspNetCore SDK oder WorkerService SDK werden standardmäßig keine Indikatoren erfasst. Das Modul selbst wird aktiviert, damit Benutzer die gewünschten Zähler hinzufügen können, um sie zu erfassen.

Eine Liste bekannter Indikatoren, die von der .NET-Runtime veröffentlicht werden, finden Sie im Dokument Verfügbare Leistungsindikatoren.

Anpassen zu erfassender Indikatoren

Das folgende Beispiel veranschaulicht das Hinzufügen und Entfernen von Indikatoren. Diese Anpassung erfolgt als Teil Ihrer Anwendungsdienstkonfiguration, nachdem die Erfassung von Telemetriedaten durch Application Insights entweder mit AddApplicationInsightsTelemetry() oder AddApplicationInsightsWorkerService() aktiviert wurde. Nachfolgend sehen Sie einen Beispielcode aus einer ASP.NET Core-Anwendung. Informationen zu anderen Anwendungstypen finden Sie unter "Konfigurieren von Telemetriemodulen".

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

Deaktivieren des Sammlungsmoduls EventCounter

EventCounterCollectionModule kann mithilfe von ApplicationInsightsServiceOptions deaktiviert werden.

Im folgenden Beispiel wird das ASP.NET Core-SDK verwendet.

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

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

Ein ähnlicher Ansatz kann auch für das Worker Service SDK verwendet werden, aber der Namespace muss geändert werden, wie im folgenden Beispiel gezeigt.

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

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

Log Analytics-Abfragen für Ereigniszähler

Sie können Ereigniszählerberichte in Log Analytics in der Tabelle customMetrics suchen und anzeigen.

Führen Sie z.B. die folgende Abfrage aus, um zu sehen, welche Indikatoren erfasst werden und für die Abfrage verfügbar sind:

customMetrics | summarize avg(value) by name

Um ein Diagramm eines bestimmten Indikators (z.B. ThreadPool Completed Work Item Count) im aktuellen Zeitraum zu erhalten, führen Sie die folgende Abfrage aus.

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

Wie für andere Telemetriedaten ist auch in der Tabelle customMetrics eine cloud_RoleInstance-Spalte enthalten, die die Identität der Hostserverinstanz angibt, auf dem Ihre Anwendung ausgeführt wird. Die vorstehende Abfrage zeigt den Indikatorwert pro Instanz und kann zum Vergleichen der Leistung verschiedener Serverinstanzen verwendet werden.

Häufig gestellte Fragen zu Ereigniszählern

Häufig gestellte Fragen (FAQ) finden Sie unter Häufig gestellte Fragen zu Ereigniszählern.

Filtern und Anreichern von Telemetrie

In diesem Abschnitt

Filtern und Vorverarbeitung der Telemetrie

Sie können Code schreiben, um Ihre Telemetrie zu filtern, zu ändern oder zu erweitern, bevor sie aus dem SDK gesendet wird. Die Verarbeitung umfasst Daten, die von den Standard-Telemetriemodulen gesendet werden, z. B. HTTP-Anforderungssammlung und Abhängigkeitssammlung.

  • Die Filterung kann Telemetriedaten ändern oder verwerfen, bevor sie vom SDK gesendet werden, indem die Implementierung von ITelemetryProcessor erfolgt. So könnten Sie beispielsweise das Telemetrievolumen reduzieren, indem Sie Anfragen von Robotern ausschließen. Im Gegensatz zum Sampling haben Sie die vollständige Kontrolle darüber, was gesendet oder verworfen wird, es wirkt sich jedoch auf Metriken aus, die auf aggregierten Protokollen basieren. Je nachdem, wie Sie Elemente verwerfen, verlieren Sie möglicherweise auch die Möglichkeit, zwischen verwandten Elementen zu navigieren.

  • Fügen Sie Eigenschaften zu allen Telemetriedaten hinzu, die von Ihrer App gesendet werden, oder ändern Sie diese, indem Sie eine ITelemetryInitializer. Sie können beispielsweise berechnete Werte oder Versionsnummern hinzufügen, nach denen die Daten im Portal gefiltert werden sollen.

  • Das Sampling reduziert die Telemetriemenge, ohne dass sich dies auf Ihre Statistiken auswirkt. Es hält verwandte Datenpunkte zusammen, sodass Sie zwischen ihnen navigieren können, wenn Sie ein Problem diagnostizieren. Im Portal wird die Gesamtanzahl multipliziert, um eine Kompensation der Stichproben zu erreichen.

Hinweis

Die SDK-API wird verwendet, um benutzerdefinierte Ereignisse und Metriken zu senden.

Filterung

Mit dieser Technik können Sie direkt steuern, was im Telemetriedatenstrom enthalten oder ausgeschlossen ist. Das Filtern kann verwendet werden, um Telemetrieelemente herauszufiltern, die an Application Insights gesendet werden. Sie können die Filterung mit Sampling oder separat verwenden.

Zum Filtern der Telemetrie schreiben Sie einen Telemetrieprozessor und registrieren ihn bei TelemetryConfiguration. Alle Telemetriedaten durchlaufen Ihren Prozessor. Sie können es aus dem Datenstrom ablegen oder dem nächsten Prozessor in der Kette zugeben. Telemetrie aus den Standardmodulen, wie dem HTTP-Anforderungssammler und dem Abhängigkeitssammler, sowie die von Ihnen selbst nachverfolgte Telemetrie ist enthalten. Sie können z. B. Telemetriedaten zu Anforderungen von Robots oder erfolgreiche Abhängigkeitsaufrufe herausfiltern.

Warnung

Durch das Filtern der Telemetrie, die vom SDK gesendet wird, mithilfe von Prozessoren können Sie die im Portal angezeigten Statistiken verzerren und es schwierig machen, verwandte Elemente zu verfolgen.

Erwägen Sie stattdessen die Verwendung von Sampling.

ITelemetryProcessor und ITelemetryInitializer

Was ist der Unterschied zwischen Telemetrieprozessoren und Telemetrieinitialisierern?

  • Es gibt einige Überschneidungen in dem, was Sie damit tun können. Beide können verwendet werden, um Eigenschaften der Telemetrie hinzuzufügen oder zu ändern, obwohl wir empfehlen, Initialisierer für diesen Zweck zu verwenden.
  • Telemetrieinitialisierer werden immer vor Telemetrieprozessoren ausgeführt.
  • Telemetrieinitialisierer können mehrmals aufgerufen werden. Standardmäßig legen sie keine Eigenschaft fest, die bereits festgelegt wurde.
  • Telemetrieprozessoren ermöglichen es Ihnen, ein Telemetrieelement vollständig zu ersetzen oder zu verwerfen.
  • Alle registrierten Telemetrieinitialisierer werden für jedes Telemetrieelement aufgerufen. Für Telemetrieprozessoren garantiert das SDK das Aufrufen des ersten Telemetrieprozessors. Ob der Rest der Prozessoren aufgerufen wird oder nicht, wird durch die vorherigen Telemetrieprozessoren entschieden.
  • Verwenden Sie Telemetrieinitialisierer, um Telemetrie mit mehr Eigenschaften zu erweitern oder eine vorhandene zu überschreiben. Verwenden Sie einen Telemetrieprozessor, um Telemetrie auszufiltern.

Hinzufügen/Ändern von Eigenschaften

Verwenden Sie Telemetrieinitialisierer, um Telemetrie mit zusätzlichen Informationen zu erweitern oder Telemetrieeigenschaften außer Kraft zu setzen, die von den Standardmäßigen Telemetriemodulen festgelegt wurden.

Beispielsweise sammelt Application Insights für ein Webpaket Telemetriedaten zu HTTP-Anforderungen. Standardmäßig wird jede Anforderung mit einem Antwortcode >=400 als fehlgeschlagen gekennzeichnet. Wenn Sie stattdessen 400 als Erfolg behandeln möchten, können Sie einen Telemetrieinitialisierer bereitstellen, der die Erfolgseigenschaft festlegt.

Wenn Sie einen Telemetrieinitialisierer bereitstellen, wird er immer aufgerufen, wenn eine der Track*()-Methoden aufgerufen wird. Dieser Initialisierer enthält Track() Methoden, die von den Standard-Telemetriemodulen aufgerufen werden. In der Konvention legen diese Module keine Eigenschaft fest, die bereits von einem Initialisierer festgelegt wurde. Telemetrieinitialisierer werden vor dem Aufrufen von Telemetrieprozessoren aufgerufen, sodass alle Von Initialisierern vorgenommenen Anreicherungen für Prozessoren sichtbar sind.

Telemetrieinitialisierer

Verwenden Sie Telemetrieinitialisierer, um Telemetrie mit zusätzlichen Informationen zu erweitern oder Telemetrieeigenschaften zu überschreiben, die von den Standard-Telemetriemodulen festgelegt wurden.

Mit Telemetrieinitialisierern werden Kontexteigenschaften festgelegt, die mit jedem Element der Telemetrie gesendet werden. Sie können eigene Initialisierer schreiben, um Kontexteigenschaften festzulegen.

Die standardmäßigen Initialisierer werden entweder von den Web- oder WindowsServer-NuGet-Paketen festgelegt:

Initialisierer Description
AccountIdTelemetryInitializer Legt die AccountId-Eigenschaft fest.
AuthenticatedUserIdTelemetryInitializer Legt die Eigenschaft AuthenticatedUserId so fest, wie sie vom JavaScript-SDK festgelegt wurde.
AzureRoleEnvironmentTelemetryInitializer Aktualisiert die Eigenschaften RoleName und RoleInstance des Kontexts Device für alle Telemetrieelemente mit Informationen, die aus der Azure-Laufzeitumgebung extrahiert wurden.
BuildInfoConfigComponentVersionTelemetryInitializer Aktualisiert die Eigenschaft Version des Kontexts Component für alle Telemetrieelemente mit dem Wert, der aus der von MS Build erzeugten Datei BuildInfo.config extrahiert wurde.
ClientIpHeaderTelemetryInitializer Aktualisiert die Eigenschaft Ip des Kontexts Location aller Telemetrieelemente basierend auf dem HTTP-Header X-Forwarded-For der Anforderung.
DeviceTelemetryInitializer Aktualisiert die folgenden Eigenschaften des Kontexts Device für alle Telemetrieelemente:

Type ist auf PC festgelegt.
Id ist auf den Domänennamen des Computers festgelegt, auf dem die Webanwendung ausgeführt wird.
OemName ist auf den Wert festgelegt, der mithilfe von WMI aus dem Feld Win32_ComputerSystem.Manufacturer extrahiert wurde.
Model ist auf den Wert festgelegt, der mithilfe von WMI aus dem Feld Win32_ComputerSystem.Model extrahiert wurde.
NetworkType ist auf den Wert festgelegt, der aus der Eigenschaft NetworkInterface extrahiert wurde.
Language ist auf den Namen der Eigenschaft CurrentCulture festgelegt.
DomainNameRoleInstanceTelemetryInitializer Aktualisiert die Eigenschaft RoleInstance des Kontexts Device für alle Telemetrieelemente mit dem Domänennamen des Computers, auf dem die Webanwendung ausgeführt wird.
OperationNameTelemetryInitializer Aktualisiert die Eigenschaft Name von RequestTelemetry und die Eigenschaft Name des Kontexts Operation aller Telemetrieelemente basierend auf der HTTP-Methode sowie die Namen des ASP.NET-MVC-Controller und der Aktion, die aufgerufen werden, um die Anforderung zu verarbeiten.
OperationIdTelemetryInitializer oder OperationCorrelationTelemetryInitializer Aktualisiert die Kontexteigenschaft Operation.Id aller Telemetrieelemente, die beim Behandeln einer Anforderung mit dem automatisch generierten RequestTelemetry.Id nachverfolgt werden.
SessionTelemetryInitializer Aktualisiert die Eigenschaft Id des Kontexts Session für alle Telemetrieelemente mit Werten, die aus dem Cookie ai_session extrahiert werden. Dieses wird vom ApplicationInsights-JavaScript-Instrumentationscode generiert, der im Browser des Benutzers ausgeführt wird.
SyntheticTelemetryInitializer oder SyntheticUserAgentTelemetryInitializer Aktualisiert die Kontexteigenschaften User, Sessionund Operation aller Telemetrieelemente, die beim Behandeln einer Anforderung von einer synthetischen Quelle (beispielsweise ein Verfügbarkeitstest oder Suchmaschinen-Bot) nachverfolgt werden. Standardmäßig werden vom Metrik-Explorer keine synthetischen Telemetriedaten angezeigt.

Die <Filters> legen identifizierende Eigenschaften der Anforderungen fest.
UserTelemetryInitializer Aktualisiert die Eigenschaften Id und AcquisitionDate des Kontexts User für alle Telemetrieelemente mit Werten, die aus dem Cookie ai_user extrahiert werden, der vom Application Insights-JavaScript-Instrumentationscode generiert wird, der im Browser des Benutzers ausgeführt wird.
WebTestTelemetryInitializer Legt die Benutzer-ID, Sitzungs-ID und synthetischen Quelleneigenschaften für die HTTP-Anforderungen fest, die aus Verfügbarkeitstests stammen.

Die <Filters> legen identifizierende Eigenschaften der Anforderungen fest.

Hinweis

Für .NET-Anwendungen in Azure Service Fabric können Sie das NuGet-Paket Microsoft.ApplicationInsights.ServiceFabric aufnehmen. Dieses Paket enthält eine Eigenschaft FabricTelemetryInitializer, wodurch Service Fabric-Eigenschaften zu Telemetrieelementen hinzugefügt werden. Weitere Informationen finden Sie auf der GitHub-Seite zu den Eigenschaften, die von diesem NuGet-Paket hinzugefügt werden.

Hinzufügen von ITelemetryInitializer

In diesem Blog wird ein Projekt zum Diagnostizieren von Abhängigkeitsproblemen beschrieben, indem regelmäßig Pings an Abhängigkeiten gesendet werden.

  1. Definieren Sie Ihren Initialisierer

    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. Laden Sie Ihren Initialisierer

Option 1: Konfiguration im Code

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

Option 2: Konfiguration in ApplicationInsights.config

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

Weitere Informationen zu diesem Beispiel.

Problembehandlung bei ApplicationInsights.config
  • Vergewissern Sie sich, dass der vollqualifizierte Typname und der Assemblyname korrekt sind.
  • Vergewissern Sie sich, dass sich die applicationinsights.config Datei in Ihrem Ausgabeverzeichnis befindet und alle letzten Änderungen enthält.

Beispiel für ITelemetryInitializers

Hinzufügen einer benutzerdefinierten Eigenschaft

Im folgenden Beispiel eines Initialisierers wird jeder verfolgten Telemetrie eine benutzerdefinierte Eigenschaft hinzugefügt.

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

Mit dem folgenden Beispielinitialisierer wird der Cloudrollenname für alle überwachten Telemetriedaten festgelegt.

public void Initialize(ITelemetry telemetry)
{
    if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
    {
        telemetry.Context.Cloud.RoleName = "MyCloudRoleName";
    }
}
Steuern der Client-IP-Adresse, die für Geolocation-Zuordnungen verwendet wird

Im folgenden Beispielinitialisierer wird die Client-IP festgelegt, die für die Geolocation-Zuordnung anstelle der Clientsocket-IP-Adresse während der Telemetrieaufnahme verwendet wird.

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

Telemetrieprozessoren

Mit Telemetrieprozessoren kann jedes Telemetrieelement vor dem Senden vom SDK an das Portal gefiltert und geändert werden.

  1. Implementieren Sie ITelemetryProcessor.

    Telemetrieprozessoren erstellen eine Verarbeitungskette. Wenn Sie einen Telemetrieprozessor instanziieren, erhalten Sie einen Verweis auf den nächsten Prozessor in der Kette. Wenn ein Telemetriedatenpunkt an die Prozessmethode übergeben wird, funktioniert er und ruft dann den nächsten Telemetrieprozessor in der Kette auf (oder ruft ihn nicht auf).

    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;
        }
    }
    
  2. Fügen Sie Ihren Prozessor hinzu.

    Fügen Sie diesen Codeausschnitt in ApplicationInsights.configein:

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

    Sie können Zeichenfolgenwerte aus der datei .config übergeben, indem Sie öffentliche benannte Eigenschaften in Ihrer Klasse bereitstellen.

    Warnung

    Achten Sie darauf, den Typnamen und alle Eigenschaftsnamen in der datei .config den Klassen- und Eigenschaftennamen im Code zuzuordnen. Wenn die .config-Datei auf einen nicht vorhandenen Typ oder eine Eigenschaft verweist, kann das SDK im Hintergrund keine Telemetrie senden.

    Alternativ können Sie den Filter im Code initialisieren. Fügen Sie in einer geeigneten Initialisierungsklasse, z. B. AppStart in Global.asax.cs, den Prozessor in die Kette ein:

    Hinweis

    Das folgende Codebeispiel ist veraltet, wird aber hier für die Posterität zur Verfügung gestellt. Erwägen Sie die ersten Schritte mit OpenTelemetry oder die Migration zu 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();
    

    Telemetrieclients, die nach diesem Zeitpunkt erstellt wurden, verwenden Ihre Prozessoren.

    Telemetrieprozessor für adaptive Stichprobenerstellung (von 2.0.0-beta3)

    Diese Funktionalität ist standardmäßig aktiviert. Wenn die App umfangreiche Telemetriedaten sendet, entfernt dieser Prozessor einige davon.

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

    Der Parameter enthält das Ziel, das der Algorithmus zu erreichen versucht. Die Instanzen des SDK funktionieren unabhängig voneinander. Wenn Ihr Server also aus mehreren Computern zu einem Cluster gruppiert ist, erhöht sich das tatsächliche Volumen an Telemetriedaten entsprechend.

    Erfahren Sie mehr über Sampling.

    Telemetrieprozessor für die Stichprobenerstellung mit festem Prozentsatz (von 2.0.0-beta1)

    Es gibt auch einen standardmäßigen Sampling-Telemetrieprozessor (von 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>
    

Beispielfilter

Synthetische Anfragen

Filtert Bots und Webtests aus. Obwohl der Metrics Explorer Ihnen die Möglichkeit bietet, synthetische Quellen herauszufiltern, reduziert diese Option den Datenverkehr und das Datenaufkommen, indem sie direkt im SDK herausgefiltert werden.

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

Filtert Anforderungen mit einer "401"-Antwort aus.

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);
}
Herausfiltern schneller Remoteabhängigkeitsaufrufe

Wenn Sie nur langsame Anrufe diagnostizieren möchten, filtern Sie die schnellen Aufrufe heraus.

Hinweis

Durch diese Filterung werden die Im Portal angezeigten Statistiken verzerrt.

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

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

Probenahme

Informationen zum Konfigurieren des Samplings für ASP.NET Anwendungen finden Sie unter Sampling in Application Insights.

Anreichern von Daten über HTTP

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

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

Verwalten von SDK-Komponenten

In diesem Abschnitt

Sie können das Application Insights SDK für ASP.NET, ASP.NET Core und Worker Service anpassen, um die Standardkonfiguration zu ändern.

Das Application Insights .NET SDK umfasst zahlreiche NuGet-Pakete. Das Kernpaket stellt die API für das Senden von Telemetriedaten an Application Insights bereit. Zusätzliche Pakete bieten Telemetriemodule und -initialisierer für die automatische Nachverfolgung von Telemetriedaten von Ihrer Anwendung und deren Kontext. Durch Anpassen der Konfigurationsdatei können Sie Telemetriemodule und -initialisierer aktivieren bzw. deaktivieren. Sie können für einige davon auch Parameter festlegen.

Der Name der Konfigurationsdatei lautet ApplicationInsights.config oder ApplicationInsights.xml. Der Name hängt vom Typ Ihrer Anwendung ab. Sie wird dem Projekt bei der Installation der meisten SDK-Versionen automatisch hinzugefügt.

Standardmäßig wird die Datei im Stammordner des Projekts erstellt, wenn Sie die automatisierte Funktion aus den Visual Studio-Vorlagenprojekten verwenden, die >ApplicationInsights.config unterstützen. Nach der Kompilierung wird sie in den Ordner „bin“ kopiert. Sie wird auch durch den Application Insights-Agent auf einem IIS-Server einer Web-App hinzugefügt.

Von Bedeutung

Die Konfigurationsdatei wird ignoriert, wenn die Erweiterung für Azure-Websites oder die Erweiterung für Azure-VMs und VM-Skalierungsgruppen verwendet wird.

Es gibt keine gleichwertige Datei zum Steuern des SDK in einer Webseite.

Telemetriekanäle

Telemetriekanäle sind ein integraler Bestandteil der Application Insights SDKs. Hiermit wird die Pufferung und Übertragung von Telemetriedaten an den Application Insights-Dienst verwaltet. Die .NET- und .NET Core-Versionen der SDKs verfügen über zwei integrierte Telemetriekanäle: InMemoryChannel und ServerTelemetryChannel. In diesem Abschnitt werden die einzelnen Kanäle beschrieben und das Anpassen des Kanalverhaltens veranschaulicht.

Hinweis

Häufig gestellte Fragen (FAQ) finden Sie unter Häufig gestellte Fragen zu Telemetriekanälen

Was sind Telemetriekanäle?

Telemetriekanäle sind für das Puffern und Senden von Telemetrieelementen an den Application Insights-Dienst verantwortlich, wo sie für Abfragen und Analysen gespeichert werden. Ein Telemetriekanal ist jede Klasse, die die Schnittstelle Microsoft.ApplicationInsights.ITelemetryChannel implementiert.

Die Send(ITelemetry item)-Methode eines Telemetriekanals wird aufgerufen, nachdem alle Telemetrieinitialisierer und Telemetrieprozessoren aufgerufen wurden. Daher erreichen Elemente, die von einem Telemetrieprozessor verworfen wurden, den Kanal nicht. Mit der Send()-Methode werden die Elemente gewöhnlich nicht sofort an das Back-End gesendet. Normalerweise werden Sie im Arbeitsspeicher gepufferten und für eine effiziente Übertragung in Batches gesendet.

Vermeiden Sie es, Flush() zu anzurufen, es sei denn, die gepufferte Telemetrie muss sofort gesendet werden. Verwenden Sie diese Funktion ausschließlich in folgenden Szenarien: beim Herunterfahren von Anwendungen, bei der Ausnahmebehandlung oder bei kurzlebigen Prozessen wie Hintergrundaufträgen oder Befehlszeilentools. In Webanwendungen oder länger ausgeführten Diensten übernimmt das SDK automatisch das Senden von Telemetriedaten. Das unnötige Aufrufen von Flush() kann zu Leistungsproblemen führen.

Live Metrics Stream verfügt auch über einen benutzerdefinierten Kanal, der für das Livestreaming von Telemetriedaten verwendet wird. Dieser Kanal ist vom regulären Telemetriekanal unabhängig, und dieses Dokument trifft nicht auf ihn zu.

Integrierte Telemetriekanäle

Im Lieferumfang der Application Insights SDKs für .NET und .NET Core sind zwei integrierte Kanäle enthalten:

  • InMemoryChannel: Ein einfacher Kanal, der Elemente im Arbeitsspeicher puffert, bis sie gesendet werden. Elemente werden im Arbeitsspeicher gepuffert, und dieser wird einmal alle 30 Sekunden geleert oder sobald 500 Elemente gepuffert sind. Dieser Kanal bietet minimale Zuverlässigkeitsgarantien, da das Senden von Telemetriedaten nach einem Fehler nicht wiederholt wird. Dieser Kanal bewahrt Elemente auch nicht auf dem Datenträger auf. Daher gehen alle nicht gesendeten Elemente beim Herunterfahren der Anwendung dauerhaft verloren, unabhängig davon, ob dies ordnungsgemäß erfolgt oder nicht. Dieser Kanal implementiert eine Flush()-Methode, mit der das synchrone Leeren aller Telemetrieelemente aus dem Arbeitsspeicher erzwungen werden kann. Dieser Kanal eignet sich gut für Anwendungen mit kurzer Ausführungszeit, bei denen eine synchrone Leerung ideal ist.

    Dieser Kanal ist Bestandteil des größeren NuGet-Pakets „Microsoft.ApplicationInsights“ und ist der Standardkanal, der vom SDK verwendet wird, wenn keine andere Konfiguration vorhanden ist.

  • ServerTelemetryChannel: Ein komplexerer Kanal, der über Wiederholungsrichtlinien verfügt und Daten auf einem lokalen Datenträger speichern kann. Dieser Kanal wiederholt das Senden von Telemetriedaten, wenn vorübergehende Fehler auftreten. Dieser Kanal verwendet auch lokalen Datenträgerspeicher, um Elemente während Netzwerkausfällen oder bei großen Telemetriedatenmengen auf dem Datenträger aufzubewahren. Aufgrund dieser Wiederholungsmechanismen und des lokalen Datenträgerspeichers gilt dieser Kanal als zuverlässiger. Er wird für alle Produktionsszenarien empfohlen. Dieser Kanal ist die Standardeinstellung für ASP.NET- und ASP.NET Core-Anwendungen, die gemäß der offiziellen Dokumentation konfiguriert sind. Dieser Kanal ist für Serverszenarien mit lang andauernden Prozessen optimiert. Die von diesem Kanal implementierte Flush()-Methode ist nicht synchron.

    Dieser Kanal wird als das NuGet-Paket Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel geliefert und automatisch erworben, wenn Sie das NuGet-Paket Microsoft.ApplicationInsights.Web oder Microsoft.ApplicationInsights.AspNetCore verwenden.

Konfigurieren eines Telemetriekanals

Sie konfigurieren einen Telemetriekanal, indem Sie ihn auf die aktive Telemetriekonfiguration festlegen. Bei ASP.NET-Anwendungen schließt die Konfiguration das Festlegen der Telemetriekanalinstanz auf TelemetryConfiguration.Active oder das Ändern von ApplicationInsights.config ein. Bei ASP.NET Core-Anwendungen schließt die Konfiguration das Hinzufügen des Kanals zum Container für die Abhängigkeitsinjektion ein.

In den folgenden Abschnitten werden Beispiele für die Konfiguration der StorageFolder-Einstellung des Kanals bei verschiedenen Anwendungstypen gezeigt. StorageFolder ist nur eine der konfigurierbaren Einstellungen. Die vollständige Liste der Konfigurationseinstellungen finden Sie im Abschnitt Konfigurierbare Einstellungen in Kanälen weiter unten in diesem Artikel.

Option 1: Konfiguration im Code

Der folgende Code richtet eine ServerTelemetryChannel-Instanz so ein, dass StorageFolder auf einen benutzerdefinierten Speicherort festgelegt ist. Fügen Sie diesen Code am Anfang der Anwendung hinzu, typischerweise in der Application_Start()-Methode in „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;
}

Option 2: Konfiguration in ApplicationInsights.config

Der folgende Abschnitt von ApplicationInsights.config zeigt die Konfiguration des Kanals ServerTelemetryChannel, bei der StorageFolder auf einen benutzerdefinierten Speicherort festgelegt ist:

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

Konfiguration im Code für Konsolenanwendungen

Bei Konsolen-Apps ist der Code für .NET und .NET Core identisch:

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

Funktionsdetails zu ServerTelemetryChannel

ServerTelemetryChannel speichert eingehende Elemente in einem Puffer im Arbeitsspeicher. Die Elemente werden serialisiert, komprimiert und einmal alle 30 Sekunden, oder sobald 500 Elemente gepuffert wurden, in einer Transmission-Instanz gespeichert. Eine einzelne Transmission-Instanz enthält bis zu 500 Elemente und stellt einen Batch von Telemetriedaten dar, die über einen einzigen HTTPS-Aufruf an den Application Insights-Dienst gesendet werden.

Standardmäßig können maximal 10 Transmission-Instanzen parallel gesendet werden. Wenn Telemetriedaten schneller eintreffen oder das Netzwerk bzw. das Application Insights-Back-End langsam ist, werden Transmission-Instanzen im Arbeitsspeicher gespeichert. Die Standardkapazität dieses Transmission-Puffers im Arbeitsspeicher beträgt 5 MB. Wenn die Kapazität des Arbeitsspeichers überschritten ist, werden Transmission-Instanzen auf einem lokalen Datenträger bis zu einem Maximum von 50 MB gespeichert.

Transmission-Instanzen werden auch bei Auftreten von Netzwerkproblemen auf dem lokalen Datenträger gespeichert. Nur die Elemente, die auf einem lokalen Datenträger gespeichert sind, überstehen einen Absturz der Anwendung. Sie werden gesendet, sobald die Anwendung wieder gestartet wird. Wenn weiterhin Netzwerkprobleme bestehen, verwendet ServerTelemetryChannel eine exponentielle Backofflogik im Bereich von 10 Sekunden bis zu einer Stunde, bevor erneut versucht wird, Telemetriedaten zu senden.

Konfigurierbare Einstellungen für die Kanäle

Die vollständige Liste der konfigurierbaren Einstellungen für jeden Kanal finden Sie in den folgenden Artikeln:

Nachfolgend sind die am häufigsten verwendeten Einstellungen für ServerTelemetryChannel aufgeführt:

  • MaxTransmissionBufferCapacity: Die maximale Menge an Arbeitsspeicher in Byte, die vom Kanal zum Puffern von Übertragungen im Arbeitsspeicher verwendet wird. Wenn diese Kapazitätsgrenze erreicht ist, werden neue Elemente direkt auf dem lokalen Datenträger gespeichert. Der Standardwert ist 5 MB. Das Festlegen eines höheren Werts führt zu einer geringeren Datenträgerauslastung, aber denken Sie daran, dass Elemente im Arbeitsspeicher bei einem Absturz der Anwendung verloren gehen.

  • MaxTransmissionSenderCapacity: Die maximale Anzahl von Transmission-Instanzen, die gleichzeitig an Application Insights gesendet werden. Der Standardwert ist 10. Diese Einstellung kann mit einem höheren Wert konfiguriert werden. Dies wird empfohlen, wenn große Mengen von Telemetriedaten generiert werden. Große Mengen treten in der Regel bei Auslastungstests auf oder wenn die Stichprobenerstellung deaktiviert ist.

  • StorageFolder: Der Ordner, der vom Kanal verwendet wird, um Elemente bei Bedarf auf dem Datenträger zu speichern. Unter Windows wird entweder %LOCALAPPDATA% oder %TEMP% verwendet, wenn kein anderer Pfad explizit angegeben wird. In anderen Umgebungen als Windows werden standardmäßig die folgenden Speicherorte verwendet (in der Reihenfolge): %TMPDIR%, /var/tmp/ oder /tmp/.

Welchen Kanal sollte ich verwenden?

ServerTelemetryChannel wird für die meisten Produktionsszenarien mit zeitintensiven Anwendungen empfohlen. Weitere Informationen zum Leeren der Telemetrie finden Sie unter Verwendung von Flush().

Gründe für die Verwendung von Flush()

Die Flush()-Methode sendet gepufferte Telemetrie sofort. Sie sollte jedoch nur in bestimmten Szenarien verwendet werden.

Verwenden Sie Flush() in folgenden Fällen:

  • Die Anwendung wird heruntergefahren, und Sie sollten sicherstellen, dass Telemetrie vor dem Beenden gesendet wird.
  • Sie befinden sich in einem Ausnahmehandler und müssen sicherstellen, dass Telemetrie übermittelt wird.
  • Sie schreiben einen kurzlebigen Prozess wie einen Hintergrundauftrag oder ein CLI-Tool, das schnell beendet wird.

Vermeiden Sie die Verwendung von Flush() in länger ausgeführten Anwendungen wie Webdiensten. Das SDK verwaltet das Puffern und Übertragung automatisch. Das unnötige Aufrufen von Flush() kann zu Leistungsproblemen führen und garantiert nicht, dass alle Daten gesendet werden, insbesondere bei der Verwendung von ServerTelemetryChannel, die nicht synchron geleert wird.

Telemetriemodule

Application Insights erfasst automatisch Telemetriedaten zu bestimmten Workloads, ohne dass eine manuelle Nachverfolgung durch den Benutzer erforderlich ist.

Die unten aufgeführten Module für die automatische Sammlung sind standardmäßig aktiviert. Sie können sie deaktivieren oder ihr Standardverhalten anpassen.

Jedes Telemetriemodul erfasst eine bestimmte Art von Daten und verwendet die Haupt-API zum Senden der Daten. Die Module werden von verschiedenen NuGet-Paketen installiert, mit denen der CONFIG-Datei auch die erforderlichen Zeilen hinzugefügt werden.

Area Description
Anforderungsnachverfolgung Erfasst die Anforderungstelemetrie (Antwortzeit, Ergebniscode) für eingehende Webanforderungen.

Modul:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
Abhängigkeitsüberwachung Erfasst Telemetriedaten zu ausgehenden Abhängigkeiten (HTTP-Aufrufe, SQL-Aufrufe). Um in IIS zu arbeiten, installieren Sie den Application Insights-Agenten. Sie können auch benutzerdefinierte Abhängigkeitsnachverfolgung mithilfe der TrackDependency-API schreiben. Unterstützt die automatische Instrumentierung mit app Service- und VMSS-Überwachung.

Modul:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.DependencyCollector
Leistungsindikatoren Erfasst Windows-Leistungsindikatoren (CPU, Arbeitsspeicher, Netzwerklast von IIS-Installationen). Geben Sie an, welche Leistungsindikatoren (einschließlich benutzerdefinierter Indikatoren) angezeigt werden. Weitere Informationen finden Sie unter Erfasst Systemleistungsindikatoren.

Modul:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Ereigniszähler Erfasst .NET EventCounters. Empfohlen für ASP.NET Core und plattformübergreifend anstelle von Windows-Leistungsindikatoren.

Modul:EventCounterCollectionModule (SDK ≥ 2.8.0)
Live Metrics (QuickPulse) Erfasst Telemetrie für den Bereich „Livemetriken“.

Modul:QuickPulseTelemetryModule
Herzschläge (App-Dienst) Übermittelt Heartbeats und benutzerdefinierte Metriken für die App Service-Umgebung.

Modul:AppServicesHeartbeatTelemetryModule
Herzschläge (VM/VMSS) Übermittelt Heartbeats und benutzerdefinierte Metriken für die Azure VM-Umgebung.

Modul:AzureInstanceMetadataTelemetryModule
Diagnose-Telemetrie Meldet Fehler im Application Insights-Instrumentierungscode (z. B. fehlende Zähler, ITelemetryInitializer-Ausnahmen). Die Ablaufverfolgungs-Telemetrie wird in der Diagnosesuche angezeigt.

Modul:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet:Microsoft.ApplicationInsights

Hinweis: Wenn Sie nur dieses Paket installieren, wird die Datei ApplicationInsights.config nicht automatisch erstellt.
Entwicklermodus (angefügter Debugger) Zwingt TelemetryChannel zum sofortigen Senden von Elementen, wenn der Debugger angefügt ist. Reduziert die Latenz, erhöht jedoch die CPU-/Netzwerkauslastung.

Modul:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet:Application Insights Windows Server
Ausnahmeverfolgung (Web) Verfolgt nicht behandelte Ausnahmen in Web-Apps. Informationen hierzu finden Sie unter Fehler und Ausnahmen.

Modul:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
Ausnahmenachverfolgung (nicht überwacht/nicht behandelt) Verfolgt nicht überwachte Task-Ausnahmen und nicht behandelte Ausnahmen für Worker-Rollen, Windows-Dienste und Konsolenanwendungen.

Modules:
 • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule
 • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule
NuGet:Microsoft.ApplicationInsights.WindowsServer
EventSource-Nachverfolgung Sendet konfigurierte EventSource-Ereignisse als Ablaufverfolgungen an Application Insights.

Modul:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet:Microsoft.ApplicationInsights.EventSourceListener
ETW-Sammler Sendet konfigurierte ETW-Anbieterereignisse als Ablaufverfolgungen an Application Insights.

Modul:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet:Microsoft.ApplicationInsights.EtwCollector
Kern-API (kein Modul) Kern-API, die von anderen Telemetriekomponenten und für benutzerdefinierte Telemetrie verwendet wird.

Modul:Microsoft.ApplicationInsights package
NuGet:Microsoft.ApplicationInsights
Hinweis: Wenn Sie nur dieses Paket installieren, wird die Datei ApplicationInsights.config nicht automatisch erstellt.

Konfigurieren von Telemetriemodulen

Verwenden Sie den Abschnitt TelemetryModules in ApplicationInsights.config, um Module zu konfigurieren, hinzuzufügen oder zu entfernen. Die folgenden Beispiele:

  • Konfigurieren von DependencyTrackingTelemetryModule (W3C-Header-Injection aktivieren).
  • Konfigurieren von EventCounterCollectionModule (Standardeinstellungen löschen und einen einzelnen Zähler hinzufügen).
  • Deaktivieren Sie die Sammlung perf-counter, indem Sie PerformanceCollectorModule entfernen.
<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>

Hinweis

Die genaue Gruppe von Modulen, die in Ihrem ApplicationInsights.config-Modul vorhanden sind, hängt davon ab, welche SDK-Pakete Sie installiert haben.

Telemetrie deaktivieren

Für jedes Modul gibt es in der Konfigurationsdatei einen Knoten. Um ein Modul zu deaktivieren, löschen Sie den Knoten, oder kommentieren Sie ihn aus.

Verbindungszeichenfolge

Mit dieser Einstellung wird die Application Insights-Ressource bestimmt, in der die Daten angezeigt werden. In der Regel erstellen Sie für jede Ihrer Anwendungen eine separate Ressource mit einer separaten Verbindungszeichenfolge.

Codebeispiele finden Sie unter Verbindungszeichenfolgen in Application Insights.

Wenn Sie den Schlüssel dynamisch festlegen möchten, um z. B. Ergebnisse aus Ihrer Anwendung an andere Ressourcen zu senden, können Sie die Verbindungszeichenfolge in der Konfigurationsdatei auslassen und stattdessen im Code festlegen.

Um die Verbindungszeichenfolge für alle Instanzen von TelemetryClient, einschließlich der Standardtelemetriemodule, festzulegen, führen Sie diesen Schritt in einer Initialisierungsmethode aus, z. B. global.aspx.cs in einem ASP.NET-Dienst:

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        var telemetryClient = new TelemetryClient(configuration);

Wenn Sie einen bestimmten Satz von Ereignissen an eine andere Ressource senden möchten, können Sie den Schlüssel für einen bestimmten Telemetrieclient festlegen:


    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

Um eine neue Verbindungszeichenfolge abzurufen, erstellen Sie eine neue Ressource im Application Insights-Portal.

ApplicationId-Anbieter

Hinweis

Für ASP.NET ist dieser Anbieter ab SDK v2.6.0* verfügbar.

Der Zweck dieses Anbieters besteht darin, eine Anwendungs-ID auf der Grundlage einer Verbindungszeichenfolge zu suchen. Die Anwendungs-ID ist in RequestTelemetry und DependencyTelemetry enthalten und wird verwendet, um die Korrelation im Portal zu ermitteln.

Diese Funktionalität ist durch Festlegen von TelemetryConfiguration.ApplicationIdProvider verfügbar.

Schnittstelle: IApplicationIdProvider

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

Das SDK Microsoft.ApplicationInsights bietet zwei Implementierungen: ApplicationInsightsApplicationIdProvider und DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Dieser Wrapper ist für die Profil-API gedacht. Er drosselt Anforderungen und Cacheergebnisse. Dieser Anbieter wird automatisch hinzugefügt, wenn Sie Microsoft.ApplicationInsights.DependencyCollector oder Microsoft.ApplicationInsights.Web installieren.

Die Klasse macht eine optionale Eigenschaft mit dem Namen ProfileQueryEndpoint verfügbar. Standardmäßig ist sie auf https://dc.services.visualstudio.com/api/profiles/{0}/appId festgelegt.

Sollten Sie einen Proxy konfigurieren müssen, empfehlen wir, die Basisadresse zu proxyen und sicherzustellen, dass der Pfad /api/profiles/{0}/appId enthält. Zur Laufzeit wird {0} für jede Anforderung durch den Instrumentierungsschlüssel ersetzt.

Beispielkonfiguration über 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>

Beispielkonfiguration über Code

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Dieser statische Anbieter basiert auf den konfigurierten Kombinationen aus Instrumentierungsschlüssel und Anwendungs-ID.

Diese Klasse verfügt über die Eigenschaft Defined, die ein Dictionary<string,string> von Instrumentierungsschlüssel-/Anwendungs-ID-Paaren ist.

Diese Klasse enthält die optionale Eigenschaft Next, mit der ein weiterer Anbieter konfiguriert werden kann. Dieser wird verwendet, wenn eine Verbindungszeichenfolge angefordert wird, die in Ihrer Konfiguration nicht vorhanden ist.

Beispielkonfiguration über ApplicationInsights.config

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

Beispielkonfiguration über Code

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

Konfigurieren der Erfassung von Momentaufnahmen

Informationen zum Konfigurieren der Erfassung von Momentaufnahmen für ASP.NET- und ASP.NET Core-Anwendungen finden Sie unter Aktivieren des Momentaufnahmedebuggers für .NET-Apps in Azure Service Fabric, Cloud Services und VM.

Hinzufügen der clientseitigen Überwachung

In den vorherigen Abschnitten haben Sie Anleitungen zu den Methoden erhalten, mit denen die serverseitige Überwachung automatisch und manuell konfiguriert werden kann. Wenn Sie die clientseitige Überwachung hinzufügen möchten, verwenden Sie das clientseitige JavaScript SDK. Sie können clientseitige Transaktionen einer beliebigen Webseite überwachen, indem Sie ein JavaScript (Web) SDK Loader-Skript vor dem schließenden </head>-Tag im HTML-Code der Seite hinzufügen.

Obwohl es möglich ist, das JavaScript (Web) SDK Loader-Skript manuell dem Header jeder HTML-Seite hinzuzufügen, sollten Sie das JavaScript (Web) SDK Loader-Skript stattdessen einer primären Seite hinzufügen. Diese Aktion schleust das JavaScript (Web) SDK Loader-Skript in alle Seiten einer Website ein.

Für die vorlagenbasierte ASP.NET-MVC-App in diesem Artikel heißt die Datei, die Sie bearbeiten müssen, _Layout.cshtml. Sie finden sie unter Ansichten>Freigegeben. Wenn Sie die clientseitige Überwachung hinzufügen möchten, öffnen Sie die Datei _Layout.cshtml, und befolgen Sie die auf dem JavaScript (Web) SDK Loader-Skript basierende Einrichtungsanleitung aus dem Artikel zur Konfiguration des clientseitigen JavaScript SDK.

Kern-API für benutzerdefinierte Ereignisse und Metriken

Fügen Sie einige Codezeilen in Ihre Anwendung ein, um herauszufinden, was Benutzer damit tun, oder um Probleme zu diagnostizieren. Sie können Telemetrie von Geräte- und Desktop-Apps, Webclients und Webservern senden. Verwenden Sie die Application Insights-Kern-Telemetrie-API, um benutzerdefinierte Ereignisse und Metriken und Ihre eigenen Versionen der Standardtelemetrie zu senden. Diese API ist die gleiche API, die von den standardmäßigen Application Insights-Datensammlern verwendet wird.

API-Zusammenfassung

Die Kern-API ist auf allen Plattformen einheitlich, abgesehen von einigen Variationen wie GetMetric (nur.NET).

Methode Wird für
TrackPageView Seiten, Bildschirme, Fenster oder Formulare.
TrackEvent Benutzeraktionen und andere Ereignisse. Wird verwendet, um das Benutzerverhalten zu verfolgen oder die Leistung zu überwachen.
GetMetric Null- und mehrdimensionale Metriken, zentral konfigurierte Aggregation, nur C#.
TrackMetric Leistungsmessungen wie Warteschlangenlängen, die nicht mit bestimmten Ereignissen zusammenhängen.
TrackException Protokollieren von Ausnahmen für die Diagnose. Verfolgen Sie, wo diese in Bezug auf andere Ereignisse auftreten, und untersuchen Sie die Stapelüberwachung.
TrackRequest Protokollierung der Häufigkeit und Dauer von Serveranforderungen für die Leistungsanalyse.
TrackTrace Nachrichten im Ressourcendiagnoseprotokoll. Sie können auch Protokolle von Drittanbietern erfassen.
TrackDependency Protokollierung der Dauer und Häufigkeit von Aufrufen externer Komponenten, von denen Ihre App abhängt.

Sie können Eigenschaften und Metriken an die meisten dieser Telemetrieaufrufe anfügen.

Voraussetzungen

Wenn Sie noch keinen Verweis auf das Application Insights SDK haben:

  1. Fügen Sie das Application Insights SDK zu Ihrem Projekt hinzu.

  2. Schließen Sie in Ihrem Gerät oder Webservercode Folgendes ein:

    using Microsoft.ApplicationInsights;
    

Abrufen einer TelemetryClient-Instanz

Erhalte eine Instanz von TelemetryClient:

Hinweis

Wenn Sie Azure Functions v2+ oder Azure WebJobs v3+ verwenden, lesen Sie "Überwachen von Azure-Funktionen".

Hinweis

Rufen Sie für Apps vom Typ ASP.NET Core oder Nicht-HTTP/Worker für .NET/.NET Core eine Instanz von TelemetryClient aus dem Container für die Abhängigkeitsinjektion ab, wie in der jeweiligen Dokumentation erläutert.

private TelemetryClient telemetry = new TelemetryClient();

Wenn eine Meldung angezeigt wird, die Besagt, dass diese Methode veraltet ist, finden Sie weitere Informationen unter microsoft/ApplicationInsights-dotnet#1152 .

Eingehende HTTP-Anforderungen werden automatisch erfasst. Möglicherweise möchten Sie weitere Instanzen TelemetryClient für andere Module Ihrer App erstellen. Sie können beispielsweise eine TelemetryClient Instanz in Ihrer Middleware-Klasse haben, um Geschäftslogikereignisse zu melden. Sie können Eigenschaften wie UserId und DeviceId festlegen, um die Maschine zu identifizieren. Diese Informationen werden an alle Ereignisse angefügt, die die Instanz sendet.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Hinweis

TelemetryClient ist threadsicher.

TrackEvent

In Application Insights ist ein benutzerdefiniertes Ereignis ein Datenpunkt, den Sie im Metrik-Explorer als aggregierte Anzahl und in der Diagnosesuche als einzelne Vorkommen anzeigen können. (Es ist nicht mit MVC oder anderen Framework-"Ereignissen" verknüpft.)

Fügen Sie TrackEvent Aufrufe in Ihren Code ein, um verschiedene Ereignisse zu zählen. Sie können beispielsweise nachverfolgen, wie oft Benutzer ein bestimmtes Feature auswählen. Oder Sie möchten vielleicht wissen, wie oft sie bestimmte Ziele erreichen oder bestimmte Arten von Fehlern machen.

Senden Sie beispielsweise in einer Spiele-App ein Ereignis, wenn ein Benutzer das Spiel gewinnt:

telemetry.TrackEvent("WinGame");

Benutzerdefinierte Ereignisse in Log Analytics

Die Telemetrie ist in der Tabelle customEvents auf der Registerkarte mit Application Insights-Protokollen oder auf der Oberfläche zur Verwendungsanalyse verfügbar. Ereignisse können von trackEvent(..) oder dem Click-Analytics-Automatische-Sammlung-Plugin stammen.

Wenn das Sampling ausgeführt wird, zeigt die itemCount Eigenschaft einen Wert größer als 1an. Beispielsweise bedeutet itemCount==10, dass von 10 Aufrufen zu trackEvent() der Samplingprozess nur einen übermittelt hat. Um eine korrekte Anzahl von benutzerdefinierten Ereignissen zu erhalten, verwenden Sie Code wie customEvents | summarize sum(itemCount).

Hinweis

itemCount hat einen Mindestwert von 1; der Datensatz selbst einen Eintrag darstellt.

GetMetric

Informationen zum effektiven Verwenden des GetMetric() Aufrufs zum Erfassen lokal präaggregatter Metriken für .NET- und .NET Core-Anwendungen finden Sie unter Custom metric collection in .NET and .NET Core.

TrackMetric

Hinweis

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric ist nicht die bevorzugte Methode zum Senden von Metriken. Metriken sollten immer über einen Zeitraum vor dem Senden vorab aggregiert werden. Verwenden Sie eine der GetMetric(..) Überladungen, um ein Metrikobjekt für den Zugriff auf SDK-Präaggregationsfunktionen abzurufen.

Wenn Sie Ihre eigene Voraggregationslogik implementieren, können Sie die TrackMetric() Methode verwenden, um die resultierenden Aggregate zu senden. Wenn Ihre Anwendung für jedes Mal ein separates Telemetrieelement ohne Aggregation sendet, haben Sie wahrscheinlich einen Anwendungsfall für die Ereignistelemetrie. Siehe TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights kann Metriken darstellen, die nicht bestimmten Ereignissen zugeordnet sind. Sie können beispielsweise eine Warteschlangenlänge in regelmäßigen Intervallen überwachen. Bei Metriken sind die einzelnen Messungen weniger interessant als die Variationen und Trends, und daher sind statistische Diagramme nützlich.

Um Metriken an Application Insights zu senden, können Sie die TrackMetric(..) API verwenden. Es gibt zwei Möglichkeiten zum Senden einer Metrik:

  • Einzelner Wert. Jedes Mal, wenn Sie eine Messung in Ihrer Anwendung durchführen, senden Sie den entsprechenden Wert an Application Insights.

    Angenommen, Sie haben eine Metrik, die die Anzahl der Elemente in einem Container beschreibt. Während eines bestimmten Zeitraums setzen Sie zunächst drei Elemente in den Container und entfernen dann zwei Elemente. Dementsprechend würden Sie zweimal anrufen TrackMetric . Zuerst übergeben Sie den Wert 3 und übergeben dann den Wert -2. Application Insights speichert beide Werte für Sie.

  • Aggregation. Wenn Sie mit Metriken arbeiten, ist jede einzelne Messung selten von Interesse. Stattdessen ist eine Zusammenfassung der Ereignisse in einem bestimmten Zeitraum wichtig. Eine solche Zusammenfassung wird als Aggregation bezeichnet.

    Im vorherigen Beispiel ist 1 die Aggregatmetriksumme für diesen Zeitraum und die Anzahl der Metrikwerte .2 Wenn Sie den Aggregationsansatz verwenden, rufen Sie nur einmal pro Zeitraum auf TrackMetric und senden die Aggregatwerte. Wir empfehlen diesen Ansatz, da dadurch der Kosten- und Leistungsaufwand erheblich reduziert werden kann, indem weniger Datenpunkte an Application Insights gesendet werden und gleichzeitig alle relevanten Informationen gesammelt werden.

Beispiele für einzelne Werte

So senden Sie einen einzelnen Metrikwert:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Benutzerdefinierte Metriken in Log Analytics

Die Telemetrie ist in der customMetrics Tabelle in Application Insights Analytics verfügbar. Jede Zeile stellt einen Aufruf von trackMetric(..) in Ihrer App dar.

  • valueSum: Die Summe der Messungen. Um den Mittelwert abzurufen, dividieren Sie durch valueCount.
  • valueCount: Die Anzahl der Messungen, die in diesem trackMetric(..) Aufruf aggregiert wurden.

Hinweis

valueCount hat einen Minimalwert von 1; der Datensatz selbst einen Eintrag darstellt.

Seitenaufrufe

In einer Geräte- oder Webseiten-App werden die Telemetriedaten zu den Seitenaufrufen standardmäßig gesendet, wenn die einzelnen Bildschirme oder Seiten geladen werden. Sie können jedoch die Standardeinstellung ändern, um Seitenansichten zu mehr oder unterschiedlichen Zeiten nachzuverfolgen. Beispielsweise können Sie in einer App, die Registerkarten oder Bereiche anzeigt, eine Seite nachverfolgen, wenn der Benutzer einen neuen Bereich öffnet.

Benutzer- und Sitzungsdaten werden zusammen mit Seitenansichten als Eigenschaften gesendet, sodass benutzer- und Sitzungsdiagramme lebendig werden, wenn Telemetrie zur Seitenansicht vorhanden ist.

Benutzerdefinierte Seitenansichten

telemetry.TrackPageView("GameReviewPage");

Seitentelemetrie in Log Analytics

In Log Analytics zeigen zwei Tabellen Daten aus Browservorgängen an:

  • pageViews: Enthält Daten über die URL und den Seitentitel.
  • browserTimings: Enthält Daten zur Clientleistung, z. B. die Zum Verarbeiten der eingehenden Daten benötigten Zeit.

So finden Sie, wie lange der Browser zum Verarbeiten verschiedener Seiten benötigt:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

So entdecken Sie die Beliebtheit verschiedener Browser:

pageViews
| summarize count() by client_Browser

Zum Zuordnen von Seitenansichten zu AJAX-Aufrufen, verknüpfen Sie diese mit den Abhängigkeiten:

pageViews
| join (dependencies) on operation_Id

TrackRequest

Das Server-SDK verwendet TrackRequest zum Protokollieren von HTTP-Anforderungen.

Sie können sie auch selbst aufrufen, wenn Sie Anforderungen in einem Kontext simulieren möchten, in dem das Webdienstmodul nicht ausgeführt wird.

Die empfohlene Methode zum Senden von Anforderungstelemetrie ist der Ort, an dem die Anforderung als Vorgangskontext fungiert.

Vorgangskontext

Sie können Telemetrieelemente miteinander korrelieren, indem Sie sie dem Vorgangskontext zuordnen. Das Standardmäßige Anforderungsnachverfolgungsmodul führt es für Ausnahmen und andere Ereignisse aus, die gesendet werden, während eine HTTP-Anforderung verarbeitet wird. In Search and Analytics können Sie alle Ereignisse, die der Anforderung zugeordnet sind, ganz einfach mithilfe der Vorgangs-ID finden.

Wenn Sie Telemetrie manuell nachverfolgen, ist die einfachste Möglichkeit, die Telemetriekorrelation mithilfe dieses Musters sicherzustellen:

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

Weitere Informationen zur Korrelation finden Sie unter Telemetriekorrelation in Application Insights.

Zusammen mit dem Festlegen eines Vorgangskontexts StartOperation wird ein Telemetrieelement des von Ihnen angegebenen Typs erstellt. Es sendet das Telemetrieelement, wenn Sie die Operation beenden oder wenn Sie explizit StopOperation aufrufen. Wenn Sie als Telemetrietyp verwenden RequestTelemetry , wird die Dauer auf das zeitlimitierte Intervall zwischen Start und Stopp festgelegt.

Die Telemetrieelemente, die innerhalb eines Vorgangsbereichs gemeldet werden, werden zu untergeordneten Elementen eines entsprechenden Vorgangs. Vorgangskontexte können geschachtelt werden.

In der Suche wird der Vorgangskontext verwendet, um die Liste verwandter Elemente zu erstellen.

Screenshot der Liste

Weitere Informationen zur Nachverfolgung von benutzerdefinierten Vorgängen finden Sie unter "Nachverfolgen von benutzerdefinierten Vorgängen mit Application Insights .NET SDK".

Anforderungen in Log Analytics

In Application Insights Analytics werden Anforderungen in der requests Tabelle angezeigt.

Wenn das Sampling ausgeführt wird, zeigt die itemCount Eigenschaft einen Wert größer als 1an. Beispielsweise bedeutet dies itemCount==10, dass von 10 Aufrufen an trackRequest() der Samplingprozess nur einen von ihnen übermittelt hat. Um eine korrekte Anzahl von Anforderungen und durchschnittliche Dauer nach Anforderungsnamen segmentiert zu erhalten, verwenden Sie Code wie:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Ausnahmen an Application Insights senden:

Die Berichte enthalten die Stapelüberwachung.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Die SDKs erfassen viele Ausnahmen automatisch, sodass Sie nicht immer explizit aufrufen TrackException müssen.

Ausnahmen in Log Analytics

In Application Insights Analytics werden Ausnahmen in der exceptions Tabelle angezeigt.

Wenn das Sampling ausgeführt wird, zeigt die itemCount Eigenschaft einen Wert größer als 1an. Beispielsweise bedeutet dies itemCount==10, dass von 10 Aufrufen an trackException() der Samplingprozess nur einen von ihnen übermittelt hat. Um eine korrekte Anzahl von Ausnahmen abzurufen, die nach Ausnahmetyp segmentiert werden, verwenden Sie Code wie:

exceptions
| summarize sum(itemCount) by type

Die meisten wichtigen Stapelinformationen werden bereits in separate Variablen extrahiert, aber Sie können die details Struktur auseinanderziehen, um mehr zu erhalten. Da diese Struktur dynamisch ist, sollten Sie das Ergebnis in den erwarteten Typ umwandeln. Beispiel:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Verwenden Sie zum Zuordnen von Ausnahmen zu den zugehörigen Anforderungen eine Verknüpfung:

exceptions
| join (requests) on operation_Id

TrackTrace

Nutzen Sie TrackTrace bei der Diagnose von Problemen, indem Sie eine Brotkrümelnavigation an Application Insights senden. Sie können Blöcke von Diagnosedaten senden und in der Diagnosesuche prüfen.

Verwenden Sie in . NET-Protokolladaptern diese API, um Protokolle von Drittanbietern an das Portal zu senden.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Protokollieren Sie ein Diagnoseereignis, z. B. das Eingeben oder Verlassen einer Methode.

Parameter Description
message Diagnosedaten. Kann viel länger sein als ein Name.
properties Zuordnung von Zeichenfolge zu Zeichenfolge. Weitere Daten werden verwendet, um Ausnahmen im Portal zu filtern . Standardmäßig leer.
severityLevel Unterstützte Werte: SeverityLevel.ts.

Sie können nach Nachrichteninhalten suchen, aber im Gegensatz zu Eigenschaftswerten können Sie ihn nicht filtern.

Die Größenbeschränkung message ist viel höher als der Grenzwert für Eigenschaften. Ein Vorteil TrackTrace ist, dass Sie relativ lange Daten in die Nachricht einfügen können. Beispielsweise können Sie POST-Daten dort codieren.

Sie können Ihrer Nachricht auch einen Schweregradstufe hinzufügen. Wie bei anderen Telemetriedaten auch können Sie Eigenschaftswerte hinzufügen, um zu filtern oder nach verschiedenen Ablaufverfolgungen zu suchen. Beispiel:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

In der Suche können Sie dann ganz einfach alle Nachrichten eines bestimmten Schweregrads herausfiltern, die sich auf eine bestimmte Datenbank beziehen.

Ablaufverfolgungen in Log Analytics

In Application Insights Analytics werden Aufrufe an TrackTrace in der traces-Tabelle angezeigt.

Wenn das Sampling ausgeführt wird, zeigt die itemCount Eigenschaft einen Wert größer als 1an. Beispielsweise bedeutet dies itemCount==10, dass von 10 Aufrufen an trackTrace() der Samplingprozess nur einen von ihnen übermittelt hat. Verwenden Sie Code wie traces | summarize sum(itemCount), um die korrekte Anzahl von Ablaufverfolgungsaufrufen zu erhalten.

TrackDependency

Verwenden Sie den TrackDependency Aufruf, um die Reaktionszeiten und Erfolgsraten von Aufrufen an einen externen Codeabschnitt nachzuverfolgen. Die Ergebnisse werden in den Abhängigkeitsdiagrammen im Portal angezeigt. Der folgende Codeausschnitt muss überall hinzugefügt werden, wo ein Abhängigkeitsaufruf erfolgt.

Hinweis

Für .NET und .NET Core können Sie alternativ die Erweiterungsmethode TelemetryClient.StartOperation verwenden, die die für die Korrelation erforderlichen Eigenschaften sowie einige andere Eigenschaften wie Startzeit und Dauer füllt, sodass Sie keinen benutzerdefinierten Timer, wie in den folgenden Beispielen, erstellen müssen. Weitere Informationen finden Sie im Abschnitt zur ausgehenden Abhängigkeitsnachverfolgung in "Nachverfolgen von benutzerdefinierten Vorgängen mit Application Insights .NET SDK".

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Denken Sie daran, dass die Server-SDKs ein Abhängigkeitsmodul enthalten, das bestimmte Abhängigkeitsaufrufe, wie z. B. Datenbanken und REST-APIs, automatisch erkennt und nachverfolgt. Sie müssen einen Agent auf Ihrem Server installieren, damit das Modul funktioniert.

Sie verwenden diesen Anruf, wenn Sie Anrufe nachverfolgen möchten, die die automatisierte Nachverfolgung nicht erfasst.

Um das Standard-Abhängigkeitsnachverfolgungsmodul in C# zu deaktivieren, bearbeiten Sie ApplicationInsights.config, und löschen Sie den Verweis auf DependencyCollector.DependencyTrackingTelemetryModule.

Abhängigkeiten in Log Analytics

In Application Insights AnalyticstrackDependency werden Aufrufe in der dependencies Tabelle angezeigt.

Wenn das Sampling ausgeführt wird, zeigt die itemCount Eigenschaft einen Wert größer als 1 an. Beispielsweise bedeutet dies itemCount==10, dass von 10 Aufrufen an trackDependency() der Samplingprozess nur einen von ihnen übermittelt hat. Um eine korrekte Anzahl von Abhängigkeiten abzurufen, die nach Zielkomponente segmentiert sind, verwenden Sie Code wie:

dependencies
| summarize sum(itemCount) by target

Verwenden Sie eine Verknüpfung, um Abhängigkeiten ihren verwandten Anforderungen zuzuordnen:

dependencies
| join (requests) on operation_Id

Löschen von Daten

Normalerweise sendet das SDK Daten in festen Intervallen, in der Regel 30 Sekunden oder wenn der Puffer voll ist, was normalerweise 500 Elemente ist. In einigen Fällen möchten Sie den Puffer möglicherweise leeren. Ein Beispiel ist, wenn Sie das SDK in einer Anwendung verwenden, die beendet wird.

Wenn Sie Flush() verwenden, empfehlen wir dieses Muster:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Wenn Sie FlushAsync() verwenden, empfehlen wir dieses Muster:

await telemetryClient.FlushAsync()
// No need to sleep

Wir empfehlen, beim Herunterfahren der Applikation stets einen Flush durchzuführen, um sicherzustellen, dass keine Telemetriedaten verloren gehen.

Hinweis

Überprüfen Sie die Autoflush-Konfiguration: Die Aktivierung von Autoflush in Ihrer web.config Datei kann zu Leistungsbeeinträchtigungen in .NET-Anwendungen führen, die mit Application Insights instrumentiert sind. Bei aktivierter Autoflush-Funktion führt jeder Aufruf von System.Diagnostics.Trace.Trace* Methoden dazu, dass einzelne Telemetrieelemente als separate unterschiedliche Webanforderungen an den Aufnahmedienst gesendet werden. Dies kann zu einer Netzwerk- und Speicherauslastung auf Ihren Webservern führen. Um die Leistung zu verbessern, empfiehlt es sich, autoflush zu deaktivieren und außerdem den ServerTelemetryChannel zu verwenden, der für eine effektivere Telemetriedatenübertragung konzipiert ist.

Die Funktion ist asynchron für den Server-Telemetriekanal.

Authentifizierte Benutzer

In einer Web-App werden Benutzer standardmäßig durch Cookies identifiziert . Ein Benutzer wird möglicherweise mehrmals gezählt, wenn er von einem anderen Computer oder Browser aus auf Ihre App zugreift oder wenn er Cookies löscht.

Wenn sich Benutzer bei Ihrer App anmelden, können Sie eine genauere Anzahl erhalten, indem Sie die authentifizierte Benutzer-ID im Browsercode festlegen. Es ist nicht erforderlich, den tatsächlichen Anmeldenamen des Benutzers zu verwenden. Es muss nur eine ID sein, die für diesen Benutzer eindeutig ist. Es darf keine Leerzeichen oder eines der Zeichen ,;=|enthalten.

Die Benutzer-ID wird auch in einem Sitzungscookies festgelegt und an den Server gesendet. Wenn das Server-SDK installiert ist, wird die authentifizierte Benutzer-ID als Teil der Kontexteigenschaften von Client- und Server-Telemetrie gesendet. Anschließend können Sie danach filtern und suchen.

Wenn Ihre App Benutzer in Konten gruppiert, können Sie auch einen Bezeichner für das Konto übergeben. Es gelten dieselben Zeicheneinschränkungen.

Im Metrik-Explorer können Sie ein Diagramm erstellen, das "Benutzer", "Authentifiziert" und "Benutzerkonten" zählt.

Sie können auch nach Clientdatenpunkten mit bestimmten Benutzernamen und Konten suchen .

Hinweis

Die EnableAuthenticationTrackingJavaScript-Eigenschaft in der ApplicationInsightsServiceOptions-Klasse im .NET Core SDK vereinfacht die JavaScript-Konfiguration, die zum Einfügen des Benutzernamens als Auth-ID für jede vom Application Insights JavaScript SDK gesendete Ablaufverfolgung erforderlich ist.

Wenn diese Eigenschaft auf true festgelegt ist, wird der Benutzername im ASP.NET Core zusammen mit clientseitiger Telemetrie angezeigt. Aus diesem Grund ist das manuelle Hinzufügen appInsights.setAuthenticatedUserContext nicht mehr erforderlich, da es bereits vom SDK für ASP.NET Core eingefügt wurde. Die Auth-ID wird auch an den Server gesendet, auf dem das SDK in .NET Core sie identifiziert und für jede serverseitige Telemetrie verwendet, wie in der JavaScript-API-Referenz beschrieben.

Für JavaScript-Anwendungen, die nicht auf die gleiche Weise funktionieren wie ASP.NET Core MVC, z. B. SPA-Web-Apps, müssen Sie immer noch manuell hinzufügen appInsights.setAuthenticatedUserContext .

Filtern, Suchen und Segmentieren Ihrer Daten mithilfe von Eigenschaften

Sie können Eigenschaften und Messungen an Ihre Ereignisse, Metriken, Seitenansichten, Ausnahmen und andere Telemetriedaten anfügen.

Eigenschaften sind Zeichenfolgenwerte, mit denen Sie Ihre Telemetrie in den Verwendungsberichten filtern können. Wenn Ihre App beispielsweise mehrere Spiele bereitstellt, können Sie den Namen des Spiels an jedes Ereignis anfügen, damit Sie sehen können, welche Spiele beliebter sind.

Die Zeichenfolgenlänge ist auf 8.192 Zeichen begrenzt. Wenn Sie große Datenblöcke senden möchten, verwenden Sie den Nachrichtenparameter von TrackTrace.

Metriken sind numerische Werte, die grafisch dargestellt werden können. Vielleicht möchten Sie beispielsweise sehen, ob es einen graduellen Anstieg der Ergebnisse gibt, die Ihre Spieler erzielen. Die Diagramme können durch die Eigenschaften segmentiert werden, die mit dem Ereignis gesendet werden, sodass Sie separate oder gestapelte Diagramme für verschiedene Spiele abrufen können.

Metrikwerte sollten größer oder gleich 0 sein, damit sie ordnungsgemäß angezeigt werden.

Es gibt einige Grenzwerte für die Anzahl der Eigenschaften, Eigenschaftswerte und Metriken, die Sie verwenden können.

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

Von Bedeutung

Stellen Sie sicher, dass Sie keine persönlich identifizierbaren Informationen in Eigenschaften protokollieren.

Alternative Möglichkeit zum Festlegen von Eigenschaften und Metriken

Wenn dies praktischer ist, können Sie die Parameter eines Ereignisses in einem separaten Objekt sammeln:

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

Warnung

Verwenden Sie nicht dieselbe Telemetrieelementinstanz (event in diesem Beispiel), um mehrmals aufzurufen Track*() . Diese Vorgehensweise kann dazu führen, dass Telemetrie mit einer falschen Konfiguration gesendet wird.

Benutzerdefinierte Messungen und Eigenschaften in Log Analytics

In Log Analytics werden benutzerdefinierte Metriken und Eigenschaften in den customMeasurements und customDimensions Attributen jedes Telemetriedatensatzes angezeigt.

Wenn Sie ihrer Anforderungs-Telemetrie beispielsweise eine Eigenschaft mit dem Namen "Game" hinzufügen, zählt diese Abfrage die Vorkommen verschiedener Werte von "Game" und zeigt den Mittelwert der benutzerdefinierten Metrik "Score" an:

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Beachten Sie Folgendes:

  • Wenn Sie einen Wert aus dem customDimensions oder customMeasurements JSON extrahieren, hat er einen dynamischen Typen, dann müssen Sie ihn entweder tostring oder todouble konvertieren.
  • Um die Möglichkeit der Probenahme zu berücksichtigen, verwenden Sie sum(itemCount) nicht count().

Zeitmessung bei Ereignissen

Manchmal möchten Sie diagrammieren, wie lange es dauert, um eine Aktion auszuführen. So möchten Sie beispielsweise wissen, wie lange Benutzer entscheidungen in einem Spiel berücksichtigen müssen. Verwenden Sie den Messparameter, um diese Informationen zu erhalten.

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

Standardeigenschaften für benutzerdefinierte Telemetrie

Wenn Sie Standardeigenschaftenwerte für einige der benutzerdefinierten Ereignisse festlegen möchten, die Sie schreiben, legen Sie sie in einer TelemetryClient Instanz fest. Sie werden jedem Telemetrieelement hinzugefügt, das von diesem Client gesendet wird.

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

Einzelne Telemetrieaufrufe können die Standardwerte in ihren Eigenschaftenwörterbüchern überschreiben.

Wenn Sie allen Telemetriedaten Eigenschaften hinzufügen möchten (einschließlich Daten aus Standardsammlungsmodulen), implementieren Sie ITelemetryInitializer.

Telemetrie deaktivieren

So beenden Und starten Sie die Erfassung und Übertragung von Telemetrie dynamisch:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Entwicklermodus

Während des Debuggens ist es sinnvoll, die Telemetriedaten beschleunigt über die Pipeline zu senden, damit die Ergebnisse sofort angezeigt werden. Außerdem erhalten Sie andere Nachrichten, mit denen Sie Probleme mit der Telemetrie nachverfolgen können. Schalten Sie sie in der Produktion aus, da die App möglicherweise verlangsamt wird.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Festlegen des Instrumentierungsschlüssels für ausgewählte benutzerdefinierte Telemetrie

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Dynamische Verbindungszeichenfolge

Um eine Vermischung von Telemetrie aus Entwicklungs-, Test- und Produktionsumgebungen zu vermeiden, können Sie separate Application Insights-Ressourcen erstellen und ihre Schlüssel je nach Umgebung ändern.

Anstatt den Instrumentierungsschlüssel aus der Konfigurationsdatei zu erhalten, können Sie ihn in Ihrem Code festlegen. Legen Sie den Schlüssel in einer Initialisierungsmethode fest, z global.aspx.cs . B. in einem ASP.NET Dienst:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

TelemetryContext

TelemetryClient verfügt über eine Context-Eigenschaft, die Werte enthält, die zusammen mit allen Telemetriedaten gesendet werden. Sie werden normalerweise von den Standardmäßigen Telemetriemodulen festgelegt, aber Sie können sie auch selbst festlegen. Beispiel:

telemetry.Context.Operation.Name = "MyOperationName";

Wenn Sie einen dieser Werte selbst festlegen, sollten Sie die relevante Zeile aus ApplicationInsights.config entfernen, damit Ihre Werte und die Standardwerte nicht verwechselt werden.

  • Komponente: Die App und ihre Version.
  • Gerät: Daten zum Gerät, auf dem die App ausgeführt wird. In Web-Apps ist es der Server oder das Clientgerät, von dem die Telemetrie gesendet wird.
  • InstrumentationKey: Die Application Insights-Ressource in Azure, in der die Telemetrie angezeigt wird. Es wird normalerweise von ApplicationInsights.configabgeholt.
  • Standort: Der geografische Standort des Geräts.
  • Vorgang: In Web-Apps die aktuelle HTTP-Anforderung. In anderen App-Typen können Sie diesen Wert so festlegen, dass Ereignisse gruppiert werden.
    • ID: Ein generierter Wert, der unterschiedliche Ereignisse korreliert, sodass Sie beim Überprüfen eines Ereignisses in der Diagnosesuche verwandte Elemente finden können.
    • Name: Ein Bezeichner, in der Regel die URL der HTTP-Anforderung.
    • SyntheticSource: Falls nicht null oder leer ist, ist dies eine Zeichenfolge, die angibt, dass die Quelle der Anforderung als Roboter oder Webtest identifiziert wurde. Standardmäßig wird sie aus Berechnungen im Metrik-Explorer ausgeschlossen.
  • Sitzung: Die Sitzung des Benutzers. Die ID wird auf einen generierten Wert festgelegt, der geändert wird, wenn der Benutzer eine Weile nicht aktiv war.
  • Benutzer: Benutzerinformationen.

Grenzen

Es gibt einige Grenzwerte hinsichtlich der Anzahl von Metriken und Ereignissen pro Anwendung (d. h. pro Instrumentationsschlüssel). Die Beschränkungen hängen von dem von Ihnen ausgewählten Tarif ab.

Resource Standardgrenze Maximale Grenze Hinweise
Gesamtdaten pro Tag 100 GB Wenden Sie sich an den Support. Sie können eine Obergrenze festlegen, um Daten zu reduzieren. Wird eine höhere Datenmenge benötigt, können Sie den Grenzwert im Portal auf bis zu 1.000 GB erhöhen. Bei Kapazitäten über 1.000 GB senden Sie eine E-Mail an AIDataCap@microsoft.com.
Throttling 32.000 Ereignisse/s Wenden Sie sich an den Support. Das Limit wird eine Minute lang gemessen.
Datenaufbewahrungsprotokolle 30 bis 730 Tage 730 Tage Diese Ressource ist für Protokolle vorgesehen.
Datenaufbewahrungsmetriken 90 Tage 90 Tage Diese Ressource ist für den Metrik-Explorer vorgesehen.
Aufbewahrung ausführlicher Ergebnisse von Verfügbarkeitstests mit mehreren Schritten 90 Tage 90 Tage Diese Ressource liefert detaillierte Ergebnisse der einzelnen Schritte.
Maximale Größe von Telemetrieelementen 64 KB 64 KB
Maximale Anzahl von Telemetrieelementen pro Batch 64.000 64.000
Eingenschaft und Länge der Namen von Metriken 150 150 Siehe Typschemas.
Zeichenfolgenlänge des Eigenschaftswerts 8,192 8,192 Siehe Typschemas.
Länge von Ablaufverfolgungs- und Ausnahmebenachrichtigungen 32,768 32,768 Siehe Typschemas.
Anzahl der Verfügbarkeitstests pro Application Insights-Ressource 100 100
Anzahl der Verfügbarkeitstests pro Ressourcengruppe 800 800 Weitere Informationen finden Sie unter Azure Resource Manager.
In Verfügbarkeitstests maximale Anzahl der Umleitungen pro Test 10 10
Minimale Testhäufigkeit bei Verfügbarkeitstests 300 Sekunden Benutzerdefinierte Testhäufigkeiten oder Häufigkeiten von weniger als fünf Minuten erfordern benutzerdefinierte TrackAvailability-Implementierungen.
.NET Profiler- und Momentaufnahmedebugger-Datenaufbewahrung Zwei Wochen Kontaktieren Sie den Support. Die maximale Aufbewahrungszeit beträgt sechs Monate.
Pro Tag gesendete .NET Profiler-Daten Keine Begrenzung Keine Begrenzung
Pro Tag gesendete Momentaufnahmedebugger-Daten 30 Momentaufnahmen pro Tag pro überwachte App Keine Begrenzung Die Anzahl der pro Anwendung erfassten Momentaufnahmen kann über die Konfiguration geändert werden.

Weitere Informationen zu Preisen und Kontingenten finden Sie unter Abrechnung für Application Insights.

Um zu vermeiden, dass das Datenratenlimit erreicht wird, verwenden Sie Sampling.

Informationen dazu, wie lange Daten aufbewahrt werden, finden Sie unter "Datenaufbewahrung und Datenschutz".

Beispielanwendungen

.NET Core-Konsolenanwendung: Verwenden Sie dieses Beispiel, wenn Sie eine Konsolenanwendung verwenden, die in .NET Core (2.0 oder höher) oder .NET Framework (4.7.2 oder höher) geschrieben wurde.

ASP.NET Haupthintergrundaufgaben mit HostedServices: Verwenden Sie dieses Beispiel, wenn Sie sich in ASP.NET Core befinden und Hintergrundaufgaben gemäß offiziellen Anleitungen erstellen.

.NET Core Worker Service: Verwenden Sie dieses Beispiel, wenn Sie über eine .NET Worker Service-Anwendung gemäß offiziellen Anleitungen verfügen.

Problembehandlung

Informationen finden Sie in dem dedizierten Artikel zur Problembehandlung.

In Visual Studio 2019 gibt es ein bekanntes Problem: Das Speichern des Instrumentierungsschlüssels oder der Verbindungszeichenfolge in einem Benutzergeheimnis ist für .NET Framework-basierte Apps fehlerhaft. Der Schlüssel muss letztendlich in die Applicationinsights.config Datei hartcodiert werden, um diesen Fehler zu umgehen. Dieser Artikel wurde so verfasst, dass dieses Problem komplett umgangen wird, indem keine Benutzergeheimnisse verwendet werden.

Testen der Konnektivität zwischen Ihrem Anwendungshost und dem Erfassungsdienst

Application Insights-SDKs und -Agents senden Telemetriedaten, die als REST-Aufrufe unserer Erfassungsendpunkte erfasst werden sollen. Sie können die Konnektivität Ihres Webservers oder Anwendungshostcomputers mit den Endpunkten des Erfassungsdiensts testen, indem Sie unformatierte REST-Clients über PowerShell- oder cURL-Befehle verwenden. Siehe Problembehandlung bei fehlender Anwendungstelemetrie in Azure Monitor Application Insights.

Open Source SDK

Lesen und Hinzufügen von Code.

Die neuesten Updates und Fehlerbehebungen finden Sie in den Versionshinweisen.

Veröffentlichungshinweise

Versionen ab 2.12: .NET Software Development Kits (SDKs) einschließlich ASP.NET, ASP.NET Core und Protokollierungsadaptern

Unsere Dienstupdates fassen auch wichtige Application Insights-Verbesserungen zusammen.

Nächste Schritte

Referenz