Kivételek diagnosztizálása webalkalmazásokban az Application Insights használatával

2025-03-21

Figyelemfelhívás

Javasoljuk az Azure Monitor OpenTelemetry Distro használatát az új alkalmazások vagy ügyfelek számára az Azure Monitor Application Insights használatához. Az Azure Monitor OpenTelemetry Distro az Application Insights SDK-hoz hasonló funkciókat és élményt nyújt. Az Application Insights SDK-ból a .NET, aNode.jsés a Python áttelepítési útmutatóival migrálható, de még dolgozunk néhány további funkció hozzáadásán a visszamenőleges kompatibilitás érdekében.

A webalkalmazások kivételei az Application Insights használatával jelenthetők. A sikertelen kéréseket a kivételekkel és az egyéb eseményekkel korrelálhatja az ügyfélen és a kiszolgálón, így gyorsan diagnosztizálhatja az okokat. Ebből a cikkből megtudhatja, hogyan állíthat be kivételjelentéseket, hogyan jelentheti ki explicit módon a kivételeket, diagnosztizálhatja a hibákat és egyebeket.

Kivételjelentés beállítása

Beállíthatja az Application Insightst a kiszolgálón vagy az ügyfélen előforduló kivételek jelentésére. Attól függően, hogy az alkalmazás melyik platformtól függ, szüksége lesz a megfelelő bővítményre vagy SDK-ra.

Kiszolgálóoldal

Ha a kiszolgálóoldali alkalmazás kivételeit szeretné jelenteni, vegye figyelembe a következő forgatókönyveket:

Adja hozzá az Azure-webalkalmazásokhoz készült Application Insights-bővítményt .
Adja hozzá az Azure Virtual Machines és az Azure Virtual Machine Scale Sets IIS által üzemeltetett alkalmazások alkalmazásmonitorozási bővítményét .
Telepítse az Application Insights SDK-t az alkalmazás kódjába, futtassa az Application Insights Agent for IIS-webkiszolgálókat, vagy engedélyezze a Java-webalkalmazásokhoz készült Java-ügynököt .

Ügyféloldal

A JavaScript SDK lehetővé teszi a webböngészőkben előforduló kivételek ügyféloldali jelentéskészítését. A kliensen történő kivételjelentés beállításához tekintse meg a weblapokhoz tartozó Application Insights útmutatót.

Alkalmazás-keretrendszerek

Egyes alkalmazás-keretrendszerek esetén további konfigurációra van szükség. Vegye figyelembe a következő technológiákat:

Webes űrlapok
MVC
Webes API 1.*
Web API 2.*
WCF

Fontos

Ez a cikk kifejezetten a példakódok szempontjából .NET-keretrendszer alkalmazásokat ismerteti. A .NET Core SDK-ban a .NET-keretrendszer működő módszerek némelyike elavult. További információkért tekintse meg a .NET Core SDK dokumentációját , amikor alkalmazásokat készít a .NET Core használatával.

Kivételek diagnosztizálása a Visual Studióval

Nyissa meg az alkalmazásmegoldást a Visual Studióban. Futtassa az alkalmazást a kiszolgálón vagy a fejlesztőgépen az F5 használatával. Hozza létre újra a kivételt.

Nyissa meg az Application Insights Search telemetriai ablakát a Visual Studióban. A hibakeresés során válassza az Application Insights legördülő menüt.

Válasszon ki egy kivételjelentést a verem nyomkövetésének megjelenítéséhez. A megfelelő kódfájl megnyitásához válasszon egy sorhivatkozást a verem nyomkövetésében.

Ha a CodeLens engedélyezve van, a kivételek adatait fogja látni:

Hibák diagnosztizálása az Azure Portal használatával

Az Application Insights egy válogatott alkalmazásteljesítmény-kezelési felülettel rendelkezik, amely segít diagnosztizálni a megfigyelt alkalmazások hibáit. A kezdéshez a bal oldali Application Insights-erőforrásmenü Vizsgálat területén válassza a Hibák lehetőséget.

Látni fogja a kérések sikertelenségi arányának trendjeit, hogy hány sikertelen, és hány felhasználót érint. Az Általános nézet a kiválasztott sikertelen műveletre jellemző legkedveltebb disztribúciókat jeleníti meg. Az első három válaszkód, az első három kivételtípus és az első három sikertelen függőségtípus jelenik meg.

A műveletek egyes részhalmazainak reprezentatív mintáinak áttekintéséhez válassza a megfelelő hivatkozást. A kivételek diagnosztizálásához például kiválaszthatja, hogy hány kivétel jelenjen meg a teljes körű tranzakció részletei lapon.

Másik lehetőségként ahelyett, hogy egy adott sikertelen művelet kivételeit tekintené meg, a kivételek általános nézetéből kiindulva a felül található Kivételek lapra válthat. Itt láthatja a figyelt alkalmazáshoz összegyűjtött összes kivételt.

Egyéni nyomkövetési és naplóadatok

Az alkalmazásra vonatkozó diagnosztikai adatok lekéréséhez beszúrhat kódot a saját telemetriai adatok küldéséhez. Az egyéni telemetriai vagy naplóadatok a kérés, az oldalnézet és az egyéb automatikusan gyűjtött adatok mellett megjelennek a diagnosztikai keresésben.

Microsoft.VisualStudio.ApplicationInsights.TelemetryClientA használatával számos API érhető el:

TelemetryClient.TrackEvent általában a használati minták monitorozására használják, de az általa küldött adatok az egyéni események alatt is megjelennek a diagnosztikai keresésben. Az események elnevezése sztringtulajdonságokat és numerikus metrikákat tartalmazhat, amelyek alapján szűrheti a diagnosztikai kereséseket.
TelemetryClient.TrackTrace lehetővé teszi hosszabb adatok, például POST-adatok küldését.
TelemetryClient.TrackException kivételadatokat, például veremköveteket küld az Application Insightsnak.

Az események megtekintéséhez a bal oldali menüben nyissa meg a Keresés elemet. Válassza ki a legördülő menü eseménytípusait, majd válassza az Egyéni esemény, nyomkövetés vagy kivétel lehetőséget.

Feljegyzés

Ha az alkalmazás sok telemetriát hoz létre, az adaptív mintavételezési modul automatikusan csökkenti a portálra küldött kötetet úgy, hogy csak az események egy reprezentatív részét küldi el. Az ugyanahhoz a művelethez tartozó események csoportként lesznek kiválasztva vagy törölve, hogy navigálni lehessen a kapcsolódó események között. További információ: Mintavételezés az Application Insightsban.

Kérelem POST-adatainak megtekintése

A kérés részletei nem tartalmazzák az alkalmazásnak post-hívásban küldött adatokat. Az adatok jelentése:

Telepítse az SDK-t az alkalmazásprojektben.
Kód beszúrása az alkalmazásba a Microsoft.ApplicationInsights.TrackTrace() meghívásához. Küldje el a POST-adatokat az üzenetparaméterben. A megengedett méret korlátozott, ezért csak a lényeges adatokat kell elküldenie.
Sikertelen kérés vizsgálatakor keresse meg a kapcsolódó nyomkövetéseket.

Kivételek és kapcsolódó diagnosztikai adatok rögzítése

Először nem fogja látni a portálon az összes olyan kivételt, amely hibákat okoz az alkalmazásban. Ha a JavaScript SDK-t használja a weblapokon, minden böngészőkivételt látni fog. A legtöbb kiszolgálói kivételt azonban az IIS elkapja, és meg kell írnia egy kis kódot, hogy láthassa őket.

A következőket teheti:

A kivételeket explicit módon naplózza , ha kódot szúr be a kivételkezelőkbe a kivételek jelentéséhez.
A kivételek automatikus rögzítése a ASP.NET-keretrendszer konfigurálásával. A szükséges kiegészítések különböző típusú keretrendszerekhez eltérőek.

Jelentéskivételek explicit módon

A jelentés legegyszerűbb módja, ha beszúr egy hívást trackException() egy kivételkezelőbe.

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

A tulajdonságok és a mérési paraméterek nem kötelezőek, de hasznosak a szűréshez és a további információk hozzáadásához. Ha például van egy alkalmazás, amely több játékot is futtathat, megtalálhatja az adott játékhoz kapcsolódó kivételjelentéseket. Tetszőleges számú elemet adhat hozzá az egyes szótárakhoz.

Böngészőkivételek

A legtöbb böngésző-kivételt a rendszer jelenti.

Ha a weblap tartalomkézbesítési hálózatokból vagy más tartományokból származó szkriptfájlokat tartalmaz, győződjön meg arról, hogy a szkriptcímke rendelkezik az attribútummal crossorigin="anonymous" , és hogy a kiszolgáló CORS-fejléceket küld. Ez a viselkedés lehetővé teszi, hogy lekérje a verem nyomkövetését és részleteit az ilyen erőforrásokból származó nem kezelt JavaScript-kivételekhez.

A telemetriai ügyfél újbóli használata

Feljegyzés

Javasoljuk, hogy példányosítsd az TelemetryClient egyszer, és használd újra az alkalmazás teljes élettartama alatt.

A .NET környezetben alkalmazott függőséginjektálással (DI), a megfelelő .NET SDK-val és az Application Insights megfelelő DI konfigurálásával megkövetelheted a TelemetryClient konstruktorparaméterként.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

Az előző példában a TelemetryClient beszúrt érték be lesz szúrva az ExampleController osztályba.

Webes űrlapok

Webes űrlapok esetén a HTTP-modul összegyűjti a kivételeket, ha nincsenek konfigurálva CustomErrorsátirányítások. Ha azonban aktív átirányításokkal rendelkezik, adja hozzá a következő sorokat a függvényhez a Global.asax.cs fájlban.

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

Az előző példában a _telemetryClient típus osztályhatókörű változója TelemetryClient.

MVC

Az Application Insights Web SDK 2.6-os verziójától kezdve (3. bétaverzió és újabb verziók) az Application Insights automatikusan összegyűjti az MVC 5+ vezérlők metódusaiba beszedett kezeletlen kivételeket. Ha korábban hozzáadott egy egyéni kezelőt az ilyen kivételek nyomon követéséhez, eltávolíthatja, hogy megakadályozza a kivételek kettős nyomon követését.

Több olyan eset is van, amikor egy kivételszűrő nem tudja megfelelően kezelni a kivételekkel kapcsolatos hibákat:

Vezérlőkonstruktorokból
Üzenetkezelőktől
Útválasztás során
Választartalmak szerializálása során
Az alkalmazás indításakor
Háttérfeladatokban

Az alkalmazás által kezelt kivételeket továbbra is manuálisan kell nyomon követni. A vezérlőkből származó kezeletlen kivételek általában 500 "belső kiszolgálói hiba" választ eredményeznek. Ha az ilyen válasz manuálisan, egy kezelt kivétel eredményeként jön létre, vagy egyáltalán nincs kivétel, akkor a rendszer a megfelelő 500-as ResultCode kérelemtelemetria alapján követi nyomon. Az Application Insights SDK azonban nem tudja nyomon követni a megfelelő kivételt.

Korábbi verziók támogatása

Ha az Application Insights Web SDK 2.5 -ös (és korábbi) MVC 4-et (és korábbit) használja, a kivételek nyomon követéséhez tekintse meg az alábbi példákat.

Ha a CustomErrors konfigurációja igen Off, a HTTP-modul számára kivételeket lehet gyűjteni. Ha RemoteOnly azonban ez (alapértelmezett) vagy On, a kivétel törlődik, és nem érhető el az Application Insights számára az automatikus adatgyűjtéshez. Ezt a viselkedést a System.Web.Mvc.HandleErrorAttribute osztály felülbírálásával és a felülbírált osztály alkalmazásával javíthatja, ahogyan az itt látható különböző MVC-verziók esetében is látható (lásd a GitHub forrását):

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

Cserélje le a HandleError attribútumot az új attribútumra a vezérlőkben:

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

Minta

MVC 3

Regisztráljon AiHandleErrorAttribute globális szűrőként a Global.asax.cs:

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

Minta

MVC 4, MVC 5

Regisztráljon AiHandleErrorAttribute globális szűrőként a FilterConfig.cs:

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

Minta

Webes API

Az Application Insights Web SDK 2.6-os verziójától kezdve (3. bétaverzió és újabb verziók) az Application Insights a Web API 2+-hoz automatikusan gyűjti a vezérlő metódusaiba beszedett kezeletlen kivételeket. Ha korábban hozzáadott egy egyéni kezelőt az ilyen kivételek nyomon követéséhez, az alábbi példákban leírtak szerint eltávolíthatja, hogy megakadályozza a kivételek kettős nyomon követését.

A kivételszűrők számos esetben nem kezelhetők. Példa:

A vezérlőkonstruktorokban történt kivételek.
Az üzenetkezelőkben történt kivételek.
Az útválasztás során történt kivételek.
A választartalmak szerializálása során történt kivételek.
Az alkalmazás indításakor kidobott kivétel.
A háttérfeladatokban történt kivételek.

Az alkalmazás által kezelt kivételeket továbbra is manuálisan kell nyomon követni. A vezérlőkből származó kezeletlen kivételek általában 500 "belső kiszolgálói hiba" választ eredményeznek. Ha egy ilyen válasz manuálisan, egy kezelt kivétel eredményeként jön létre, vagy egyáltalán nincs kivétel, akkor a rendszer egy 500-as ResultCode megfelelő kérelemtelemetria alapján követi nyomon. Az Application Insights SDK azonban nem tudja nyomon követni a megfelelő kivételt.

Korábbi verziók támogatása

Ha az Application Insights Web SDK 2.5(és korábbi) 1. (és korábbi) Webes API-t használja, a kivételek nyomon követéséhez tekintse meg az alábbi példákat.

Webes API 1.x

Felülbírálás 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);
    }
    }
}

Ezt a felülírt attribútumot hozzáadhatja adott vezérlőkhöz, vagy felveheti az osztály globális szűrőkonfigurációjába WebApiConfig :

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

Minta

Webes API 2.x

A következő implementáció IExceptionLoggerhozzáadása:

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

Adja hozzá ezt a kódrészletet a következő szolgáltatásokhoz 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());
        }
    }
}

Minta

Alternatív megoldásként a következőkre van lehetősége:

Cserélje le az egyetlen ExceptionHandler példányt egy egyéni implementációra IExceptionHandler. Ezt a kivételkezelőt csak akkor hívja meg a rendszer, ha a keretrendszer továbbra is meg tudja választani, hogy melyik válaszüzenetet küldje el, például a kapcsolat megszakadásakor nem.
Használjon kivételszűrőket a Web API 1.x vezérlők előző szakaszában leírtak szerint, amelyeket nem minden esetben hívunk meg.

WCF (Windows Communication Foundation)

Adjon hozzá egy olyan osztályt, amely kiterjeszti Attribute és megvalósítja IErrorHandler a elemet.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)
        {
        }
      }
    }

Adja hozzá az attribútumot a szolgáltatás implementációihoz:

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

Minta

Kivételteljesítmény-számlálók

Ha telepítette az Azure Monitor Application Insights-ügynököt a kiszolgálón, lekérheti a .NET által mért kivételek arányának diagramját. Mind a kezelt, mind a kezeletlen .NET-kivételeket tartalmazza a rendszer.

Nyisson meg egy metrikakezelő lapot, és adjon hozzá egy új diagramot. A Teljesítményszámlálók területen válassza a Kivételi arány lehetőséget.

A .NET-keretrendszer úgy számítja ki a mértéket, hogy megszámolja a kivételek számát egy intervallumban, és elosztja az intervallum hosszával.

Ez a szám eltér az Application Insights portál által kiszámított kivételek számától, amely a jelentéseket számolja TrackException . A mintavételezési időközök eltérőek, és az SDK nem küld TrackException jelentéseket az összes kezelt és kezeletlen kivételről.

Következő lépések

Ellenőrizze, hogy az Application Insights SDK támogatott verzióját futtatja-e .
A REST, az SQL és a függőségekre irányuló egyéb hívások figyelése
Az oldalbetöltési idők, a böngészők kivételei és az AJAX-hívások figyelése
Teljesítményszámlálók figyelése

Megosztás a következőn keresztül:

Kivételek diagnosztizálása webalkalmazásokban az Application Insights használatával

Kivételjelentés beállítása

Kiszolgálóoldal

Ügyféloldal

Alkalmazás-keretrendszerek

Kivételek diagnosztizálása a Visual Studióval

Hibák diagnosztizálása az Azure Portal használatával

Egyéni nyomkövetési és naplóadatok

Kérelem POST-adatainak megtekintése

Kivételek és kapcsolódó diagnosztikai adatok rögzítése

Jelentéskivételek explicit módon

Böngészőkivételek

A telemetriai ügyfél újbóli használata

Webes űrlapok

MVC

Korábbi verziók támogatása

MVC 2

MVC 3

MVC 4, MVC 5

Webes API

Korábbi verziók támogatása

Webes API 1.x

Webes API 2.x

WCF (Windows Communication Foundation)

Kivételteljesítmény-számlálók

Következő lépések

Visszajelzés

További források