Diagnostisera undantag i webbappar med Application Insights

  • Artikel

Kommentar

Följande dokumentation förlitar sig på det klassiska API:et Application Insights. Den långsiktiga planen för Application Insights är att samla in data med OpenTelemetry. Mer information finns i Aktivera Azure Monitor OpenTelemetry för .NET-, Node.js-, Python- och Java-program.

Undantag i webbprogram kan rapporteras med Application Insights. Du kan korrelera misslyckade begäranden med undantag och andra händelser på såväl klienten som servern, vilket innebär att du snabbt kan diagnostisera orsakerna. I den här artikeln får du lära dig hur du konfigurerar undantagsrapportering, rapporterar undantag explicit, diagnostiserar fel med mera.

Konfigurera undantagsrapportering

Du kan konfigurera Application Insights för att rapportera undantag som inträffar på antingen servern eller klienten. Beroende på vilken plattform ditt program är beroende av behöver du rätt tillägg eller SDK.

Serversidan

Om du vill att undantag ska rapporteras från ditt program på serversidan bör du överväga följande scenarier:

Kundsidan

JavaScript SDK ger möjlighet att rapportera undantag på klientsidan som inträffar i webbläsare. Information om hur du konfigurerar undantagsrapportering på klienten finns i Application Insights för webbsidor.

Programramverk

Med vissa programramverk krävs mer konfiguration. Tänk på följande tekniker:

Viktigt!

Den här artikeln fokuserar specifikt på .NET Framework-appar ur ett kodexempelperspektiv. Några av metoderna som fungerar för .NET Framework är föråldrade i .NET Core SDK. Mer information finns i .NET Core SDK-dokumentationen när du skapar appar med .NET Core.

Diagnostisera undantag med hjälp av Visual Studio

Öppna applösningen i Visual Studio. Kör appen, antingen på servern eller på utvecklingsdatorn med hjälp av F5. Återskapa undantaget.

Öppna telemetrifönstret Application Insights Search i Visual Studio. När du felsöker väljer du listrutan Application Insights .

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

Välj en undantagsrapport för att visa stackspårningen. Om du vill öppna relevant kodfil väljer du en radreferens i stackspårningen.

Om CodeLens är aktiverat visas data om undantagen:

Screenshot that shows CodeLens notification of exceptions.

Diagnostisera fel med hjälp av Azure-portalen

Application Insights har en hanterad programprestandahantering som hjälper dig att diagnostisera fel i dina övervakade program. Börja genom att gå till resursmenyn Application Insights till vänster under Undersök och välj alternativet Fel .

Du ser trender för felfrekvens för dina begäranden, hur många av dem som misslyckas och hur många användare som påverkas. Vyn Övergripande visar några av de mest användbara distributionerna som är specifika för den valda misslyckade åtgärden. Du ser de tre vanligaste svarskoderna, de tre vanligaste undantagstyperna och de tre vanligaste beroendetyperna som misslyckas.

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

Om du vill granska representativa exempel för var och en av dessa delmängder av åtgärder väljer du motsvarande länk. Om du till exempel vill diagnostisera undantag kan du välja antalet undantag som ska visas på fliken Transaktionsinformation från slutpunkt till slutpunkt.

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

I stället för att titta på undantag för en specifik misslyckad åtgärd kan du också börja från den övergripande vyn av undantag genom att växla till fliken Undantag överst . Här kan du se alla undantag som samlas in för din övervakade app.

Anpassad spårning och loggdata

För att få diagnostikdata som är specifika för din app kan du infoga kod för att skicka egna telemetridata. Dina anpassade telemetri- eller loggdata visas i diagnostiksökningen tillsammans med begäran, sidvyn och andra automatiskt insamlade data.

Med hjälp av Microsoft.VisualStudio.ApplicationInsights.TelemetryClienthar du flera TILLGÄNGLIGA API:er:

Om du vill se dessa händelser öppnar du Sök på den vänstra menyn. Välj den nedrullningsbara menyn Händelsetyper och välj sedan Anpassad händelse, Spårning eller Undantag.

Screenshot that shows the Search screen.

Kommentar

Om din app genererar mycket telemetri minskar modulen för anpassningsbar sampling automatiskt volymen som skickas till portalen genom att endast skicka en representativ del av händelserna. Händelser som ingår i samma åtgärd väljs eller avmarkeras som en grupp så att du kan navigera mellan relaterade händelser. Mer information finns i Sampling i Application Insights.

Se POST-begärandedata

Information om begäran inkluderar inte de data som skickas till din app i ett POST-anrop. Så här rapporterar du dessa data:

  • Installera SDK :et i programprojektet.
  • Infoga kod i programmet för att anropa Microsoft.ApplicationInsights.TrackTrace(). Skicka POST-data i meddelandeparametern. Det finns en gräns för den tillåtna storleken, så du bör bara försöka skicka viktiga data.
  • När du undersöker en misslyckad begäran letar du upp de associerade spårningarna.

Samla in undantag och relaterade diagnostikdata

Först ser du inte alla undantag som orsakar fel i appen i portalen. Du ser eventuella webbläsarfel om du använder JavaScript SDK på dina webbsidor. Men de flesta serverfel fångas av IIS och du måste skriva lite kod för att se dem.

Du kan:

  • Logga undantag explicit genom att infoga kod i undantagshanterare för att rapportera undantagen.
  • Samla in undantag automatiskt genom att konfigurera ditt ASP.NET ramverk. De nödvändiga tilläggen skiljer sig åt för olika typer av ramverk.

Rapportera undantag explicit

Det enklaste sättet att rapportera är att infoga ett anrop till trackException() i en undantagshanterare.

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

Parametrarna för egenskaper och mått är valfria, men de är användbara för att filtrera och lägga till extra information. Om du till exempel har en app som kan köra flera spel kan du hitta alla undantagsrapporter som är relaterade till ett visst spel. Du kan lägga till så många objekt som du vill i varje ordlista.

Webbläsarundantag

De flesta webbläsarfel rapporteras.

Om din webbsida innehåller skriptfiler från nätverk för innehållsleverans eller andra domäner kontrollerar du att skripttaggen har attributet crossorigin="anonymous" och att servern skickar CORS-huvuden. Med det här beteendet kan du hämta en stackspårning och information för ohanterade JavaScript-undantag från dessa resurser.

Återanvänd din telemetriklient

Kommentar

Vi rekommenderar att du instansierar en TelemetryClient gång och återanvänder den under hela programmets livslängd.

Med Dependency Injection (DI) i .NET, lämplig .NET SDK och korrekt konfiguration av Application Insights för DI, kan du kräva TelemetryClient som en konstruktorparameter.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

I föregående exempel TelemetryClient matas ExampleController in i klassen.

Webbformulär

För webbformulär kan HTTP-modulen samla in undantagen när inga omdirigeringar har konfigurerats med CustomErrors. Men när du har aktiva omdirigeringar lägger du till följande rader i Application_Error funktionen i Global.asax.cs.

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

I föregående exempel _telemetryClient är en variabel med klassomfattning av typen TelemetryClient.

MVC

Från och med Application Insights Web SDK version 2.6 (beta 3 och senare) samlar Application Insights in ohanterade undantag som genereras automatiskt i MVC 5+-kontrollantmetoderna. Om du tidigare har lagt till en anpassad hanterare för att spåra sådana undantag kan du ta bort den för att förhindra dubbel spårning av undantag.

Det finns flera scenarier när ett undantagsfilter inte kan hantera fel korrekt när undantag utlöses:

  • Från styrenhetskonstruktorer
  • Från meddelandehanterare
  • Under routning
  • Under svarsinnehålls serialisering
  • Under programstart
  • I bakgrundsaktiviteter

Alla undantag som hanteras av programmet måste fortfarande spåras manuellt. Ohanterade undantag från kontrollanter resulterar vanligtvis i ett svar på 500 "internt serverfel". Om ett sådant svar konstrueras manuellt till följd av ett hanterat undantag, eller inget undantag alls, spåras det i motsvarande telemetri för begäran med ResultCode 500. Application Insights SDK kan dock inte spåra ett motsvarande undantag.

Stöd för tidigare versioner

Om du använder MVC 4 (och tidigare) av Application Insights Web SDK 2.5 (och tidigare) läser du följande exempel för att spåra undantag.

Om CustomErrors-konfigurationen är Offär undantag tillgängliga för HTTP-modulen att samla in. Men om det är RemoteOnly (standard) eller Onkommer undantaget att rensas och inte vara tillgängligt för Application Insights att samla in automatiskt. Du kan åtgärda det beteendet genom att åsidosätta klassen System.Web.Mvc.HandleErrorAttribute och tillämpa den åsidosatta klassen enligt de olika MVC-versionerna här (se GitHub-källan):

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

Ersätt Attributet HandleError med det nya attributet i dina kontrollanter:

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

Exempel

MVC 3

Registrera dig AiHandleErrorAttribute som ett globalt filter i Global.asax.cs:

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

Exempel

MVC 4, MVC 5

Registrera dig AiHandleErrorAttribute som ett globalt filter i FilterConfig.cs:

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

Exempel

Webb-API

Från och med Application Insights Web SDK version 2.6 (beta 3 och senare) samlar Application Insights in ohanterade undantag som genereras i kontrollantmetoderna automatiskt för Web API 2+. Om du tidigare har lagt till en anpassad hanterare för att spåra sådana undantag, enligt beskrivningen i följande exempel, kan du ta bort den för att förhindra dubbel spårning av undantag.

Det finns flera fall som undantagsfiltren inte kan hantera. Till exempel:

  • Undantag som utlöses från styrenhetskonstruktörer.
  • Undantag som utlöses av meddelandehanterare.
  • Undantag som utlöses under routning.
  • Undantag som utlöses under serialisering av svarsinnehåll.
  • Undantag som utlöses när programmet startas.
  • Undantag som utlöses i bakgrundsaktiviteter.

Alla undantag som hanteras av programmet måste fortfarande spåras manuellt. Ohanterade undantag från kontrollanter resulterar vanligtvis i ett svar på 500 "internt serverfel". Om ett sådant svar konstrueras manuellt till följd av ett hanterat undantag, eller inget undantag alls, spåras det i en motsvarande telemetri för begäran med ResultCode 500. Application Insights SDK kan dock inte spåra ett motsvarande undantag.

Stöd för tidigare versioner

Om du använder Web API 1 (och tidigare) av Application Insights Web SDK 2.5 (och tidigare) läser du följande exempel för att spåra undantag.

Webb-API 1.x

Åsidosätt 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);
    }
    }
}

Du kan lägga till det här åsidosatta attributet till specifika kontrollanter eller lägga till det i den globala filterkonfigurationen WebApiConfig i klassen:

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

Exempel

Webb-API 2.x

Lägg till en implementering av 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);
        }
    }
}

Lägg till det här kodfragmentet i tjänsterna i 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());
        }
    }
}

Exempel

Som alternativ kan du:

  • Ersätt den enda ExceptionHandler instansen med en anpassad implementering av IExceptionHandler. Den här undantagshanteraren anropas bara när ramverket fortfarande kan välja vilket svarsmeddelande som ska skickas, inte när anslutningen avbryts, till exempel.
  • Använd undantagsfilter enligt beskrivningen i föregående avsnitt på Web API 1.x-kontrollanter, som inte anropas i alla fall.

WCF

Lägg till en klass som utökar Attribute och implementerar IErrorHandler och 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)
        {
        }
      }
    }

Lägg till attributet i tjänstimplementeringarna:

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

Exempel

Prestandaräknare för undantag

Om du har installerat Azure Monitor Application Insights-agenten på servern kan du få ett diagram över undantagsfrekvensen, mätt med .NET. Både hanterade och ohanterade .NET-undantag ingår.

Öppna fliken metrics explorer och lägg till ett nytt diagram. Under Prestandaräknare väljer du Undantagsfrekvens.

.NET Framework beräknar frekvensen genom att räkna antalet undantag i ett intervall och dividera med intervallets längd.

Det här antalet skiljer sig från antalet undantag som beräknas av Application Insights-portalens inventeringsrapporter TrackException . Samplingsintervallen skiljer sig åt och SDK skickar TrackException inte rapporter för alla hanterade och ohanterade undantag.

Nästa steg