Application Insights für ASP.NET Core-Anwendungen aktivieren
In diesem Artikel wird beschrieben, wie Sie Application Insights für eine ASP.NET Core-Anwendung aktivieren, die als Azure-Web-App bereitgestellt wird. Diese Implementierung verwendet einen SDK-basierten Ansatz. Ein Ansatz mit automatischer Instrumentierung ist ebenfalls verfügbar.
Application Insights kann die folgenden Telemetriedaten aus Ihrer ASP.NET Core-Anwendung erfassen:
- Requests
- Abhängigkeiten
- Ausnahmen
- Leistungsindikatoren
- Heartbeats
- Protokolle
Für eine Beispielanwendung verwenden wir eine ASP.NET Core MVC-Anwendung, die auf net6.0
ausgerichtet ist. Die Anleitung in diesem Artikel können Sie jedoch für alle ASP.NET Core-Anwendungen nutzen. Wenn Sie den Workerdienst verwenden, befolgen Sie die hier angegebenen Anweisungen.
Hinweis
Ein OpenTelemetry-basierten .NET-Angebot ist verfügbar. Weitere Informationen
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.
Unterstützte Szenarios
Mit dem Application Insights SDK für ASP.NET Core können Sie Anwendungen unabhängig davon überwachen, wo und wie sie ausgeführt werden. Wenn Ihre Anwendung ausgeführt wird und über eine Netzwerkverbindung mit Azure verfügt, kann Application Insights daraus Telemetriedaten erfassen. Die Application Insights-Überwachung wird in allen Umgebungen unterstützt, in denen auch .NET Core unterstützt wird. Die folgenden Szenarien werden unterstützt:
- Betriebssystem: Windows, Linux oder Mac
- Hostingmethode: Prozessintern oder prozessextern
- Bereitstellungsmethode: Abhängig vom Framework oder eigenständig
- Webserver: IIS (Internetinformationsdienste) oder Kestrel
- Hostingplattform: Das Web-Apps-Feature von Azure App Service, Azure VM, Docker, Azure Kubernetes Service (AKS) usw.
- .NET Core-Version: Alle offiziell unterstützten .NET Core-Versionen, die sich nicht in der Vorschauphase befinden
- IDE: Visual Studio, Visual Studio Code oder Befehlszeile
Voraussetzungen
Für dieses Tutorial benötigen Sie Folgendes:
- Visual Studio 2022
- Die folgenden Visual Studio-Workloads:
- ASP.NET und Webentwicklung
- Datenspeicherung und -verarbeitung
- Azure-Entwicklung
- .NET 6.0
- Azure-Abonnement und -Benutzerkonto (mit der Möglichkeit, Ressourcen zu erstellen und zu löschen)
Bereitstellen von Azure-Ressourcen
Befolgen Sie den Leitfaden zum Bereitstellen der Beispielanwendung aus dem GitHub-Repository.
Um den Ressourcen global eindeutige Namen zu geben, wird einigen Ressourcen ein sechsstelliges Suffix zugewiesen. Bitte notieren Sie sich dieses Suffix zur späteren Verwendung in diesem Artikel.
Erstellen einer Application Insights-Ressource
Wählen Sie im Azure-Portal die Ressourcengruppe application-insights-azure-cafe aus.
Wählen Sie im oberen Symbolleistenmenü die Option + Erstellen aus.
Suchen Sie auf dem Bildschirm Ressource erstellen im Textfeld für die Marketplace-Suche nach Application Insights, und wählen Sie diese Option aus.
Wählen Sie auf dem Übersichtsbildschirm der Application Insights-Ressource die Option Erstellen aus.
Wählen Sie auf dem Bildschirm „Application Insights“ die Registerkarte Grundlagen aus. Füllen Sie das Formular mithilfe der folgenden Tabelle aus, und wählen Sie dann die Schaltfläche Überprüfen + erstellen. Felder, die in der nachstehenden Tabelle nicht angegeben sind, behalten möglicherweise ihre Standardwerte bei.
Feld Wert Name Geben Sie azure-cafe-application-insights-{SUFFIX}
ein, und ersetzen Sie {SUFFIX} durch den zuvor notierten Suffixwert.Region Wählen Sie dieselbe Region aus, die beim Bereitstellen der Artikelressourcen ausgewählt wurde. Log Analytics-Arbeitsbereich Wählen Sie azure-cafe-log-analytics-workspace aus. Alternativ können Sie einen neuen Log Analytics-Arbeitsbereich erstellen. Wurde die Validierung bestanden, wählen Sie Erstellen aus, um die Ressource bereitzustellen.
Nachdem die Ressource bereitgestellt wurde, kehren Sie zur Ressourcengruppe
application-insights-azure-cafe
zurück, und wählen Sie die von Ihnen bereitgestellte Application Insights-Ressource aus.Wählen Sie auf dem Übersichtsbildschirm der Application Insights-Ressource die Schaltfläche In Zwischenablage kopieren aus, um den Wert der Verbindungszeichenfolge zu kopieren. Sie verwenden den Wert der Verbindungszeichenfolge im nächsten Abschnitt dieses Artikels.
Konfigurieren der Anwendungseinstellung „Application Insights-Verbindungszeichenfolge“ im Web-App-Dienst
Kehren Sie zur Ressourcengruppe
application-insights-azure-cafe
zurück und öffnen Sie die App Service-Ressource azure-cafe-web-{SUFFIX}.Wählen Sie im linken Menü unter dem Abschnitt „Einstellungen“ die Option Konfiguration aus. Wählen Sie anschließend auf der Registerkarte Anwendungseinstellungen unter der Kopfzeile „Anwendungseinstellungen“ die Option + Neue Anwendungseinstellung aus.
Füllen Sie im Bereich „Anwendungseinstellung hinzufügen/bearbeiten“ das Formular folgendermaßen aus, und wählen Sie OK aus:
Feld Wert Name APPLICATIONINSIGHTS_CONNECTION_STRING Wert Fügen Sie den im vorherigen Abschnitt kopierten Wert der Application Insights-Verbindungszeichenfolge ein. Wählen Sie auf dem App Service-Konfigurationsbildschirm die Schaltfläche Speichern im Symbolleistenmenü aus. Wenn Sie aufgefordert werden, die Änderungen zu speichern, wählen Sie Weiter aus.
Installieren des NuGet-Pakets von Application Insights
Wir müssen die ASP.NET Core MVC-Webanwendung so konfigurieren, dass Telemetrie gesendet wird. Dies wird mithilfe des NuGet-Pakets mit Application Insights für ASP.NET Core-Webanwendungen erreicht.
Öffnen Sie
1 - Starter Application\src\AzureCafe.sln
in Visual Studio.Klicken Sie im Projektmappen-Explorer von Visual Studio mit der rechten Maustaste auf die AzureCafe-Projektdatei, und wählen Sie NuGet-Pakete verwalten aus.
Wählen Sie die Registerkarte Durchsuchen aus, und suchen Sie dann nach Microsoft.ApplicationInsights.AspNetCore. Wählen Sie Installieren aus, und akzeptieren Sie die Lizenzbedingungen. Es wird empfohlen, die neueste stabile Version zu verwenden. Vollständige Versionshinweise für das SDK finden Sie im Open-Source-GitHub-Repository.
Lassen Sie Visual Studio für den nächsten Abschnitt des Artikels offen.
Aktivieren der serverseitigen Telemetrie für Application Insights
Das NuGet-Paket mit Application Insights für ASP.NET Core-Webanwendungen enthält Features, um das Senden serverseitiger Telemetrie an die Application Insights-Ressource in Azure zu ermöglichen.
Öffnen Sie im Visual Studio-Projektmappen-Explorer die Datei Program.cs.
Fügen Sie den folgenden Code vor der
builder.Services.AddControllersWithViews()
-Anweisung ein. Dieser Code liest automatisch den Wert der Application Insights-Verbindungszeichenfolgen aus der Konfiguration. DieAddApplicationInsightsTelemetry
-Methode registriertApplicationInsightsLoggerProvider
mit dem integrierten Container für die Abhängigkeitsinjektion, der dann zum Erfüllen von ILogger- und ILogger<TCategoryName>-Implementierungsanforderungen verwendet wird.builder.Services.AddApplicationInsightsTelemetry();
Tipp
Weitere Informationen über die Konfigurationsoptionen in ASP.NET Core.
Aktivieren der clientseitigen Telemetrie für Webanwendungen
Wenn Sie die vorherigen Schritte ausgeführt haben, können Sie serverseitige Telemetriedaten erfassen. Die Beispielanwendung verfügt über clientseitige Komponenten. Führen Sie daher die unten angegebenen Schritte aus, um mit dem Erfassen von Nutzungstelemetriedaten zu beginnen.
Öffnen Sie
\Views\_ViewImports.cshtml
im Projektmappen-Explorer von Visual Studio.Fügen Sie am Ende der bestehenden Datei folgenden Code hinzu.
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
Um die clientseitige Überwachung für Ihre Anwendung ordnungsgemäß zu aktivieren, öffnen Sie
\Views\Shared\_Layout.cshtml
und fügen den folgenden Code direkt vor dem schließenden<\head>
-Tag im Projektmappen-Explorer von Visual Studio ein. Der JavaScript-Codeausschnitt muss in den Abschnitt<head>
jeder Anwendungsseite eingefügt sein, die Sie überwachen möchten.@Html.Raw(JavaScriptSnippet.FullScript)
Tipp
Eine Alternative zur Verwendung von
FullScript
istScriptBody
. Verwenden SieScriptBody
, wenn Sie das<script>
-Tag so steuern müssen, dass eine Inhaltssicherheitsrichtlinie festgelegt wird:<script> // apply custom changes to this script tag. @Html.Raw(JavaScriptSnippet.ScriptBody) </script>
Hinweis
Die JavaScript-Einschleusung bietet eine Standardkonfigurationserfahrung. Wenn Sie eine Konfiguration benötigen, die über das Festlegen der Verbindungszeichenfolge hinausgeht, müssen Sie die automatische Einschleusung wie oben beschrieben entfernen und das JavaScript SDK manuell hinzufügen.
Aktivieren der Überwachung von Datenbankabfragen
Bei der Untersuchung von Ursachen für Leistungsbeeinträchtigungen müssen Erkenntnisse zu Datenbankaufrufen einbezogen werden. Aktivieren Sie die Überwachung durch Konfiguration des Abhängigkeitsmoduls. Die Abhängigkeitsüberwachung, einschließlich SQL, ist standardmäßig aktiviert.
Führen Sie folgende Schritte aus, um den vollständigen Text der SQL-Abfrage zu erfassen.
Hinweis
Der SQL-Text kann vertrauliche Daten wie Kennwörter und PII enthalten. Achten Sie beim Aktivieren dieses Features darauf.
Öffnen Sie im Visual Studio-Projektmappen-Explorer die Datei Program.cs.
Fügen Sie am Anfang der Datei die folgende
using
-Anweisung hinzu.using Microsoft.ApplicationInsights.DependencyCollector;
Fügen Sie unmittelbar nach dem Code
builder.Services.AddApplicationInsightsTelemetry()
Folgendes ein, um die SQL-Befehlstextinstrumentierung zu aktivieren.builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
Ausführen der Azure Cafe-Webanwendung
Nach dem Bereitstellen des Webanwendungscodes wird die Telemetrie an Application Insights übertragen. Mit dem Application Insights SDK werden eingehende Webanforderungen an die Anwendung automatisch erfasst.
Klicken Sie im Projektmappen-Explorer von Visual Studio mit der rechten Maustaste auf das Projekt AzureCafe, und wählen Sie im Kontextmenü Veröffentlichen aus.
Wählen Sie Veröffentlichen aus, um den neuen Code zu Azure App Service höherzustufen.
Wenn die Azure Cafe-Webanwendung erfolgreich veröffentlicht wurde, wird ein neues Browserfenster für die Azure Cafe-Webanwendung geöffnet.
Führen Sie zum Generieren von Telemetriedaten die folgenden Schritte in der Webanwendung aus, um eine Bewertung hinzuzufügen.
Um die Speisekarte und Bewertungen eines Cafes anzuzeigen, wählen Sie Details neben einem Cafe aus.
Um Bewertungen anzuzeigen und hinzuzufügen, wählen Sie auf dem Cafe-Bildschirm die Registerkarte Bewertungen. Wählen Sie die Schaltfläche Bewertung hinzufügen, um eine Bewertung hinzuzufügen.
Geben Sie im Dialogfeld „Bewertung erstellen“ einen Namen, eine Bewertung und Kommentare ein, und laden Sie ein Foto für die Bewertung hoch. Wenn Sie fertig sind, wählen Sie Bewertung hinzufügen aus.
Wenn Sie zusätzliche Telemetriedaten generieren müssen, fügen Sie zusätzliche Bewertungen hinzu.
Livemetriken
Mit Livemetriken kann schnell überprüft werden, ob die Application Insights-Überwachung ordnungsgemäß konfiguriert ist. Livemetriken zeigen die CPU-Auslastung des laufenden Prozesses jedoch nahezu in Echtzeit an. Außerdem können andere Telemetriedaten wie z. B. Anforderungen, Abhängigkeiten und Ablaufverfolgungen angezeigt werden. Beachten Sie, dass es einige Minuten dauern kann, bis die Telemetriedaten im Portal und in der Analyse angezeigt werden.
Anzeigen der Anwendungsübersicht
Die Beispielanwendung ruft mehrere Azure-Ressourcen auf, einschließlich Azure SQL, Azure Blob Storage und Azure Language Service (für die Bewertung der Stimmungsanalyse).
Application Insights untersucht eingehende Telemetriedaten und kann eine visuelle Karte erkannter Systemintegrationen generieren.
Melden Sie sich beim Azure-Portal an.
Öffnen Sie die Ressourcengruppe für die Beispielanwendung
application-insights-azure-cafe
.Wählen Sie in der Liste der Ressourcen die
azure-cafe-insights-{SUFFIX}
-Application Insights-Ressource aus.Wählen Sie im linken Menü unter der Überschrift Untersuchen das Element Anwendungszuordnung aus. Betrachten Sie die generierte Anwendungsübersicht.
Anzeigen von HTTP-Aufrufen und Datenbank-SQL-Befehlstext
Öffnen Sie die Application Insights-Ressource im Azure-Portal.
Wählen Sie im linken Menü unter der Kopfzeile Untersuchen die Option Leistung aus.
Die Registerkarte Vorgänge enthält Details zu den von der Anwendung empfangenen HTTP-Aufrufen. Um zwischen Server- und Browseransichten (clientseitigen Ansichten) der Daten zu wechseln, verwenden Sie den Umschalter „Server/Browser“.
Wählen Sie einen Vorgang aus der Tabelle aus, und zeigen Sie ein Beispiel der Anforderung detaillierter an.
Die End-to-End-Transaktion wird für die ausgewählte Anforderung angezeigt. In diesem Fall wurde eine Bewertung einschließlich eines Bilds erstellt. Daher umfasst es Aufrufe an Azure Storage und den Sprachdienst (für die Stimmungsanalyse). Zudem enthält Sie Datenbankaufrufe in SQL Azure, um die Überprüfung beizubehalten. In diesem Beispiel zeigt das erste ausgewählte Ereignis Informationen in Relation zum HTTP POST-Aufruf an.
Wählen Sie ein SQL-Element aus, um den SQL-Befehlstext zu überprüfen, der an die Datenbank ausgestellt wurde.
Wählen Sie optional Abhängigkeitsanforderungen (ausgehend) für Azure Storage oder den Sprachdienst aus.
Kehren Sie zum Bildschirm Leistung zurück, und wählen Sie die Registerkarte Abhängigkeiten aus, um Aufrufe externer Ressourcen zu untersuchen. Beachten Sie, dass die Tabelle „Vorgänge“ Aufrufe von Stimmungsanalyse, Blob Storage und Azure SQL enthält.
Anwendungsprotokollierung mit Application Insights
Übersicht über die Protokollierung
Application Insights ist eine Art Protokollierungsanbieter, der für ASP.NET Core-Anwendungen verfügbar ist, die für Anwendungen verfügbar werden, wenn das NuGet-Paket Application Insights für ASP.NET Core installiert und die serverseitige Telemetriesammlung aktiviert ist.
Als Erinnerung registriert der folgende Code in Program.cs den ApplicationInsightsLoggerProvider
mit integriertem Container für die Abhängigkeitsinjektion.
builder.Services.AddApplicationInsightsTelemetry();
Da ApplicationInsightsLoggerProvider
als Protokollierungsanbieter registriert ist, ist die App bereit, sich anhand der Konstruktorinjektion mit ILogger oder der generischen Alternative ILogger<TCategoryName> bei Application Insights anzumelden.
Hinweis
Standardmäßig ist der Protokollanbieter ist so konfiguriert, dass Protokollereignisse mit einem Schweregrad von LogLevel.Warning oder höher automatisch erfasst werden.
Betrachten Sie den folgenden Beispielcontroller. Er veranschaulicht die Injektion von ILogger, die mit ApplicationInsightsLoggerProvider
behoben wird, der beim Container für die Abhängigkeitsinjektion registriert ist. Beachten Sie bei der Get-Methode, dass Informations-, Warnungs- und Fehlermeldungen aufgezeichnet werden.
Hinweis
Standardmäßig wird die Ablaufverfolgung auf Informationsebene nicht aufgezeichnet. Nur die Warnungs- und höheren Ebenen werden erfasst.
using Microsoft.AspNetCore.Mvc;
[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
private readonly ILogger _logger;
public ValuesController(ILogger<ValuesController> logger)
{
_logger = logger;
}
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
//Info level traces are not captured by default
_logger.LogInformation("An example of an Info trace..");
_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 Logging in ASP.NET Core (Protokollierung in ASP.NET Core).
Anzeigen von Protokollen in Application Insights
Der ValuesController oben wird mit der Beispielanwendung bereitgestellt und befindet sich im Ordner Controller des Projekts.
Öffnen Sie mithilfe eines Internetbrowsers die Beispielanwendung. Hängen Sie in der Adressleiste
/api/Values
an, und drücken Sie die Eingabetaste.Warten Sie im Azure-Portal einige Momente, und wählen Sie dann die Application Insights-Ressource azure-cafe-insights-{SUFFIX} aus.
Wählen Sie im linken Menü der Application Insights-Ressource im Abschnitt Überwachung die Option Protokolle aus.
Doppelklicken Sie im Bereich Tabellen auf die Tabelle Ablaufverfolgung, die sich unter der Struktur Application Insights befindet.
Ändern Sie die Abfrage, um Ablaufverfolgungen für den Controller Werte wie folgt abzurufen, und wählen Sie dann Ausführen aus, um die Ergebnisse zu filtern.
traces | where operation_Name == "GET Values/Get"
In den Ergebnissen werden die im Controller vorhandenen Protokollnachrichten angezeigt. Ein Protokollschweregrad von 2 gibt eine Warnstufe an. Ein Protokollgrad von 3 gibt eine Fehlerstufe an.
Alternativ kann die Abfrage auch geschrieben werden, um Ergebnisse basierend auf der Kategorie des Protokolls abzurufen. Standardmäßig ist die Kategorie der vollqualifizierte Name der Klasse, in der der ILogger eingefügt wird. In diesem Fall lautet der Name der Kategorie ValuesController (wenn der Klasse ein Namespace zugeordnet ist, wird dem Namen der Namespace vorangestellt). Schreiben Sie die folgende Abfrage neu, und führen Sie noch einmal aus, um Ergebnisse basierend auf der Kategorie abzurufen.
traces | where customDimensions.CategoryName == "ValuesController"
Steuern der Ebene der Protokolle, die an Application Insights gesendet werden
ILogger
-Implementierungen verfügen über einen integrierten Mechanismus zum Anwenden der Protokollfilterung. Mit dieser Filterung können Sie die Protokolle steuern, die an jeden registrierten Anwender gesendet werden, einschließlich des Application Insights-Anbieters. Sie können die Filterung entweder in der Konfiguration (mittels einer appsettings.json-Datei) oder im Code verwenden. Weitere Informationen zu Protokollebenen und Anleitungen zur entsprechenden Verwendung finden Sie in der Dokumentation zur Protokollebene.
In den folgenden Beispielen wird gezeigt, wie Filterregeln auf die ApplicationInsightsLoggerProvider
-Ebene der Protokolle angewendet werden, die an Application Insights gesendet werden.
Erstellen von Filterregeln mit Konfiguration
Der ApplicationInsightsLoggerProvider
-Alias wird in der Konfiguration als ApplicationInsights angezeigt. Im folgenden Abschnitt der Datei appsettings.json wird die Standardprotokollebene für alle Anbieter auf LogLevel.Warning festgelegt. Bei der Konfiguration für den ApplicationInsights-Anbieter wird insbesondere für Kategorien, die mit „ValuesController“ beginnen, dieser Standardwert mit LogLevel.Error und höher überschrieben.
{
//... additional code removed for brevity
"Logging": {
"LogLevel": { // No provider, LogLevel applies to all the enabled providers.
"Default": "Warning"
},
"ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
"LogLevel": {
"ValuesController": "Error" //Log Level for the "ValuesController" category
}
}
}
}
Wenn Sie die Beispielanwendung mit dem voranstehenden Code in appsettings.json bereitstellen, wird nur die Fehlerablaufverfolgung zurückgegeben, die bei der Interaktion mit ValuesController an Application Insights gesendet wird. Dies liegt daran, dass LogLevel für die Kategorie ValuesController auf Fehler festgelegt ist. Daher wird die Ablaufverfolgung Warnung unterdrückt.
Deaktivieren der Protokollierung in Application Insights
Um die Protokollierung mithilfe der Konfiguration zu deaktivieren, legen Sie alle LogLevel-Werte auf „Keine“ fest.
{
//... additional code removed for brevity
"Logging": {
"LogLevel": { // No provider, LogLevel applies to all the enabled providers.
"Default": "None"
},
"ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
"LogLevel": {
"ValuesController": "None" //Log Level for the "ValuesController" category
}
}
}
}
Legen Sie im Code den Standard für ApplicationInsightsLoggerProvider
und alle nachfolgenden Protokollebenen auf Keine fest.
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);
Open Source SDK
Informationen zu den neuesten Updates und Fehlerbehebungen finden Sie in den Versionshinweisen.
Nächste Schritte
- Machen Sie sich Benutzerflows vertraut, um die Benutzernavigation in Ihrer App nachzuvollziehen.
- Konfigurieren Sie eine Momentaufnahmensammlung, um den Status des Quellcodes und der Variablen zu dem Zeitpunkt anzuzeigen, an dem eine Ausnahme ausgelöst wurde.
- Verwenden Sie die API, um Ihre eigenen Ereignisse und Metriken für eine detaillierte Ansicht der Leistung und Nutzung Ihrer App zu senden.
- Übersicht der Verfügbarkeit
- Dependency Injection in ASP.NET Core
- Protokollierung in ASP.NET Core
- .NET-Ablaufverfolgungsprotokolle in Application Insights
- Automatische Instrumentierung für Application Insights