Diagnosticar exceções em aplicativos Web com o Application Insights

  • Artigo

Nota

A documentação a seguir depende da API clássica do Application Insights. O plano de longo prazo para o Application Insights é coletar dados usando OpenTelemetry. Para obter mais informações, consulte Habilitar o Azure Monitor OpenTelemetry para aplicativos .NET, Node.js, Python e Java.

Exceções em aplicativos Web podem ser relatadas com o Application Insights. Pode correlacionar pedidos falhados com exceções e outros eventos tanto no cliente como no servidor, para diagnosticar rapidamente as causas. Neste artigo, você aprenderá a configurar relatórios de exceções, relatar exceções explicitamente, diagnosticar falhas e muito mais.

Configurar o relatório de exceções

Você pode configurar o Application Insights para relatar exceções que ocorrem no servidor ou no cliente. Dependendo da plataforma da qual seu aplicativo depende, você precisará da extensão ou SDK apropriado.

Lado do servidor

Para que as exceções sejam relatadas do seu aplicativo do lado do servidor, considere os seguintes cenários:

Lado do cliente

O JavaScript SDK fornece a capacidade de relatórios do lado do cliente de exceções que ocorrem em navegadores da Web. Para configurar relatórios de exceção no cliente, consulte Application Insights para páginas da Web.

Estruturas de aplicação

Com algumas estruturas de aplicativos, mais configuração é necessária. Considere as seguintes tecnologias:

Importante

Este artigo é especificamente focado em aplicativos .NET Framework de uma perspetiva de exemplo de código. Alguns dos métodos que funcionam para o .NET Framework são obsoletos no SDK do .NET Core. Para obter mais informações, consulte a documentação do SDK do .NET Core ao criar aplicativos com o .NET Core.

Diagnosticar exceções usando o Visual Studio

Abra a solução de aplicativo no Visual Studio. Execute o aplicativo, no servidor ou na máquina de desenvolvimento, usando F5. Recrie a exceção.

Abra a janela de telemetria Pesquisa do Application Insights no Visual Studio. Durante a depuração, selecione a caixa suspensa Application Insights .

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

Selecione um relatório de exceção para mostrar seu rastreamento de pilha. Para abrir o arquivo de código relevante, selecione uma referência de linha no rastreamento de pilha.

Se o CodeLens estiver habilitado, você verá dados sobre as exceções:

Screenshot that shows CodeLens notification of exceptions.

Diagnosticar falhas usando o portal do Azure

O Application Insights vem com uma experiência de gerenciamento de desempenho de aplicativos selecionada para ajudá-lo a diagnosticar falhas em seus aplicativos monitorados. Para começar, no menu de recursos do Application Insights à esquerda, em Investigar, selecione a opção Falhas .

Você verá as tendências da taxa de falha de suas solicitações, quantas delas estão falhando e quantos usuários são afetados. A visualização Geral mostra algumas das distribuições mais úteis específicas para a operação com falha selecionada. Você verá os três principais códigos de resposta, os três principais tipos de exceção e os três principais tipos de dependência com falha.

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

Para examinar amostras representativas para cada um desses subconjuntos de operações, selecione o link correspondente. Por exemplo, para diagnosticar exceções, você pode selecionar a contagem de uma exceção específica a ser apresentada com a guia Detalhes da transação de ponta a ponta.

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

Como alternativa, em vez de examinar exceções de uma operação com falha específica, você pode começar a partir da visualização Geral de exceções alternando para a guia Exceções na parte superior. Aqui você pode ver todas as exceções coletadas para seu aplicativo monitorado.

Rastreamento personalizado e dados de log

Para obter dados de diagnóstico específicos para seu aplicativo, você pode inserir código para enviar seus próprios dados de telemetria. Seus dados personalizados de telemetria ou log são exibidos na pesquisa de diagnóstico ao lado da solicitação, da visualização de página e de outros dados coletados automaticamente.

Usando o Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, você tem várias APIs disponíveis:

  • TelemetryClient.TrackEvent é normalmente usado para monitorar padrões de uso, mas os dados enviados também aparecem em Eventos personalizados na pesquisa de diagnóstico. Os eventos são nomeados e podem carregar propriedades de cadeia de caracteres e métricas numéricas nas quais você pode filtrar suas pesquisas de diagnóstico.
  • TelemetryClient.TrackTrace permite enviar dados mais longos, como informações POST.
  • TelemetryClient.TrackException envia detalhes de exceção, como rastreamentos de pilha para o Application Insights.

Para ver esses eventos, no menu à esquerda, abra Pesquisar. Selecione o menu suspenso Tipos de evento e escolha Evento personalizado, Rastreamento ou Exceção.

Screenshot that shows the Search screen.

Nota

Se seu aplicativo gerar muita telemetria, o módulo de amostragem adaptável reduzirá automaticamente o volume enviado para o portal enviando apenas uma fração representativa de eventos. Os eventos que fazem parte da mesma operação serão selecionados ou desmarcados como um grupo para que você possa navegar entre eventos relacionados. Para obter mais informações, consulte Amostragem no Application Insights.

Ver pedido de dados POST

Os detalhes da solicitação não incluem os dados enviados para seu aplicativo em uma chamada POST. Para que estes dados sejam comunicados:

  • Instale o SDK em seu projeto de aplicativo.
  • Insira o código em seu aplicativo para chamar Microsoft.ApplicationInsights.TrackTrace(). Envie os dados POST no parâmetro message. Há um limite para o tamanho permitido, então você deve tentar enviar apenas os dados essenciais.
  • Ao investigar uma solicitação com falha, localize os rastreamentos associados.

Capturar exceções e dados de diagnóstico relacionados

No início, você não verá no portal todas as exceções que causam falhas em seu aplicativo. Você verá todas as exceções do navegador se estiver usando o SDK do JavaScript em suas páginas da Web. Mas a maioria das exceções de servidor são capturadas pelo IIS e você tem que escrever um pouco de código para vê-las.

Pode:

  • Registre exceções explicitamente inserindo código em manipuladores de exceção para relatar as exceções.
  • Capture exceções automaticamente configurando sua estrutura de ASP.NET. Os aditamentos necessários são diferentes para diferentes tipos de quadros.

Comunicar exceções explicitamente

A maneira mais simples de relatar é inserir uma chamada para trackException() em um manipulador de exceções.

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

Os parâmetros de propriedades e medidas são opcionais, mas são úteis para filtrar e adicionar informações extras. Por exemplo, se tiver uma aplicação que possa executar vários jogos, poderá encontrar todos os relatórios de exceção relacionados com um determinado jogo. Você pode adicionar quantos itens quiser a cada dicionário.

Exceções de browser

A maioria das exceções do navegador são relatadas.

Se sua página da Web incluir arquivos de script de redes de distribuição de conteúdo ou outros domínios, verifique se a marca de script tem o atributo crossorigin="anonymous" e se o servidor envia cabeçalhos CORS. Esse comportamento permitirá que você obtenha um rastreamento de pilha e detalhes para exceções JavaScript não tratadas desses recursos.

Reutilize seu cliente de telemetria

Nota

Recomendamos que você instancie o TelemetryClient uma vez e o reutilize durante toda a vida útil de um aplicativo.

Com a Injeção de Dependência (DI) no .NET, o SDK do .NET apropriado e a configuração correta do Application Insights for DI, você pode exigir o TelemetryClient parâmetro as a constructor.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

No exemplo anterior, o TelemetryClient é injetado ExampleController na classe.

Formulários Web

Para formulários da Web, o módulo HTTP poderá coletar as exceções quando não houver redirecionamentos configurados com CustomErrors. No entanto, quando você tiver redirecionamentos ativos, adicione as seguintes linhas à Application_Error função no Global.asax.cs.

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

No exemplo anterior, o _telemetryClient é uma variável de escopo de classe do tipo TelemetryClient.

MVC

A partir do Application Insights Web SDK versão 2.6 (beta 3 e posterior), o Application Insights coleta automaticamente exceções não tratadas lançadas nos métodos de controladores MVC 5+. Se você adicionou anteriormente um manipulador personalizado para rastrear essas exceções, poderá removê-lo para evitar o rastreamento duplo de exceções.

Há vários cenários em que um filtro de exceção não pode lidar corretamente com erros quando exceções são lançadas:

  • De construtores de controladores
  • De manipuladores de mensagens
  • Durante o encaminhamento
  • Durante a serialização do conteúdo de resposta
  • Durante o arranque da aplicação
  • Em tarefas em segundo plano

Todas as exceções tratadas pelo aplicativo ainda precisam ser rastreadas manualmente. Exceções não tratadas originadas de controladores normalmente resultam em uma resposta 500 "Erro interno do servidor". Se essa resposta for construída manualmente como resultado de uma exceção manipulada, ou nenhuma exceção, ela será rastreada na telemetria de solicitação correspondente com ResultCode 500. No entanto, o SDK do Application Insights não consegue controlar uma exceção correspondente.

Suporte a versões anteriores

Se você usar o MVC 4 (e anterior) do Application Insights Web SDK 2.5 (e anterior), consulte os exemplos a seguir para controlar exceções.

Se a configuração CustomErrors for Off, exceções estarão disponíveis para o módulo HTTP coletar. No entanto, se for RemoteOnly (padrão) ou On, a exceção será desmarcada e não estará disponível para o Application Insights coletar automaticamente. Você pode corrigir esse comportamento substituindo a classe System.Web.Mvc.HandleErrorAttribute e aplicando a classe substituída, conforme mostrado para as diferentes versões do MVC aqui (consulte a fonte do 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

Substitua o atributo HandleError pelo novo atributo em seus controladores:

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

Exemplo

MVC 3

Registe-se AiHandleErrorAttribute como um filtro global em Global.asax.cs:

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

Exemplo

MVC 4, MVC 5

Registe-se AiHandleErrorAttribute como um filtro global em FilterConfig.cs:

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

Exemplo

API da Web

A partir do SDK da Web do Application Insights versão 2.6 (beta 3 e posterior), o Application Insights coleta exceções não tratadas lançadas nos métodos do controlador automaticamente para a API Web 2+. Se você adicionou anteriormente um manipulador personalizado para controlar essas exceções, conforme descrito nos exemplos a seguir, poderá removê-lo para evitar o rastreamento duplo de exceções.

Há vários casos que os filtros de exceção não podem lidar. Por exemplo:

  • Exceções emitidas a partir dos construtores de controladores.
  • Exceções emitidas a partir dos processadores de mensagens.
  • Exceções emitidas durante o encaminhamento.
  • Exceções emitidas durante a serialização de conteúdos de resposta.
  • Exceção lançada durante a inicialização do aplicativo.
  • Exceção emitida em tarefas em segundo plano.

Todas as exceções tratadas pelo aplicativo ainda precisam ser rastreadas manualmente. Exceções não tratadas originadas de controladores normalmente resultam em uma resposta 500 "Erro interno do servidor". Se essa resposta for construída manualmente como resultado de uma exceção manipulada, ou nenhuma exceção, ela será rastreada em uma telemetria de solicitação correspondente com ResultCode 500. No entanto, o SDK do Application Insights não pode rastrear uma exceção correspondente.

Suporte a versões anteriores

Se você usar a API Web 1 (e anteriores) do Application Insights Web SDK 2.5 (e anteriores), consulte os exemplos a seguir para controlar exceções.

API Web 1.x

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

Você pode adicionar esse atributo substituído a controladores específicos ou adicioná-lo à configuração de filtro global na WebApiConfig classe:

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

Exemplo

API Web 2.x

Adicione uma implementação de 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);
        }
    }
}

Adicione este trecho aos serviços em 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());
        }
    }
}

Exemplo

Como alternativa, você pode:

  • Substitua a única ExceptionHandler instância por uma implementação personalizada do IExceptionHandler. Esse manipulador de exceção só é chamado quando a estrutura ainda é capaz de escolher qual mensagem de resposta enviar, não quando a conexão é abortada, por exemplo.
  • Use filtros de exceção, conforme descrito na seção anterior sobre controladores da API Web 1.x, que não são chamados em todos os casos.

WCF

Adicione uma classe que estenda Attribute e implemente IErrorHandler e 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)
        {
        }
      }
    }

Adicione o atributo às implementações de serviço:

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

Exemplo

Contadores de desempenho de exceção

Se tiver instalado o Azure Monitor Application Insights Agent no servidor, pode obter um gráfico da taxa de exceções, medida pelo .NET. As exceções do .NET manipuladas e não tratadas estão incluídas.

Abra uma guia do explorador de métricas, adicione um novo gráfico. Em Contadores de Desempenho, selecione Taxa de exceção.

O .NET Framework calcula a taxa contando o número de exceções em um intervalo e dividindo pelo comprimento do intervalo.

Essa contagem é diferente da contagem de exceções calculada pelos relatórios de contagem TrackException do portal do Application Insights. Os intervalos de amostragem são diferentes e o SDK não envia TrackException relatórios para todas as exceções tratadas e não tratadas.

Próximos passos