Diagnostizieren von Ausnahmen in Web-Apps mit Application Insights
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 und unserer OpenTelemetry Roadmap. Migrationsleitfaden sind für .NET, Node.js und Python verfügbar.
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 Artikel 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.
Serverseitig
Berücksichtigen Sie die folgenden Szenarien, damit Ausnahmen von Ihrer serverseitigen Anwendung gemeldet werden:
- Fügen Sie die Application Insights-Erweiterung für Azure-Web-Apps hinzu.
- Fügen Sie die Erweiterung zur Anwendungsüberwachung für Azure-VMs und für in Azure Virtual Machine Scale Sets-IIS gehostete Apps hinzu.
- Installieren Sie das Application Insights SDK in Ihrem App-Code, führen Sie den Application Insights-Agent für IIS-Webserver aus, oder aktivieren Sie den Java-Agent für Java-Web-Apps.
Clientseitig
Das JavaScript-SDK bietet die Möglichkeit zur clientseitigen Berichterstellung für Ausnahmen, die in Webbrowsern auftreten. Informationen zum Einrichten der Berichterstellung für Ausnahmen auf dem Client finden Sie unter Application Insights für Webseiten.
Anwendungsframeworks
Bei einigen Anwendungsframeworks ist weitere Konfiguration erforderlich. Beachten Sie die folgende Technologien:
Wichtig
Dieser Artikel konzentriert sich speziell auf .NET Framework-Apps aus Codebeispielperspektive. Einige der Methoden, die für .NET Framework eingesetzt werden, sind im .NET Core SDK veraltet. Weitere Informationen zum Erstellen von Apps mit .NET Core finden Sie in der Dokumentation zum .NET Core SDK.
Diagnostizieren von Ausnahmen mithilfe von Visual Studio
Öffnen Sie in Visual Studio die Anwendungsprojektmappe. Führen Sie die App entweder auf dem Server oder Ihrem Entwicklungscomputer aus, indem Sie F5 drücken. Erstellen Sie die Ausnahme neu.
Öffnen Sie in Visual Studio das Application Insights-Fenster Telemetriedaten suchen. Klicken Sie während des Debuggens auf das Dropdownfeld Application Insights.
Wählen Sie einen Ausnahmebericht aus, um dessen Stapelüberwachung anzuzeigen. Klicken Sie in der Stapelüberwachung auf einen Zeilenverweis, um die relevante Codedatei zu öffnen.
Wenn CodeLens aktiviert ist, werden Daten zu den Ausnahmen angezeigt:
Diagnostizieren von Fehlern mithilfe des Azure-Portals
Application Insights umfasst eine zusammengestellte Application Performance Management-Benutzeroberfläche, die Sie beim Diagnostizieren von Fehlern in Ihren überwachten Anwendungen unterstützt. Um zu beginnen, wählen Sie im Application Insights-Ressourcenmenü auf der linken Seite unter Untersuchen die Option Fehler aus.
Daraufhin wird angezeigt, welche Fehlerratentrends es bei Ihren Anforderungen gibt, bei wie vielen ein Fehler auftritt und wie viele Benutzer davon betroffen sind. Die Gesamtansicht zeigt einige der nützlichsten Verteilungen, die für den ausgewählten fehlgeschlagenen Vorgang spezifisch sind. Sie zeigt die drei häufigsten Antwortcodes, die drei häufigsten Ausnahmetypen und die drei am häufigsten fehlschlagenden Abhängigkeitstypen.
Klicken Sie auf den entsprechenden Link, um repräsentative Beispiele für jede dieser Teilmengen von Vorgängen zu überprüfen. Sie können zum Diagnostizieren von Ausnahmen beispielsweise die Anzahl einer bestimmten Ausnahme auswählen, die auf der Registerkarte End-to-End-Transaktionsdetails angezeigt werden soll.
Alternativ zur Anzeige von Ausnahmen eines bestimmten fehlgeschlagenen Vorgangs können Sie mit der Ansicht Gesamt für die Ausnahmen beginnen, indem Sie im oberen Bereich zur Registerkarte Ausnahmen wechseln. Hier können Sie alle Ausnahmen anzeigen, die für Ihre überwachte App erfasst wurden.
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:
- TelemetryClient.TrackEvent wird normalerweise zum Überwachen von Verwendungsmustern verwendet, jedoch werden die damit gesendeten Daten in der Diagnosesuche auch unter Benutzerdefinierte Ereignisse angezeigt. Ereignisse werden benannt und können Zeichenfolgeneigenschaften und numerische Metriken aufweisen, nach denen Sie Ihre Diagnosesuchvorgänge filtern können.
- TelemetryClient.TrackTrace können Sie längere Daten wie POST-Informationen senden.
- TelemetryClient.TrackException sendet Ausnahmedetails wie Stapelüberwachungen an Application Insights.
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.
Hinweis
Wenn die Anwendung viele 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 desselben Vorgangs sind, werden als Gruppe aus- oder abgewählt, sodass Sie zwischen verknüpften 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:
- Installieren Sie das SDK in Ihrem Anwendungsprojekt.
- Fügen Sie Code in die Anwendung ein, um Microsoft.ApplicationInsights.TrackTrace() aufzurufen. Senden Sie die POST-Daten im "message"-Parameter. Es gibt eine Größenbeschränkung, daher sollten Sie versuchen, nur die notwendigen Daten zu senden.
- Wenn Sie eine fehlerhafte Anforderung untersuchen, suchen Sie die zugehörigen Ablaufverfolgungen.
Erfassen von Ausnahmen und zugehörigen Diagnosedaten
Zunächst werden im Portal nicht alle Ausnahmen angezeigt, die in Ihrer App zu Fehlern führen. Sie sehen alle Browserausnahmen, wenn Sie das JavaScript SDK auf Ihren Webseiten verwenden. Die meisten Serverausnahmen werden jedoch von IIS abgefangen, und Sie müssen ein wenig Code schreiben, um sie anzuzeigen.
Ihre 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.
try
{
// ...
}
catch (ex)
{
appInsights.trackException(ex, "handler loc",
{
Game: currentGame.Name,
State: currentGame.State.ToString()
});
}
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);
}
Dim telemetry = New TelemetryClient
Try
' ...
Catch ex as Exception
' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("Game", currentGame.Name)
Dim measurements = New Dictionary (Of String, Double)
measurements.Add("Users", currentGame.Users.Count)
' Send the exception telemetry:
telemetry.TrackException(ex, properties, measurements)
End Try
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.
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
}
}
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());
}
}
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());
}
}
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.
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());
}
}
}
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());
}
}
}
Als Alternativen können Sie folgende Aktionen ausführen:
- Ersetzen Sie die einzige
ExceptionHandler-Instanz durch eine benutzerdefinierte Implementierung vonIExceptionHandler. 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
}
}
Ausnahmeleistungsindikatoren
Wenn Sie den Azure Monitor Application Insights-Agent 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.