Habilitar o Application Insights para aplicativos ASP.NET Core

Este artigo descreve como habilitar o Application Insights para um aplicativo ASP.NET Core implantado como um aplicativo Web do Azure. Essa implementação usa uma abordagem baseada em SDK. Uma abordagem de auto-instrumentação também está disponível.

O Application Insights pode coletar a seguinte telemetria do seu aplicativo ASP.NET Core:

• Requests
• Dependências
• Exceções
• Contadores de desempenho
• Pulsações
• Logs

Para um aplicativo de exemplo, usaremos um aplicativo MVC do ASP.NET Core direcionadonet6.0. No entanto, é possível aplicar essas instruções a todos os aplicativos do ASP.NET Core. Se você estiver usando o Worker Service, use as instruções disponíveis aqui.

Observação

Uma Oferta do .NET baseada em OpenTelemetry está disponível. Saiba mais.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Faça a transição para cadeias de conexão para aproveitar as novas funcionalidades.

Cenários com suporte

O SDK do Application Insights para ASP.NET Core pode monitorar os aplicativos, independentemente de onde ou como eles são executados. Se o aplicativo estiver em execução e tiver conectividade de rede com o Azure, o Application Insights poderá coletar a telemetria dele. O monitoramento do Application Insights tem suporte em todos os lugares do .NET Core. Os cenários a seguir têm suporte:

• Sistema operacional: Windows, Linux ou Mac
• Método de hospedagem\ : no processo ou fora do processo
• Método de implantação: dependente do Framework ou autossuficiente
• Servidor Web: IIS (Servidor de Informações da Internet) ou Kestrel
• Plataforma de hospedagem: recurso dos Aplicativos Web do Serviço de Aplicativo do Azure, VM do Azure, Docker, AKS (Serviço Kubernetes do Azure) e assim por diante
• Versão do .NET Core: todas as versões do .NET Core com suporte oficial que não estejam em versão prévia
• IDE: Visual Studio, VS Code ou linha de comando

Pré-requisitos

Para concluir este tutorial, você precisará:

• Visual Studio 2022
• As seguintes cargas de trabalho do Visual Studio:
  • Desenvolvimento Web e ASP.NET
  • Armazenamento de dados e processamento
  • Desenvolvimento do Azure
• .NET 6.0
• Assinatura do Azure e conta de usuário (com a capacidade de criar e excluir recursos)

Implantar recursos do Azure

Siga as diretrizes para implantar o aplicativo de exemplo do repositório GitHub..

Para fornecer nomes globalmente exclusivos aos recursos, um sufixo de seis caracteres é atribuído a alguns recursos. Anote este sufixo para uso posterior neste artigo.

Criar um recurso do Application Insights

1. No portal do Azure, selecione o grupo de recursos application-insights-azure-cafe.

2. No menu superior da barra de ferramentas, selecione + Criar.

   

3. Na tela Criar um recurso, pesquise e selecione Application Insights na caixa de texto de pesquisa do marketplace.

   

   Captura de tela da tela Criar um recurso no portal do Azure. A captura de tela mostra uma pesquisa do Application Insights realçada e o Application Insights exibindo os resultados da pesquisa, que também estão realçados.

4. Na tela de visão geral do recurso do Application Insights, selecione Criar.

   

5. Na tela Application Insights, guia Básico, preencha o formulário usando a tabela a seguir e selecione o botão Revisar + criar. Os campos não especificados na tabela abaixo podem manter seus valores padrão.

   Campo	Valor
   Nome	Insira azure-cafe-application-insights-{SUFFIX}, substituindo {SUFFIX} pelo valor do sufixo apropriado registrado anteriormente.
   Região	Selecione a mesma região escolhida ao implantar os recursos do artigo.
   Workspace do Log Analytics	Selecione azure-cafe-log-analytics-workspace. Como alternativa, você poderá criar um novo workspace do Log Analytics.

   

6. Depois que a validação for aprovada, selecione Criar para implantar o recurso.

   

7. Após implantar o recurso, retorne ao grupo de recursos application-insights-azure-cafe e selecione o recurso Application Insights que você implantou.

   

8. Na tela Visão geral do recurso Application Insights, selecione o botão Copiar para Área de Transferência para copiar o valor da cadeia de conexão. Você usará o valor da cadeia de conexão na próxima seção deste artigo.

   

   Captura de tela da tela Visão geral do Application Insights no portal do Azure. A captura de tela mostra o valor da cadeia de conexão realçado e o botão Copiar para área de transferência selecionado e realçado.

Configurar a configuração do aplicativo de cadeia de conexão do Application Insights no Serviço de Aplicativo Web

1. Retorne ao grupo de recursos application-insights-azure-cafe e abra o recurso do Serviço de Aplicativo azure-cafe-web-{SUFFIX}.

   

2. No menu esquerdo, na seção Configurações, selecione Configuração. Na guia Configurações de aplicativo, em + Configurações de aplicativo, abaixo do cabeçalho de configurações do aplicativo.

   

   Captura de tela da tela de recursos do Serviço de Aplicativo no portal do Azure. A captura de tela mostra Configuração no menu à esquerda, na seção Configurações, selecionada e realçada. A guia Configurações de aplicativo está selecionada e realçada. O botão da barra de ferramentas + Nova configuração de aplicativo está realçado.

3. No painel Adicionar/Editar configuração do aplicativo, conclua o formulário da seguinte maneira e selecione OK.

   Campo	Valor
   Nome	APPLICATIONINSIGHTS_CONNECTION_STRING
   Valor	Cole o valor da cadeia de conexão do Application Insights que você copiou na seção anterior.

   

4. Na tela Serviço de Aplicativo Configuração, selecione o botão Salvar no menu da barra de ferramentas. Quando solicitado a salvar as alterações, selecione Continuar.

   

Instale o pacote NuGet do Application Insights

Precisamos configurar o aplicativo Web ASP.NET Core MVC para enviar telemetria. Isso é feito usando o Pacote NuGet de aplicativos Web do Application Insights para ASP.NET Core.

1. No Visual Studio, abra 1 - Starter Application\src\AzureCafe.sln.

2. No painel Gerenciador de Soluções do Visual Studio, clique com o botão direito do mouse no arquivo de projeto do AzureCafe e selecione Gerenciar Pacotes do NuGet.

   

3. Selecione a guia Procurar e, em seguida, selecione Microsoft.ApplicationInsights.AspNetCore. Selecione Instalar e aceite os termos de uso. É recomendável usar a versão estável mais recente. Para obter as notas sobre a versão completas do SDK, consulte o repositório GitHub de código aberto.

   

   Captura de tela que mostra a interface do usuário do Gerenciador de Pacotes NuGet no Visual Studio com a guia Procurar selecionada. Microsoft.ApplicationInsights.AspNetCore é inserido na caixa de pesquisa e o pacote Microsoft.ApplicationInsights.AspNetCore é selecionado em uma lista de resultados. No painel direito, a versão estável mais recente do pacote Microsoft.ApplicationInsights.AspNetCore é selecionada em uma lista suspensa e o botão Instalar está realçado.

   Mantenha o Visual Studio aberto para a próxima seção do artigo.

Habilitar a telemetria do lado do servidor no Application Insights

O pacote NuGet do Application Insights para aplicativos Web ASP.NET Core encapsula recursos para habilitar o envio de telemetria do lado do servidor para o recurso do Application Insights no Azure.

1. No Gerenciador de Soluções do Visual Studio, abra o arquivo Program.cs.

   

2. Insira o código a seguir antes da instrução builder.Services.AddControllersWithViews(). Esse código lê automaticamente o valor da cadeia de conexão do Application Insights da configuração. O método AddApplicationInsightsTelemetry registra o ApplicationInsightsLoggerProvider com o contêiner de injeção de dependência interno que será usado para atender às solicitações de implementação ILogger e ILogger<TCategoryName>.

   builder.Services.AddApplicationInsightsTelemetry();
   

   

   Dica

   Saiba mais sobre as opções de configuração no ASP.NET Core.

Habilitar telemetria do lado do cliente para aplicativos Web

As etapas anteriores são suficientes para ajudá-lo a começar a coletar a telemetria do lado do servidor. O aplicativo de exemplo possui componentes do lado do cliente. Siga as próximas etapas para começar a coletar a telemetria de uso.

1. No Gerenciador de Soluções do Visual Studio, abra \Views\_ViewImports.cshtml.

2. Adicione o código a seguir no final do arquivo existente.

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

   

3. Para habilitar corretamente o monitoramento do lado do cliente do aplicativo, no Gerenciador de Soluções do Visual Studio, abra \Views\Shared\_Layout.cshtml insira o seguinte código imediatamente antes da marca <\head>. Esse trecho de JavaScript deve ser inserido na seção <head> de cada página do aplicativo que você quer monitorar.

   @Html.Raw(JavaScriptSnippet.FullScript)
   

   

   Dica

   Uma alternativa ao uso do FullScript é ScriptBody. Use ScriptBody se você precisar controlar a tag <script> para definir uma Política de Segurança de Conteúdo:

   <script> // apply custom changes to this script tag.
       @Html.Raw(JavaScriptSnippet.ScriptBody)
   </script>
   

Observação

A injeção de JavaScript fornece uma experiência de configuração padrão. Se você precisar de alguma configuração além da configuração da cadeia de conexão, precisará remover a injeção automática conforme descrito acima e adicionar manualmente o SDK do JavaScript.

Habilitar o monitoramento de consultas de banco de dados

Ao investigar causas de degradação de desempenho, é importante incluir insights sobre chamadas de banco de dados. Você habilita o monitoramento configurando o módulo de dependência. O monitoramento de dependência, incluindo o SQL, é habilitado por padrão.

Siga estas etapas para capturar o texto completo da consulta SQL.

Observação

O texto SQL pode conter dados confidenciais, como senhas e PII. Tenha cuidado ao habilitar esse recurso.

1. No Gerenciador de Soluções do Visual Studio, abra o arquivo Program.cs.

2. Na parte superior do arquivo, adicione a seguinte instrução using.

   using Microsoft.ApplicationInsights.DependencyCollector;
   

3. Para habilitar a instrumentação de texto de comando SQL, insira o código a seguir imediatamente após o código builder.Services.AddApplicationInsightsTelemetry().

   builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
   

   

Executar o aplicativo Web do Azure Cafe

Após implantar o código do aplicativo Web, a telemetria fluirá para o Application Insights. O SDK do Application Insights coleta automaticamente as solicitações da Web recebidas pelo aplicativo.

1. No Gerenciador de Soluções do Visual Studio, clique com o botão direito do mouse no projeto AzureCafe e selecione Publicar no menu de contexto.

   

2. Selecione Publicar para promover o novo código para o Serviço de Aplicativo do Azure.

   

   Quando o aplicativo Web do Azure Cafe é publicado com êxito, uma nova janela do navegador é aberta para o aplicativo Web do Azure Cafe.

   

3. Para gerar alguma telemetria, siga estas etapas no aplicativo Web para adicionar uma revisão.

   1. Para exibir o menu e as revisões de um café, selecione Detalhes ao lado de um café.

      

   2. Para exibir e adicionar revisões, na tela Café, selecione a guia Revisões. Selecione o botão Adicionar revisão para adicionar uma revisão.

      

   3. Na caixa de diálogo Criar uma opinião, insira um nome, uma classificação, comentários e carregue uma foto para a opinião. Quando terminar, selecione Adicionar revisão.

      

   4. Se você precisar gerar telemetria adicional, adicione revisões adicionais.

Métricas em tempo real

Você pode usar o Live Metrics para verificar rapidamente se o monitoramento do Application Insights está configurado corretamente. O Live Metrics mostra o uso da CPU do processo em execução quase em tempo real. Ele também pode mostrar outras telemetrias como Solicitações, Dependências e Rastreamentos. Observe que poderá demorar alguns minutos para a telemetria aparecer no portal e na análise.

Exibir o mapa do aplicativo

O aplicativo de exemplo faz chamadas para vários recursos do Azure, incluindo SQL do Azure, Armazenamento de Blobs do Azure e o Serviço de Idioma do Azure (para análise de sentimento de revisão).

O Application Insights analisa os dados de telemetria recebidos e é poderá gerar um mapa visual das integrações do sistema que detecta.

1. Entre no portal do Azure.

2. Abra o grupo de recursos para o aplicativo de exemplo, que é application-insights-azure-cafe.

3. Na lista de recursos, selecione o recurso azure-cafe-insights-{SUFFIX} do Application Insights.

4. No menu esquerdo, abaixo do título Investigar, selecione Mapa de aplicativos. Observe o mapa do aplicativo gerado.

   

Exibindo chamadas HTTP e texto do comando SQL do banco de dados

1. No portal do Microsoft Azure, abra o recurso do Application Insights.

2. No menu esquerdo, abaixo do cabeçalho Investigar, selecione Desempenho.

3. A guia Operações contém detalhes das chamadas HTTP recebidas pelo aplicativo. Para alternar entre as exibições de Servidor e Navegador (lado do cliente) dos dados, use a alternância de Servidor/Navegador.

   

   Captura de tela da tela Desempenho do Application Insights no portal do Azure. A captura de tela mostra a alternância Servidor/Navegador e as chamadas HTTP recebidas pelo aplicativo realçadas.

4. Selecione uma Operação na tabela e escolha analisar uma amostra da solicitação.

   

   Captura de tela da tela Desempenho do Application Insights no portal do Azure. A captura de tela mostra uma operação POST e uma operação de exemplo da lista sugerida selecionada e realçada. O botão Analisar amostras está realçado.

   A transação de ponta a ponta é exibida para a solicitação selecionada. Nesse caso, foi criada uma revisão, incluindo uma imagem, para que inclua chamadas para o Armazenamento do Microsoft Azure e o Serviço de Linguagem (para análise de sentimentos). Isso inclui também chamadas de banco de dados no SQL Azure para persistir a revisão. Neste exemplo, o primeiro evento selecionado exibe informações relativas à chamada HTTP POST.

   

5. Selecione um item SQL para examinar o texto do comando SQL emitido para o banco de dados.

   

6. Opcionalmente, selecione as solicitações de dependência (de saída) para o Armazenamento do Microsoft Azure ou o Serviço de Linguagem.

7. Retorne à tela Desempenho e selecione Dependências para investigar chamadas em recursos externos. Observe que a tabela Operações inclui chamadas para Análise de Sentimento, Armazenamento de Blobs e SQL do Azure.

   

Registro em log de aplicativos com o Application Insights

Visão geral dos logs

O Application Insights é um tipo de provedor de log disponível para aplicativos ASP.NET Core que se torna disponível para aplicativos quando o pacote NuGet do Application Insights for ASP.NET Core é instalado e a coleta de telemetria do lado do servidor é habilitada.

Como lembrete, o código a seguir em Program.cs registra com o ApplicationInsightsLoggerProvider contêiner de injeção de dependência interno.

builder.Services.AddApplicationInsightsTelemetry();

Com o ApplicationInsightsLoggerProvider registrado como o provedor de log, o aplicativo estará pronto para fazer logon no Application Insights usando a injeção de construtor com ILogger ou a alternativa de tipo genérico ILogger<TCategoryName>.

Observação

Por padrão, o provedor de log é configurado para capturar automaticamente os eventos de log com gravidade LogLevel.Warning ou superior.

Considere o seguinte exemplo de controlador. Ele demonstra a injeção de ILogger, que é resolvida com o ApplicationInsightsLoggerProvider que está registrado com o contêiner de injeção de dependência. Observe no método Get que uma mensagem Informativa, de Aviso e de Erro é registrada.

Observação

Por padrão, o rastreamento de nível de informação não será registrado. Somente os níveis de Aviso e acima são capturados.

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInformation("An example of an Info trace..");
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Para saber mais, veja Entrar no ASP.NET Core.

Exibir logs no Application Insights

O ValuesController acima é implantado com o aplicativo de exemplo e está localizado na pasta Controladores do projeto.

1. Usando um navegador da internet, abra o aplicativo de exemplo. Na barra de endereço, anexe /api/Values e pressione Enter.

   

2. No portal do Azure, aguarde alguns instantes e selecione o recurso do Application Insights azure-cafe-insights-{SUFFIX}.

   

3. No menu à esquerda do recurso Application Insights, na seção Monitoramento, selecione Logs.

4. No painel Tabelas, na árvore do Application Insights, clique duas vezes na tabela de rastreamentos.

5. Modifique a consulta para recuperar rastreamentos do controlador Valores da seguinte maneira e selecione Executar para filtrar os resultados.

   traces 
   | where operation_Name == "GET Values/Get"
   

   Os resultados exibem as mensagens de registro presentes no controlador. Uma gravidade de log de dois indica um nível de aviso e uma severidade de log de três indica um nível de erro.

6. Como alternativa, também é possível gravar a consulta para recuperar os resultados com base na categoria do log. Por padrão, a categoria é o nome totalmente qualificado da classe em que o ILogger é injetado. Nesse caso, o nome da categoria será ValuesController (se houver um namespace associado à classe, o nome será prefixado com o namespace). Escreva novamente e execute a consulta a seguir para recuperar resultados com base na categoria.

   traces 
   | where customDimensions.CategoryName == "ValuesController"
   

Controlar o nível de logs enviados ao Application Insights

Implementações ILogger tem um mecanismo interno para aplicar a filtragem de log. Esse filtro permite que você controle os logs que são enviados para cada provedor registrado, incluindo o provedor do Application Insights. A filtragem pode ser feita na configuração (usando um arquivo appsettings.json) ou no código. Para obter mais informações sobre os níveis de log e as diretrizes sobre como usá-los adequadamente, consulte a documentação do Nível de Log.

Os exemplos a seguir mostram como aplicar regras de filtro ao ApplicationInsightsLoggerProvider para controlar o nível de logs enviados ao Application Insights.

Criar regras de filtro na configuração

O ApplicationInsightsLoggerProvider tem o alias de ApplicationInsights na configuração. A seção a seguir de um arquivo appsettings.json define o nível de log padrão para todos os provedores como LogLevel.Warning. A configuração do provedor ApplicationInsights, especificamente para categorias que começam com "ValuesController", substitui esse valor padrão por LogLevel.Error e superior.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

Implantar o aplicativo de exemplo com o código anterior em appsettings.json produzirá apenas o rastreamento de erro que está sendo enviado ao Application Insights para interagir com o ValuesController. Isso ocorre porque o LogLevel para a categoria ValuesController está definido como Error. Portanto, o rastreamento de Aviso é suprimido.

Desativar o log no Application Insights

Para desabilitar o log usando a configuração, defina todos os valores de LogLevel como "Nenhum".

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

Da mesma forma, no código, defina o nível padrão para ApplicationInsightsLoggerProvider e os níveis de log subsequentes como Nenhum.

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

SDK do código-fonte aberto

• Ler e contribuir para o código.

Para obter as atualizações e as correções de bugs mais recentes, confira as notas sobre a versão.

Próximas etapas

• Explore os fluxos dos usuários para compreender como os usuários navegam pelo aplicativo.
• Configure uma coleta de instantâneos para ver o estado do código-fonte e as variáveis no momento em que uma exceção é lançada.
• Use a API para enviar os seus eventos e métricas para uma exibição detalhada do desempenho e do uso do aplicativo.
• Visão geral da disponibilidade
• Injeção de dependência no ASP.NET Core
• Registro em log no ASP.NET Core
• Logs de rastreamento do .NET no Application Insights
• Auto-instrumentação para o Application Insights