Uitzonderingen in web-apps diagnosticeren met Application Insights

  • Artikel

Notitie

De volgende documentatie is afhankelijk van de klassieke Application Insights-API. Het langetermijnplan voor Application Insights is het verzamelen van gegevens met behulp van OpenTelemetry. Zie Azure Monitor OpenTelemetry inschakelen voor .NET-, Node.js-, Python- en Java-toepassingen voor meer informatie.

Uitzonderingen in webtoepassingen kunnen worden gerapporteerd met Application Insights. U kunt mislukte aanvragen correleren met uitzonderingen en andere gebeurtenissen op zowel de client als de server, zodat u snel een diagnose kunt stellen van de oorzaken. In dit artikel leert u hoe u uitzonderingsrapportage instelt, expliciet uitzonderingen rapporteert, fouten diagnosticeert en meer.

Uitzonderingsrapportage instellen

U kunt Application Insights instellen om uitzonderingen te rapporteren die optreden op de server of de client. Afhankelijk van het platform waarop uw toepassing afhankelijk is, hebt u de juiste extensie of SDK nodig.

Serverzijde

Houd rekening met de volgende scenario's om uitzonderingen te hebben gerapporteerd vanuit uw toepassing aan de serverzijde:

Clientzijde

De JavaScript SDK biedt de mogelijkheid voor rapportage aan de clientzijde van uitzonderingen die optreden in webbrowsers. Zie Application Insights voor webpagina's om uitzonderingsrapportage op de client in te stellen.

Toepassingsframeworks

Bij sommige toepassingsframeworks is meer configuratie vereist. Houd rekening met de volgende technologieën:

Belangrijk

Dit artikel is specifiek gericht op .NET Framework-apps vanuit het perspectief van een codevoorbeeld. Sommige methoden die voor .NET Framework werken, zijn verouderd in de .NET Core SDK. Zie de .NET Core SDK-documentatie wanneer u apps bouwt met .NET Core voor meer informatie.

Uitzonderingen diagnosticeren met Visual Studio

Open de app-oplossing in Visual Studio. Voer de app uit op uw server of op uw ontwikkelcomputer met behulp van F5. Maak de uitzondering opnieuw.

Open het telemetrievenster van Application Insights Search in Visual Studio. Selecteer tijdens foutopsporing de vervolgkeuzelijst Application Insights .

Screenshot that shows right-clicking the project and choosing Application Insights.

Selecteer een uitzonderingsrapport om de bijbehorende stacktracering weer te geven. Als u het relevante codebestand wilt openen, selecteert u een regelreferentie in de stacktracering.

Als CodeLens is ingeschakeld, ziet u gegevens over de uitzonderingen:

Screenshot that shows CodeLens notification of exceptions.

Fouten diagnosticeren met behulp van Azure Portal

Application Insights wordt geleverd met een gecureerde Application Performance Management-ervaring om u te helpen bij het diagnosticeren van fouten in uw bewaakte toepassingen. Als u wilt beginnen, selecteert u in het resourcemenu van Application Insights aan de linkerkant onder Onderzoeken de optie Fouten .

U ziet de foutenpercentagetrends voor uw aanvragen, hoeveel van deze aanvragen mislukken en hoeveel gebruikers worden beïnvloed. In de weergave Algemeen ziet u enkele van de nuttigste distributies die specifiek zijn voor de geselecteerde mislukte bewerking. U ziet de drie belangrijkste antwoordcodes, de drie belangrijkste uitzonderingstypen en de drie belangrijkste mislukte afhankelijkheidstypen.

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

Als u representatieve voorbeelden voor elk van deze subsets van bewerkingen wilt bekijken, selecteert u de bijbehorende koppeling. Als u bijvoorbeeld uitzonderingen wilt diagnosticeren, kunt u het aantal van een bepaalde uitzondering selecteren dat moet worden weergegeven op het tabblad Details van de end-to-end-transactie .

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

U kunt ook beginnen met de algemene weergave van uitzonderingen door naar het tabblad Uitzonderingen bovenaan over te schakelen naar het tabblad Uitzonderingen . Hier ziet u alle uitzonderingen die zijn verzameld voor uw bewaakte app.

Aangepaste tracerings- en logboekgegevens

Als u diagnostische gegevens wilt ophalen die specifiek zijn voor uw app, kunt u code invoegen om uw eigen telemetriegegevens te verzenden. Uw aangepaste telemetrie- of logboekgegevens worden weergegeven in diagnostische zoekopdrachten naast de aanvraag, paginaweergave en andere automatisch verzamelde gegevens.

Met behulp van de Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, hebt u verschillende API's beschikbaar:

  • TelemetryClient.TrackEvent wordt doorgaans gebruikt voor het bewaken van gebruikspatronen, maar de gegevens die worden verzonden, worden ook weergegeven onder Aangepaste gebeurtenissen in diagnostische zoekopdrachten. Gebeurtenissen hebben een naam en kunnen tekenreekseigenschappen en numerieke metrische gegevens bevatten waarop u uw diagnostische zoekopdrachten kunt filteren.
  • TelemetryClient.TrackTrace hiermee kunt u langere gegevens, zoals POST-informatie, verzenden.
  • TelemetryClient.TrackException verzendt uitzonderingsdetails, zoals stacktraceringen naar Application Insights.

Als u deze gebeurtenissen wilt zien, opent u Zoeken in het linkermenu. Selecteer de vervolgkeuzelijst Gebeurtenistypen en kies vervolgens Aangepaste gebeurtenis, Tracering of Uitzondering.

Screenshot that shows the Search screen.

Notitie

Als uw app veel telemetrie genereert, vermindert de module voor adaptieve steekproeven automatisch het volume dat naar de portal wordt verzonden door slechts een representatieve fractie van gebeurtenissen te verzenden. Gebeurtenissen die deel uitmaken van dezelfde bewerking, worden geselecteerd of gedeselecteerd als een groep, zodat u tussen gerelateerde gebeurtenissen kunt navigeren. Zie Sampling in Application Insights voor meer informatie.

Post-gegevens aanvragen bekijken

Aanvraagdetails bevatten niet de gegevens die naar uw app worden verzonden in een POST-aanroep. Ga als volgt te werk om deze gegevens te laten melden:

  • Installeer de SDK in uw toepassingsproject.
  • Voeg code in uw toepassing in om Microsoft.ApplicationInsights.TrackTrace() aan te roepen. Verzend de POST-gegevens in de berichtparameter. Er is een limiet voor de toegestane grootte, dus probeer alleen de essentiële gegevens te verzenden.
  • Wanneer u een mislukte aanvraag onderzoekt, zoekt u de bijbehorende traceringen.

Uitzonderingen en gerelateerde diagnostische gegevens vastleggen

In eerste instantie ziet u in de portal niet alle uitzonderingen die fouten veroorzaken in uw app. U ziet browser-uitzonderingen als u de JavaScript SDK op uw webpagina's gebruikt. Maar de meeste serveruitzonderingen worden gevangen door IIS en u moet een beetje code schrijven om ze te zien.

U kunt:

  • Logboekuitzondering expliciet door code in uitzonderingshandlers in te voegen om de uitzonderingen te rapporteren.
  • Maak automatisch uitzonderingen door uw ASP.NET framework te configureren. De benodigde toevoegingen zijn verschillend voor verschillende typen frameworks.

Expliciet uitzonderingen rapporteren

De eenvoudigste manier om te rapporteren is door een aanroep in trackException() te voegen in een uitzonderingshandler.

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

De eigenschappen en maatparameters zijn optioneel, maar ze zijn handig voor het filteren en toevoegen van extra informatie. Als u bijvoorbeeld een app hebt die meerdere games kan uitvoeren, kunt u alle uitzonderingsrapporten vinden die betrekking hebben op een bepaalde game. U kunt zoveel items toevoegen als u aan elke woordenlijst wilt toevoegen.

Browseruitzonderingen

De meeste browseruitzondering worden gerapporteerd.

Als uw webpagina scriptbestanden bevat van netwerken voor contentlevering of andere domeinen, controleert u of uw scripttag het kenmerk crossorigin="anonymous" heeft en of de server CORS-headers verzendt. Met dit gedrag kunt u een stacktracering en details ophalen voor niet-verwerkte JavaScript-uitzonderingen van deze resources.

Uw telemetrieclient opnieuw gebruiken

Notitie

U wordt aangeraden de TelemetryClient instantie eenmalig te instantiëren en opnieuw te gebruiken gedurende de levensduur van een toepassing.

Met afhankelijkheidsinjectie (DI) in .NET, de juiste .NET SDK en de juiste configuratie van Application Insights voor DI, kunt u de TelemetryClient parameter als constructor vereisen.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

In het voorgaande voorbeeld wordt de TelemetryClient in de ExampleController klasse geïnjecteerd.

Webformulieren

Voor webformulieren kan de HTTP-module de uitzonderingen verzamelen wanneer er geen omleidingen zijn geconfigureerd met CustomErrors. Wanneer u echter actieve omleidingen hebt, voegt u de volgende regels toe aan de Application_Error functie in Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

In het voorgaande voorbeeld is het _telemetryClient een variabele met klassebereik van het type TelemetryClient.

MVC

Vanaf Application Insights Web SDK versie 2.6 (bèta 3 en hoger) verzamelt Application Insights automatisch niet-verwerkte uitzonderingen die zijn gegenereerd in de MVC 5+-controllersmethoden. Als u eerder een aangepaste handler hebt toegevoegd om dergelijke uitzonderingen bij te houden, kunt u deze verwijderen om dubbele tracering van uitzonderingen te voorkomen.

Er zijn verschillende scenario's waarin een uitzonderingsfilter fouten niet correct kan verwerken wanneer er uitzonderingen worden gegenereerd:

  • Van controllerconstructors
  • Van berichthandlers
  • Tijdens routering
  • Tijdens serialisatie van antwoordinhoud
  • Tijdens het opstarten van de toepassing
  • Achtergrondtaken

Alle uitzonderingen die door de toepassing worden verwerkt , moeten nog steeds handmatig worden bijgehouden. Niet-verwerkte uitzonderingen die afkomstig zijn van controllers resulteren doorgaans in een reactie van 500 'Interne serverfout'. Als een dergelijk antwoord handmatig is samengesteld als gevolg van een verwerkte uitzondering of helemaal geen uitzondering, wordt deze bijgehouden in de bijbehorende aanvraagtelemetrie met ResultCode 500. De Application Insights SDK kan echter geen overeenkomstige uitzondering bijhouden.

Ondersteuning voor eerdere versies

Als u MVC 4 (en eerder) van Application Insights Web SDK 2.5 (en eerder) gebruikt, raadpleegt u de volgende voorbeelden om uitzonderingen bij te houden.

Als de CustomErrors-configuratie is Off, zijn uitzonderingen beschikbaar voor de HTTP-module die moet worden verzameld. Als het echter (standaard) is RemoteOnly , Onwordt de uitzondering gewist en is de uitzondering niet beschikbaar voor het automatisch verzamelen van Application Insights. U kunt dit gedrag oplossen door de klasse System.Web.Mvc.HandleErrorAttribute te overschrijven en de overschreven klasse toe te passen, zoals hier wordt weergegeven voor de verschillende MVC-versies (zie de GitHub-bron):

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

Vervang het kenmerk HandleError door het nieuwe kenmerk in uw controllers:

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

Voorbeeld

MVC 3

Registreren AiHandleErrorAttribute als een globaal filter in Global.asax.cs:

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

Voorbeeld

MVC 4, MVC 5

Registreren AiHandleErrorAttribute als een globaal 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());
    }
}

Voorbeeld

Web-API

Vanaf Application Insights Web SDK versie 2.6 (bèta 3 en hoger) verzamelt Application Insights niet-verwerkte uitzonderingen die automatisch worden gegenereerd in de controllermethoden voor Web API 2+. Als u eerder een aangepaste handler hebt toegevoegd om dergelijke uitzonderingen bij te houden, zoals beschreven in de volgende voorbeelden, kunt u deze verwijderen om dubbele tracering van uitzonderingen te voorkomen.

Er zijn verschillende gevallen die de uitzonderingsfilters niet kunnen verwerken. Voorbeeld:

  • Uitzonderingen die zijn opgetreden in controller-constructors.
  • Uitzonderingen die zijn opgetreden in berichtenhandlers.
  • Uitzonderingen die zijn opgetreden tijdens routering.
  • Uitzonde ringen die zijn opgetreden tijdens de serialisatie van de gegevens.
  • Er is een uitzondering opgetreden tijdens het opstarten van de toepassing.
  • Uitzondering die zijn opgetreden in achtergrondtaken.

Alle uitzonderingen die door de toepassing worden verwerkt , moeten nog steeds handmatig worden bijgehouden. Niet-verwerkte uitzonderingen die afkomstig zijn van controllers resulteren doorgaans in een reactie van 500 'Interne serverfout'. Als een dergelijk antwoord handmatig wordt samengesteld als gevolg van een verwerkte uitzondering of helemaal geen uitzondering, wordt deze bijgehouden in een bijbehorende aanvraagtelemetrie met ResultCode 500. De Application Insights SDK kan echter geen bijbehorende uitzondering bijhouden.

Ondersteuning voor eerdere versies

Als u Web API 1 (en eerder) van Application Insights Web SDK 2.5 (en eerder) gebruikt, raadpleegt u de volgende voorbeelden om uitzonderingen bij te houden.

Web-API 1.x

Overschrijven 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);
    }
    }
}

U kunt dit overschreven kenmerk toevoegen aan specifieke controllers of deze toevoegen aan de algemene filterconfiguratie in de WebApiConfig klasse:

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());
        }
    }
}

Voorbeeld

Web-API 2.x

Voeg een implementatie toe van IExceptionLogger:

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

Voeg dit fragment toe aan de services in WebApiConfig:

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());
        }
    }
}

Voorbeeld

Als alternatief kunt u het volgende doen:

  • Vervang het enige ExceptionHandler exemplaar door een aangepaste implementatie van IExceptionHandler. Deze uitzonderingshandler wordt alleen aangeroepen wanneer het framework nog steeds kan kiezen welk antwoordbericht moet worden verzonden, niet wanneer de verbinding is afgebroken, bijvoorbeeld.
  • Gebruik uitzonderingsfilters, zoals beschreven in de voorgaande sectie op Web API 1.x-controllers, die in alle gevallen niet worden aangeroepen.

WCF

Voeg een klasse toe die wordt uitgebreid Attribute en geïmplementeerd IErrorHandler en IServiceBehavior.

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

Voeg het kenmerk toe aan de service-implementaties:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Voorbeeld

Prestatiemeteritems voor uitzonderingen

Als u de Azure Monitor Application Insights-agent op uw server hebt geïnstalleerd, kunt u een grafiek ophalen van de frequentie van uitzonderingen, gemeten door .NET. Zowel verwerkte als niet-verwerkte .NET-uitzonderingen zijn opgenomen.

Open het tabblad Metrics Explorer en voeg een nieuwe grafiek toe. Selecteer onder Prestatiemeteritems de uitzonderingsfrequentie.

Het .NET Framework berekent de snelheid door het aantal uitzonderingen in een interval te tellen en te delen door de lengte van het interval.

Dit aantal verschilt van het aantal uitzonderingen dat wordt berekend door de rapporten voor het tellen van TrackException de Application Insights-portal. De steekproefintervallen verschillen en de SDK verzendt TrackException geen rapporten voor alle verwerkte en niet-verwerkte uitzonderingen.

Volgende stappen