Diagnozowanie wyjątków w aplikacjach internetowych za pomocą Szczegółowe informacje aplikacji
Uwaga
Poniższa dokumentacja opiera się na klasycznym interfejsie API usługi Application Szczegółowe informacje. Długoterminowy plan Szczegółowe informacje aplikacji polega na zbieraniu danych przy użyciu biblioteki OpenTelemetry. Aby uzyskać więcej informacji, zobacz Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications (Włączanie usługi Azure Monitor OpenTelemetry dla platformy .NET, Node.js, Python i Java applications).
Wyjątki w aplikacjach internetowych można zgłaszać za pomocą Szczegółowe informacje aplikacji. 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
Możesz skonfigurować Szczegółowe informacje aplikacji w celu zgłaszania wyjątków występujących 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 Szczegółowe informacje aplikacji 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 Szczegółowe informacje aplikacji w kodzie aplikacji, uruchom program Application Szczegółowe informacje Agent 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 Szczegółowe informacje for webs (Aplikacja Szczegółowe informacje 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 klawisza F5. Utwórz ponownie wyjątek.
Otwórz okno Telemetria Szczegółowe informacje Application Szczegółowe informacje Search w programie Visual Studio. Podczas debugowania wybierz pole listy rozwijanej Aplikacja Szczegółowe informacje.
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:
Diagnozowanie błędów przy użyciu witryny Azure Portal
Usługa Application Szczegółowe informacje zawiera wyselekcjonowane środowisko zarządzania wydajnością aplikacji, które ułatwia diagnozowanie błędów w monitorowanych aplikacjach. Aby rozpocząć, w menu Zasobów Szczegółowe informacje aplikacji 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.
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.
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.TrackExceptionwysyła szczegóły wyjątku, takie jak ślady stosu do Szczegółowe informacje aplikacji.
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.
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 Szczegółowe informacje aplikacji.
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ć aplikację Microsoft.Application Szczegółowe informacje. 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 Szczegółowe informacje aplikacji 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 SDK aplikacji Szczegółowe informacje sieci Web w wersji 2.6 (wersja beta 3 lub nowsza), usługa Application Szczegółowe informacje 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 Szczegółowe informacje aplikacji nie może śledzić odpowiedniego wyjątku.
Obsługa wcześniejszych wersji
Jeśli używasz wzorca MVC 4 (i wcześniejszego) zestawu Application Szczegółowe informacje Web SDK 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 aplikacji Szczegółowe informacje 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
}
}
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());
}
}
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());
}
}
Internetowy interfejs API
Począwszy od zestawu SDK aplikacji Szczegółowe informacje sieci Web w wersji 2.6 (wersja beta 3 lub nowsza), usługa Application Szczegółowe informacje 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 Szczegółowe informacje aplikacji nie może śledzić odpowiedniego wyjątku.
Obsługa wcześniejszych wersji
Jeśli używasz internetowego interfejsu API 1 (i wcześniejszych) zestawu Application Szczegółowe informacje Web SDK 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());
}
}
}
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());
}
}
}
Alternatywnie można wykonać następujące elementy:
- Zastąp jedyne
ExceptionHandlerwystą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 AttributeIErrorHandler 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
}
}
Liczniki wydajności wyjątków
Jeśli na serwerze zainstalowano agenta Szczegółowe informacje aplikacji usługi Azure Monitor, możesz uzyskać wykres liczby wyjątków mierzonych 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 application Szczegółowe informacje. 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.