Konfigurieren des Application Insights-SDK mit „ApplicationInsights.config“ oder „.xml“
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.
Achtung
Wir empfehlen die Azure Monitor OpenTelemetry Distro für neue Anwendungen oder Kunden, um Azure Monitor Application Insights zu betreiben. Die Azure Monitor OpenTelemetry Distro 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.
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.
Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
- NuGet-Paket Microsoft.ApplicationInsights.DependencyCollector
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.
Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
- NuGet-Paket Microsoft.ApplicationInsights.PerfCounterCollector
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.
Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
- Application Insights Windows Server -NuGet-Paket.
Nachverfolgung von Webanforderungen
Die Nachverfolgung von Webanforderungen meldet die Antwortzeit und den Ergebniscode von HTTP-Anforderungen.
Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
- Microsoft.ApplicationInsights.Web -NuGet-Paket
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.
Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
- Microsoft.ApplicationInsights.EventSourceListener
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.EtwCollector.EtwCollectorTelemetryModule
- Microsoft.ApplicationInsights.EtwCollector
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 EigenschaftAccountIdTelemetryInitializer
fest.AuthenticatedUserIdTelemetryInitializer
legt die EigenschaftAuthenticatedUserId
so fest, wie sie vom JavaScript-SDK festgelegt wurde.AzureRoleEnvironmentTelemetryInitializer
aktualisiert dieRoleName
- undRoleInstance
-Eigenschaften desDevice
-Kontexts für alle Telemetrieelemente mit Informationen, die aus der Azure-Laufzeitumgebung extrahiert wurden.BuildInfoConfigComponentVersionTelemetryInitializer
aktualisiert dieVersion
-Eigenschaft desComponent
-Kontexts für alle Telemetrieelemente mit dem Wert, der aus der von MS Build erzeugten DateiBuildInfo.config
extrahiert wurde.ClientIpHeaderTelemetryInitializer
aktualisiert dieIp
-Eigenschaft desLocation
-Kontexts aller Telemetrieelemente basierend auf demX-Forwarded-For
-HTTP-Header der Anforderung.DeviceTelemetryInitializer
aktualisiert die folgenden Eigenschaften desDevice
-Kontexts für alle Telemetrieelemente.Type
ist aufPC
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 FeldWin32_ComputerSystem.Manufacturer
extrahiert wurde.Model
wird auf den Wert festgelegt, der mithilfe von WMI aus dem FeldWin32_ComputerSystem.Model
extrahiert wurde.NetworkType
wird auf den Wert festgelegt, der aus der EigenschaftNetworkInterface
extrahiert wurde.Language
wird auf den Namen der EigenschaftCurrentCulture
festgelegt.
DomainNameRoleInstanceTelemetryInitializer
aktualisiert dieRoleInstance
-Eigenschaft desDevice
-Kontexts für alle Telemetrieelemente mit dem Domänennamen des Computers, auf dem die Webanwendung ausgeführt wird.OperationNameTelemetryInitializer
aktualisiert die EigenschaftName
vonRequestTelemetry
und die EigenschaftName
des KontextsOperation
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
oderOperationCorrelationTelemetryInitializer
aktualisiert dieOperation.Id
-Kontexteigenschaft aller verfolgten Telemetrieelemente, während eine Anforderung mit der automatisch generiertenRequestTelemetry.Id
behandelt wird.SessionTelemetryInitializer
aktualisiert die EigenschaftId
des KontextsSession
für alle Telemetrieelemente mit Werten, die aus dem Cookieai_session
extrahiert werden. Dieses wird vomApplicationInsights
-JavaScript-Instrumentationscode generiert, der im Browser des Benutzers ausgeführt wird.SyntheticTelemetryInitializer
oderSyntheticUserAgentTelemetryInitializer
aktualisiert die KontexteigenschaftenUser
,Session
undOperation
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 EigenschaftenId
undAcquisitionDate
des KontextsUser
für alle Telemetrieelemente mit Werten, die aus dem Cookieai_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.