Udostępnij za pośrednictwem

Diagnozowanie wyjątków w aplikacjach internetowych za pomocą usługi Application Insights

  • Artykuł

Uwaga

Poniższa dokumentacja opiera się na klasycznym interfejsie API usługi Application Insights. Długoterminowy plan usługi Application Insights polega na zbieraniu danych przy użyciu technologii OpenTelemetry. Aby uzyskać więcej informacji, zobacz Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications and our OpenTelemetry Roadmap (Włączanie usługi Azure Monitor OpenTelemetry dla platformy .NET, Node.js, python i Java) oraz our OpenTelemetry Roadmap (Harmonogram działania openTelemetry). Wskazówki dotyczące migracji są dostępne dla platformy .NET, Node.js i języka Python.

Wyjątki w aplikacjach internetowych można zgłaszać za pomocą usługi Application Insights. Można korelować żądania zakończone niepowodzeniem z wyjątkami i innymi zdarzeniami zarówno po stronie klienta, jak i serwera w celu szybkiego diagnozowania przyczyn. W tym artykule dowiesz się, jak skonfigurować raportowanie wyjątków, jawnie zgłaszać wyjątki, diagnozować błędy i nie tylko.

Konfigurowanie raportowania wyjątków

Usługę Application Insights można skonfigurować tak, aby zgłaszała wyjątki występujące na serwerze lub kliencie. W zależności od platformy, od której zależy aplikacja, potrzebne będzie odpowiednie rozszerzenie lub zestaw SDK.

Strona serwera

Aby zgłaszać wyjątki z aplikacji po stronie serwera, rozważ następujące scenariusze:

  • Dodaj rozszerzenie usługi Application Insights dla aplikacji internetowych platformy Azure.
  • Dodaj rozszerzenie monitorowania aplikacji dla maszyn wirtualnych platformy Azure i usług Azure Virtual Machine Scale Sets hostowanych przez usługi IIS.
  • Zainstaluj zestaw SDK usługi Application Insights w kodzie aplikacji, uruchom agenta usługi Application Insights dla serwerów internetowych usług IIS lub włącz agenta Java dla aplikacji internetowych Java.

Strona klienta

Zestaw SDK języka JavaScript umożliwia raportowanie po stronie klienta wyjątków występujących w przeglądarkach internetowych. Aby skonfigurować raportowanie wyjątków na kliencie, zobacz Application Insights dla stron internetowych.

Struktury aplikacji

W przypadku niektórych struktur aplikacji wymagana jest większa konfiguracja. Rozważ następujące technologie:

Ważne

Ten artykuł koncentruje się specjalnie na aplikacjach .NET Framework z perspektywy przykładu kodu. Niektóre metody, które działają dla platformy .NET Framework, są przestarzałe w zestawie .NET Core SDK. Aby uzyskać więcej informacji, zobacz dokumentację zestawu .NET Core SDK podczas tworzenia aplikacji za pomocą platformy .NET Core.

Diagnozowanie wyjątków przy użyciu programu Visual Studio

Otwórz rozwiązanie aplikacji w programie Visual Studio. Uruchom aplikację na serwerze lub na komputerze deweloperskim przy użyciu F5. Utwórz ponownie wyjątek.

Otwórz okno telemetrii wyszukiwania usługi Application Insights w programie Visual Studio. Podczas debugowania wybierz pole listy rozwijanej Application Insights .

Wybierz raport wyjątku, aby wyświetlić jego ślad stosu. Aby otworzyć odpowiedni plik kodu, wybierz odwołanie do wiersza w śladzie stosu.

Jeśli funkcja CodeLens jest włączona, zobaczysz dane dotyczące wyjątków:

Zrzut ekranu przedstawiający powiadomienie CodeLens o wyjątkach.

Diagnozowanie błędów przy użyciu witryny Azure Portal

Usługa Application Insights zawiera nadzorowane środowisko zarządzania wydajnością aplikacji, które ułatwia diagnozowanie błędów w monitorowanych aplikacjach. Aby rozpocząć, w menu zasobów usługi Application Insights po lewej stronie w obszarze Zbadaj wybierz opcję Błędy .

Zobaczysz trendy współczynnika niepowodzeń dla żądań, liczbę z nich kończy się niepowodzeniem i liczbę użytkowników, których dotyczy problem. Widok Ogólny przedstawia niektóre z najbardziej przydatnych dystrybucji specyficznych dla wybranej operacji zakończonej niepowodzeniem. Zobaczysz trzy najważniejsze kody odpowiedzi, trzy najważniejsze typy wyjątków i trzy najważniejsze typy zależności zakończonych niepowodzeniem.

Zrzut ekranu przedstawiający widok klasyfikacji błędów na karcie Operacje.

Aby przejrzeć reprezentatywne przykłady dla każdego z tych podzestawów operacji, wybierz odpowiedni link. Aby na przykład zdiagnozować wyjątki, możesz wybrać liczbę określonego wyjątku, który ma zostać wyświetlony na karcie Szczegóły transakcji kompleksowej.

Zrzut ekranu przedstawiający kartę Szczegóły transakcji kompleksowej.

Alternatywnie zamiast patrzeć na wyjątki określonej operacji kończącej się niepowodzeniem, możesz zacząć od widoku Ogólne wyjątki, przełączając się na kartę Wyjątki u góry. W tym miejscu można zobaczyć wszystkie wyjątki zebrane dla monitorowanej aplikacji.

Niestandardowe śledzenie i dane dziennika

Aby uzyskać dane diagnostyczne specyficzne dla aplikacji, możesz wstawić kod w celu wysłania własnych danych telemetrycznych. Niestandardowe dane telemetryczne lub dane dziennika są wyświetlane w wyszukiwaniu diagnostycznym wraz z żądaniem, widokiem strony i innymi automatycznie zebranymi danymi.

Za pomocą programu Microsoft.VisualStudio.ApplicationInsights.TelemetryClientdostępnych jest kilka interfejsów API:

  • TelemetryClient.TrackEvent jest zwykle używany do monitorowania wzorców użycia, ale wysyłane dane są również wyświetlane w obszarze Zdarzenia niestandardowe w wyszukiwaniu diagnostycznym. Zdarzenia są nazwane i mogą przenosić właściwości ciągu i metryki liczbowe, na których można filtrować wyszukiwania diagnostyczne.
  • TelemetryClient.TrackTrace umożliwia wysyłanie dłuższych danych, takich jak informacje POST.
  • TelemetryClient.TrackException wysyła szczegóły wyjątku, takie jak ślady stosu do usługi Application Insights.

Aby wyświetlić te zdarzenia, w menu po lewej stronie otwórz pozycję Wyszukaj. Wybierz menu rozwijane Typy zdarzeń, a następnie wybierz pozycję Niestandardowe zdarzenie, ślad lub wyjątek.

Zrzut ekranu przedstawiający ekran Wyszukiwania.

Uwaga

Jeśli aplikacja generuje dużo danych telemetrycznych, moduł próbkowania adaptacyjnego automatycznie zmniejszy wolumin wysyłany do portalu, wysyłając tylko reprezentatywny ułamek zdarzeń. Zdarzenia, które są częścią tej samej operacji, zostaną wybrane lub anulowane jako grupa, aby można było nawigować między powiązanymi zdarzeniami. Aby uzyskać więcej informacji, zobacz Próbkowanie w usłudze Application Insights.

Zobacz żądanie danych POST

Szczegóły żądania nie zawierają danych wysyłanych do aplikacji w wywołaniu POST. Aby te dane zostały zgłoszone:

  • Zainstaluj zestaw SDK w projekcie aplikacji.
  • Wstaw kod w aplikacji, aby wywołać metodę Microsoft.ApplicationInsights.TrackTrace(). Wyślij dane POST w parametrze komunikatu. Istnieje limit dozwolonego rozmiaru, dlatego należy spróbować wysłać tylko niezbędne dane.
  • Po zbadaniu żądania, które zakończyło się niepowodzeniem, znajdź skojarzone ślady.

Przechwytywanie wyjątków i powiązanych danych diagnostycznych

Na początku nie zobaczysz w portalu wszystkich wyjątków, które powodują błędy w aplikacji. Jeśli używasz zestawu SDK języka JavaScript na stronach internetowych, zobaczysz wszystkie wyjątki przeglądarki. Jednak większość wyjątków serwera jest przechwytywane przez usługi IIS i trzeba napisać trochę kodu, aby je zobaczyć.

Masz następujące możliwości:

  • Jawne rejestrowanie wyjątków przez wstawianie kodu w programach obsługi wyjątków w celu raportowania wyjątków.
  • Przechwyć wyjątki automatycznie , konfigurując platformę ASP.NET. Niezbędne dodatki różnią się w przypadku różnych typów platform.

Jawne zgłaszanie wyjątków

Najprostszym sposobem raportowania jest wstawienie wywołania metody trackException() w procedurze obsługi wyjątków.

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

Parametry właściwości i pomiarów są opcjonalne, ale są przydatne do filtrowania i dodawania dodatkowych informacji. Jeśli na przykład masz aplikację, która może uruchamiać kilka gier, możesz znaleźć wszystkie raporty wyjątków związane z określoną grą. Możesz dodać dowolną liczbę elementów do każdego słownika.

Wyjątki przeglądarki

Zgłoszono większość wyjątków przeglądarki.

Jeśli strona internetowa zawiera pliki skryptów z sieci dostarczania zawartości lub innych domen, upewnij się, że tag skryptu ma atrybut crossorigin="anonymous" i że serwer wysyła nagłówki CORS. To zachowanie pozwoli uzyskać ślad stosu i szczegóły dla nieobsługiwane wyjątki języka JavaScript z tych zasobów.

Ponowne używanie klienta telemetrii

Uwaga

Zalecamy utworzenie wystąpienia TelemetryClient raz i ponowne użycie go przez cały czas działania aplikacji.

W przypadku wstrzykiwania zależności (DI) na platformie .NET, odpowiedniego zestawu .NET SDK i poprawnego konfigurowania usługi Application Insights dla di, można wymagać TelemetryClient parametru jako konstruktora.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

W poprzednim przykładzie parametr TelemetryClient jest wstrzykiwany do ExampleController klasy.

Formularze sieci Web

W przypadku formularzy internetowych moduł HTTP będzie mógł zbierać wyjątki, gdy nie skonfigurowano przekierowań za pomocą polecenia CustomErrors. Jeśli jednak masz aktywne przekierowania, dodaj następujące wiersze do Application_Error funkcji w Global.asax.cs.

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

W poprzednim przykładzie _telemetryClient jest to zmienna o zakresie klasy typu TelemetryClient.

MVC

Począwszy od zestawu WEB SDK usługi Application Insights w wersji 2.6 (wersja beta 3 lub nowsza), usługa Application Insights automatycznie zbiera nieobsługiwane wyjątki zgłaszane w metodach kontrolerów MVC 5+ . Jeśli wcześniej dodano program obsługi niestandardowej w celu śledzenia takich wyjątków, możesz go usunąć, aby zapobiec podwójnemu śledzeniu wyjątków.

Istnieje kilka scenariuszy, w których filtr wyjątku nie może poprawnie obsługiwać błędów, gdy wyjątki są zgłaszane:

  • Z konstruktorów kontrolera
  • Z programów obsługi komunikatów
  • Podczas routingu
  • Podczas serializacji zawartości odpowiedzi
  • Podczas uruchamiania aplikacji
  • W zadaniach w tle

Wszystkie wyjątki obsługiwane przez aplikację muszą być śledzone ręcznie. Nieobsługiwane wyjątki pochodzące z kontrolerów zwykle powodują odpowiedź 500 "Wewnętrzny błąd serwera". Jeśli taka odpowiedź jest tworzona ręcznie w wyniku obsłużonego wyjątku lub w ogóle nie ma wyjątku, jest ona śledzona w odpowiednich danych telemetrycznych żądania z ResultCode 500. Jednak zestaw SDK usługi Application Insights nie może śledzić odpowiedniego wyjątku.

Obsługa wcześniejszych wersji

Jeśli używasz wzorca MVC 4 (i wcześniejszych) zestawu Web SDK usługi Application Insights w wersji 2.5 (i wcześniejszych), zapoznaj się z poniższymi przykładami, aby śledzić wyjątki.

Jeśli konfiguracja customErrors to Off, wyjątki będą dostępne dla modułu HTTP do zebrania. Jeśli jednak jest RemoteOnly to (wartość domyślna) lub On, wyjątek zostanie wyczyszczone i nie będzie dostępny dla usługi Application Insights do automatycznego zbierania. To zachowanie można naprawić, przesłaniając klasę System.Web.Mvc.HandleErrorAttribute i stosując przesłoniętą klasę, jak pokazano w przypadku różnych wersji MVC tutaj (zobacz źródło usługi GitHub):

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

Zastąp atrybut HandleError nowym atrybutem w kontrolerach:

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

Przykład

MVC 3

Zarejestruj AiHandleErrorAttribute się jako filtr globalny w Global.asax.cs:

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

Przykład

MVC 4, MVC 5

Zarejestruj AiHandleErrorAttribute się jako filtr globalny w FilterConfig.cs:

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

Przykład

Internetowy interfejs API

Począwszy od internetowego zestawu SDK usługi Application Insights w wersji 2.6 (wersja beta 3 lub nowsza), usługa Application Insights zbiera nieobsługiwane wyjątki zgłaszane automatycznie w metodach kontrolera dla internetowego interfejsu API 2 lub nowszego. Jeśli wcześniej dodano program obsługi niestandardowej w celu śledzenia takich wyjątków, zgodnie z opisem w poniższych przykładach, możesz go usunąć, aby zapobiec podwójnemu śledzeniu wyjątków.

Istnieje kilka przypadków, w których filtry wyjątków nie mogą obsługiwać. Na przykład:

  • Zgłoszone wyjątki przez konstruktorów kontrolerów.
  • Zgłoszone wyjątki przez programy obsługi komunikatów.
  • Zgłoszone wyjątki podczas routingu.
  • Zgłoszone wyjątki podczas serializacji zawartości odpowiedzi.
  • Wyjątek zgłaszany podczas uruchamiania aplikacji.
  • Zgłoszony wyjątek w zadaniach w tle.

Wszystkie wyjątki obsługiwane przez aplikację muszą być śledzone ręcznie. Nieobsługiwane wyjątki pochodzące z kontrolerów zwykle powodują odpowiedź 500 "Wewnętrzny błąd serwera". Jeśli taka odpowiedź jest tworzona ręcznie w wyniku obsłużonego wyjątku lub w ogóle nie ma wyjątku, jest śledzona w odpowiedniej telemetrii żądania z ResultCode 500. Jednak zestaw SDK usługi Application Insights nie może śledzić odpowiedniego wyjątku.

Obsługa wcześniejszych wersji

Jeśli używasz internetowego interfejsu API 1 (i starszych) zestawu Web SDK usługi Application Insights w wersji 2.5 (i starszych), zapoznaj się z poniższymi przykładami, aby śledzić wyjątki.

Internetowy interfejs API 1.x

Zastąpij 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);
    }
    }
}

Ten zastąpiony atrybut można dodać do określonych kontrolerów lub dodać go do konfiguracji filtru globalnego WebApiConfig w klasie:

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

Przykład

Internetowy interfejs API 2.x

Dodaj implementację polecenia 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);
        }
    }
}

Dodaj ten fragment kodu do usług w pliku 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());
        }
    }
}

Przykład

Alternatywnie można wykonać następujące elementy:

  • Zastąp jedyne ExceptionHandler wystąpienie niestandardową implementacją IExceptionHandler. Ta procedura obsługi wyjątków jest wywoływana tylko wtedy, gdy platforma nadal może wybrać komunikat odpowiedzi do wysłania, a nie po przerwaniu połączenia, na przykład.
  • Użyj filtrów wyjątków, jak opisano w poprzedniej sekcji na kontrolerach internetowego interfejsu API 1.x, które nie są wywoływane we wszystkich przypadkach.

WCF

Dodaj klasę, która rozszerza i implementuje Attribute IErrorHandler polecenia i 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)
        {
        }
      }
    }

Dodaj atrybut do implementacji usługi:

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

Przykład

Liczniki wydajności wyjątków

Jeśli na serwerze zainstalowano agenta usługi Azure Monitor Application Insights, możesz uzyskać wykres szybkości wyjątków mierzony przez platformę .NET. Uwzględniane są zarówno obsługiwane, jak i nieobsługiwane wyjątki platformy .NET.

Otwórz kartę Eksploratora metryk, dodaj nowy wykres. W obszarze Liczniki wydajności wybierz pozycję Współczynnik wyjątków.

Program .NET Framework oblicza szybkość, zliczając liczbę wyjątków w interwale i dzieląc według długości interwału.

Ta liczba różni się od liczby wyjątków obliczonych przez raporty zliczania TrackException portalu usługi Application Insights. Interwały próbkowania są różne, a zestaw SDK nie wysyła TrackException raportów dla wszystkich obsługiwanych i nieobsługiwalnych wyjątków.

Następne kroki