Konfigurieren des Application Insights-SDK mit „ApplicationInsights.config“ oder „.xml“

  • Artikel

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.

Hinweis

Die folgende Dokumentation basiert auf der klassischen Application Insights-API. Der langfristige Plan für Application Insights besteht darin, Daten mithilfe von OpenTelemetry zu sammeln. Weitere Informationen finden Sie unter Aktivieren von Azure Monitor OpenTelemetry für .NET-, Node.js-, Python- und Java-Anwendungen.

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 ApplicationInsights.config im Stammordner des Projekts erstellt, wenn Sie die automatisierte Funktion aus den Visual Studio-Vorlagenprojekten verwenden, die Hinzufügen>Application Insights-Telemetrie unterstützen. Beim Kompilieren wird sie dann in den Ordner „bin“ kopiert. Sie wird auch durch den Application Insights-Agent auf einem IIS-Server einer Web-App hinzugefügt. 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.

In diesem Artikel wird beschrieben, welche Abschnitte in der Konfigurationsdatei angezeigt werden, wie sie die Komponenten des SDK steuern und welche NuGet-Pakete diese Komponenten laden.

Hinweis

Die Anweisungen für ApplicationInsights.config und „.xml“ gelten nicht für das .NET Core SDK. Zum Konfigurieren von .NET Core-Anwendungen folgen Sie den Anweisungen in Application Insights für ASP.NET Core-Anwendungen.

Telemetriemodule (ASP.NET)

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.

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.

Abhängigkeitsüberwachung

Dependency tracking werden Telemetriedaten zu Aufrufen erfasst, die von Ihrer App für Datenbanken und externe Dienste und Datenbanken durchgeführt werden. Damit dieses Modul auf einem IIS-Server funktioniert, müssen Sie den Application Insights-Agent installieren.

Sie können auch eigenen Code zur Abhängigkeitsnachverfolgung mithilfe der TrackDependency-APIschreiben.

Abhängigkeiten können ohne Änderung Ihres Codes mithilfe einer Agent-basierten Anfügung (ohne Code) automatisch erfasst werden. Aktivieren Sie zur Verwendung in Azure-Web-Apps die Application Insights-Erweiterung. Für eine Verwendung in einer Azure-VM oder einer Azure-VM-Skalierungsgruppe aktivieren Sie die Erweiterung zur Anwendungsüberwachung für VMs und VM-Skalierungsgruppen.

Leistungserfassung

Die Leistungserfassung dient dem Sammeln von Systemleistungsindikatoren, z. B. CPU- , Arbeitsspeicher- und Netzwerkauslastung von IIS-Installationen. Sie können angeben, welche Leistungsindikatoren erfasst werden sollen, z. B. auch Leistungsindikatoren, die Sie selbst eingerichtet haben.

Application Insights-Diagnosetelemetrie

Die Klasse DiagnosticsTelemetryModule gibt Fehler im eigentlichen Application Insights-Instrumentationscode an. Dies geschieht beispielsweise, wenn der Code nicht auf Leistungsindikatoren zugreifen kann oder wenn ITelemetryInitializer eine Ausnahme auslöst. Telemetriedaten der Ablaufverfolgung, die in diesem Modul nachverfolgt werden, werden in der Diagnosesuche angezeigt.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.ApplicationInsights . Wenn Sie nur dieses Paket installieren, wird die Datei „ApplicationInsights.config“ nicht automatisch erstellt.

Entwicklermodus

Die Klasse DeveloperModeWithDebuggerAttachedTelemetryModule erzwingt, dass TelemetryChannel von Application Insights Daten sofort sendet (jeweils nur ein Telemetrieelement), wenn ein Debugger an den Anwendungsprozess angefügt ist. So wird die Zeit zwischen dem Moment, in dem die Anwendung die Telemetrie nachverfolgt, und der Anzeige im Application Insights-Portal verkürzt. Für die CPU und die Netzwerkbandbreite ist dies eine erhebliche Belastung.

Nachverfolgung von Webanforderungen

Die Nachverfolgung von Webanforderungen meldet die Antwortzeit und den Ergebniscode von HTTP-Anforderungen.

Ausnahmeverfolgung

Die Klasse ExceptionTrackingTelemetryModule verfolgt nicht behandelte Ausnahmen in Ihrer Web-App. Weitere Informationen finden Sie unter Fehler und Ausnahmen.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • NuGet-Paket Microsoft.ApplicationInsights.Web
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Verfolgt nicht überwachten Task. Ausnahmen.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: Verfolgt nicht überwachte Ausnahmen für Workerrollen, Windows-Dienste und Konsolenanwendungen.
  • Application Insights Windows Server .

EventSource-Nachverfolgung

Mit der Klasse EventSourceTelemetryModule können Sie EventSource-Ereignisse so konfigurieren, dass sie als Ablaufverfolgungen an Application Insights gesendet werden. Informationen zum Nachverfolgen von EventSource-Ereignissen finden Sie unter Verwenden von EventSource-Ereignissen.

ETW-Ereignisnachverfolgung

Mit der Klasse EtwCollectorTelemetryModule können Sie Ereignisse von ETW-Anbietern so konfigurieren, dass Sie als Ablaufverfolgungen an Application Insights gesendet werden. Informationen zum Nachverfolgen von ETW-Ereignissen finden Sie unter Verwenden von ETW-Ereignissen.

Microsoft.ApplicationInsights

Das Paket Microsoft.ApplicationInsights enthält die Kern-API des SDK. Die anderen Telemetriemodule verwenden diese API. Sie können sie auch verwenden, um Ihre eigene Telemetrie zu definieren.

  • Kein Eintrag in „ApplicationInsights.config“.
  • Microsoft.ApplicationInsights . Wenn Sie nur dieses NuGet-Paket installieren, wird keine CONFIG-Datei generiert.

Telemetriekanal

Der Telemetriekanal verwaltet die Pufferung und Übertragung von Telemetriedaten an den Application Insights-Dienst.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel ist der Standardkanal für Webanwendungen. Er puffert Daten im Arbeitsspeicher und nutzt Wiederholungsmechanismen und lokalen Datenträgerspeicher für eine zuverlässigere Übermittlung von Telemetriedaten.
  • Microsoft.ApplicationInsights.InMemoryChannel ist ein einfacher Telemetriekanal. Es wird verwendet, wenn kein anderer Kanal konfiguriert ist.

Telemetrieinitialisierer (ASP.NET)

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:

  • AccountId legt die Eigenschaft AccountIdTelemetryInitializer fest.

  • AuthenticatedUserIdTelemetryInitializer legt die Eigenschaft AuthenticatedUserId so fest, wie sie vom JavaScript-SDK festgelegt wurde.

  • AzureRoleEnvironmentTelemetryInitializer aktualisiert die RoleName- und RoleInstance-Eigenschaften des Device-Kontexts für alle Telemetrieelemente mit Informationen, die aus der Azure-Laufzeitumgebung extrahiert wurden.

  • BuildInfoConfigComponentVersionTelemetryInitializer aktualisiert die Version-Eigenschaft des Component-Kontexts für alle Telemetrieelemente mit dem Wert, der aus der von MS Build erzeugten Datei BuildInfo.config extrahiert wurde.

  • ClientIpHeaderTelemetryInitializer aktualisiert die Ip-Eigenschaft des Location-Kontexts aller Telemetrieelemente basierend auf dem X-Forwarded-For-HTTP-Header der Anforderung.

  • DeviceTelemetryInitializer aktualisiert die folgenden Eigenschaften des Device-Kontexts für alle Telemetrieelemente.

    • Type ist auf PC festgelegt.
    • Id wird auf den Domänennamen des Computers festgelegt, auf dem die Webanwendung ausgeführt wird.
    • OemName wird auf den Wert festgelegt, der mithilfe von WMI aus dem Feld Win32_ComputerSystem.Manufacturer extrahiert wurde.
    • Model wird auf den Wert festgelegt, der mithilfe von WMI aus dem Feld Win32_ComputerSystem.Model extrahiert wurde.
    • NetworkType wird auf den Wert festgelegt, der aus der Eigenschaft NetworkInterface extrahiert wurde.
    • Language wird auf den Namen der Eigenschaft CurrentCulture festgelegt.

  • DomainNameRoleInstanceTelemetryInitializer aktualisiert die RoleInstance-Eigenschaft des Device-Kontexts 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 Operation.Id-Kontexteigenschaft aller verfolgten Telemetrieelemente, während eine Anforderung mit der automatisch generierten RequestTelemetry.Id behandelt wird.

  • 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, Session und 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.

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.

Telemetrieprozessoren (ASP.NET)

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

Sie können Ihre eigenen Telemetrieprozessoren schreiben.

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 Telemetrieprozessor für die Stichprobenentnahme (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>

ConnectionString

Sieh auch die Beispiele für Verbindungszeichenfolgencode.

InstrumentationKey

Hinweis

Am 31. März 2025 wird der Support für die auf Instrumentierungsschlüsseln basierende Erfassung eingestellt. Die Erfassung von Instrumentierungsschlüsseln funktioniert zwar weiterhin, wir stellen jedoch keine Updates und keinen Support mehr für das Feature bereit. Wechseln Sie zu Verbindungszeichenfolgen, damit Sie neue Funktionen nutzen können.

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 einem separaten Schlüssel.

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

Um den Schlüssel 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.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        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.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Um einen neuen Schlüssel abzurufen, erstellen Sie eine neue Ressource im Application Insights-Portal.

ApplicationId-Anbieter

Der Anbieter ist verfügbar ab v2.6.0.

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

Diese Funktion ist verfügbar, indem Sie TelemetryConfiguration.ApplicationIdProvider im Code oder in der Konfigurationsdatei festlegen.

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 der Konfigurationsdatei hinzugefügt, wenn Sie Microsoft.ApplicationInsights.DependencyCollector oder Microsoft.ApplicationInsights.Web installieren.

Diese Klasse enthält die optionale Eigenschaft ProfileQueryEndpoint. Standardmäßig ist sie auf https://dc.services.visualstudio.com/api/profiles/{0}/appId festgelegt. Wenn Sie einen Proxy für diese Konfiguration konfigurieren müssen, wird empfohlen, die Proxyfunktion für die Basisadresse zu verwenden und "/api/profiles/{0}/appId" einzufügen. {0} wird zur Laufzeit pro Anforderung durch den Instrumentierungsschlüssel ersetzt.

Beispielkonfiguration per „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 per 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 ein Instrumentierungsschlüssel angefordert wird, der in Ihrer Konfiguration nicht vorhanden ist.

Beispielkonfiguration per „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 per Code:

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

Konfigurieren der Momentaufnahmesammlung für ASP.NET-Anwendungen

Konfigurieren Sie eine Momentaufnahmesammlung für ASP.NET-Anwendungen.

Nächste Schritte

Weitere Informationen zur API