Diagnostizieren von Ausnahmen in Web-Apps mit Application Insights

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:

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.

Screenshot that shows right-clicking the project and choosing 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:

Screenshot that shows CodeLens notification of exceptions.

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.

Screenshot that shows a failures triage view on the Operations tab.

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.

Screenshot that shows the End-to-end transaction details tab.

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:

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 that shows the Search screen.

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

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.

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

Nächste Schritte