Ativar o Application Insights para aplicações ASP.NET Core

Este artigo descreve como ativar o Application Insights para uma aplicação ASP.NET Core implementada como uma Aplicação Web do Azure. Esta implementação utiliza uma abordagem baseada em SDK. Também está disponível uma abordagem de intrusão automática .

O Application Insights pode recolher a seguinte telemetria da sua aplicação ASP.NET Core:

• Pedidos
• Dependências
• Exceções
• Contadores de desempenho
• Heartbeats
• Registos

Para uma aplicação de exemplo, vamos utilizar uma aplicação MVC ASP.NET Core que visa net6.0. No entanto, pode aplicar estas instruções a todas as aplicações ASP.NET Core. Se estiver a utilizar o Serviço de Trabalho, utilize as instruções aqui.

Nota

Está disponível uma oferta .NET baseada em OpenTelemetry . Saiba mais.

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas deixaremos de fornecer atualizações ou suporte para a funcionalidade. Transição para cadeias de ligação para tirar partido das novas capacidades.

Cenários suportados

O SDK do Application Insights para ASP.NET Core pode monitorizar as suas aplicações independentemente de onde ou como são executadas. Se a sua aplicação estiver em execução e tiver conectividade de rede ao Azure, o Application Insights pode recolher telemetria da mesma. A monitorização do Application Insights é suportada em todos os locais onde o .NET Core é suportado. São suportados os seguintes cenários:

• Sistema operativo: Windows, Linux ou Mac
• Método de alojamento: Em processo ou fora do processo
• Método de implementação: Dependente da arquitetura ou autónomo
• Servidor Web: Internet Information Server (IIS) ou Kestrel
• Plataforma de alojamento: a funcionalidade Aplicações Web de Serviço de Aplicações do Azure, VM do Azure, Docker, Azure Kubernetes Service (AKS), etc.
• Versão do .NET Core: todas as versões do .NET Core suportadas oficialmente que não estão em pré-visualização
• IDE: Visual Studio, Visual Studio Code ou linha de comandos

Pré-requisitos

Para concluir este tutorial, precisa de:

• Visual Studio 2022
• As seguintes cargas de trabalho do Visual Studio:
  • Desenvolvimento ASP.NET e Web
  • Armazenamento e processamento de dados
  • Desenvolvimento do Azure
• .NET 6.0
• Subscrição do Azure e conta de utilizador (com a capacidade de criar e eliminar recursos)

Implementar recursos do Azure

Siga a documentação de orientação para implementar a aplicação de exemplo a partir do repositório do GitHub.

Para fornecer nomes globalmente exclusivos aos recursos, é atribuído um sufixo de seis carateres a alguns recursos. Anote este sufixo para utilização mais adiante neste artigo.

Criar um recurso do Application Insights

1. Na portal do Azure, selecione o grupo de recursos application-insights-azure-café.

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

   

3. No ecrã Criar um recurso , procure e selecione Application Insights na caixa de texto de pesquisa do marketplace.

   

   Captura de ecrã do ecrã Criar um recurso no portal do Azure. A captura de ecrã mostra uma pesquisa do Application Insights realçada e o Application Insights a ser apresentado nos resultados da pesquisa, que também está realçado.

4. No ecrã de descrição geral do recurso do Application Insights, selecione Criar.

   

5. No ecrã Application Insights, no separador Informações Básicas , preencha o formulário com a seguinte tabela e, em seguida, selecione o botão Rever + criar . Os campos não especificados na tabela abaixo podem manter os valores predefinidos.

   Campo	Valor
   Nome	Introduza azure-cafe-application-insights-{SUFFIX}, substituindo {SUFIXO} pelo valor de sufixo adequado registado anteriormente.
   Region	Selecione a mesma região escolhida ao implementar os recursos do artigo.
   Área de trabalho do Log Analytics	Selecione azure-café-log-analytics-workspace. Em alternativa, pode criar uma nova área de trabalho do Log Analytics.

   

6. Assim que a validação for aprovada, selecione Criar para implementar o recurso.

   

7. Assim que o recurso for implementado, regresse ao application-insights-azure-cafe grupo de recursos e selecione o recurso do Application Insights que implementou.

   

8. No ecrã Descrição geral do recurso do Application Insights, selecione o botão Copiar para a área de transferência para copiar o valor cadeia de ligação. Irá utilizar o valor cadeia de ligação na secção seguinte deste artigo.

   

   Captura de ecrã do ecrã Descrição Geral do Application Insights no portal do Azure. A captura de ecrã mostra o valor cadeia de ligação realçado e o botão Copiar para a área de transferência selecionado e realçado.

Configurar a definição da aplicação do Application Insights cadeia de ligação na web Serviço de Aplicações

1. Regresse ao application-insights-azure-cafe grupo de recursos e abra o recurso azure-café-web-{SUFIXO} Serviço de Aplicações.

   

2. No menu esquerdo, na secção Definições, selecione Configuração. Em seguida, no separador Definições da aplicação, selecione + Nova definição da aplicação abaixo do cabeçalho Definições da aplicação.

   

   Captura de ecrã do ecrã de recursos Serviço de Aplicações no portal do Azure. A captura de ecrã mostra a Configuração no menu esquerdo na secção Definições selecionada e realçada, o separador Definições da aplicação selecionado e realçado e o botão da barra de ferramentas + Nova definição da aplicação realçado.

3. No painel de definições Adicionar/Editar aplicação, preencha o formulário da seguinte forma e selecione OK.

   Campo	Valor
   Nome	APPLICATIONINSIGHTS_CONNECTION_STRING
   Valor	Cole o valor de cadeia de ligação do Application Insights que copiou na secção anterior.

   

4. No ecrã configuração do Serviço de Aplicações, selecione o botão Guardar no menu da barra de ferramentas. Quando lhe for pedido para guardar as alterações, selecione Continuar.

   

Instalar o Pacote NuGet do Application Insights

Temos de configurar o ASP.NET Core aplicação Web MVC para enviar telemetria. Isto é feito com o pacote NuGet do Application Insights para aplicações Web ASP.NET Core.

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

2. No painel de Explorador de Soluções do Visual Studio, clique com o botão direito do rato no ficheiro de projeto do AzureCafe e selecione Gerir Pacotes NuGet.

   

3. Selecione o separador Procurar e, em seguida, procure e selecioneMicrosoft.ApplicationInsights.AspNetCore. Selecione Instalar e aceite os termos de licenciamento. Recomenda-se que utilize a versão estável mais recente. Para obter as notas de versão completas do SDK, veja o repositório open source do GitHub.

   

   Captura de ecrã que mostra a interface de utilizador do Gestor de Pacotes NuGet no Visual Studio com o separador Procurar selecionado. Microsoft.ApplicationInsights.AspNetCore é introduzido na caixa de pesquisa e o pacote Microsoft.ApplicationInsights.AspNetCore está selecionado a partir de uma lista de resultados. No painel direito, a versão estável mais recente do pacote Microsoft.ApplicationInsights.AspNetCore está selecionada numa lista pendente e o botão Instalar está realçado.

   Mantenha o Visual Studio aberto para a secção seguinte do artigo.

Ativar a telemetria do lado do servidor do Application Insights

O pacote NuGet do Application Insights para ASP.NET Core aplicações Web encapsula funcionalidades para permitir o envio de telemetria do lado do servidor para o recurso do Application Insights no Azure.

1. No visual studio Explorador de Soluções, abra o ficheiro Program.cs.

   

2. Insira o seguinte código antes da builder.Services.AddControllersWithViews() instrução . Este código lê automaticamente o valor de cadeia de ligação do Application Insights a partir da configuração. O AddApplicationInsightsTelemetry método regista o ApplicationInsightsLoggerProvider com o contentor de injeção de dependências incorporado que, em seguida, será utilizado para satisfazer os pedidos de implementação do ILogger e do ILogger<TCategoryName> .

   builder.Services.AddApplicationInsightsTelemetry();
   

   

   Dica

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

Ativar a telemetria do lado do cliente para aplicações Web

Os passos anteriores são suficientes para o ajudar a começar a recolher telemetria do lado do servidor. A aplicação de exemplo tem componentes do lado do cliente. Siga os passos seguintes para começar a recolher a telemetria de utilização.

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

2. Adicione o seguinte código no final do ficheiro existente.

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

   

3. Para ativar corretamente a monitorização do lado do cliente para a sua aplicação, no Visual Studio Explorador de Soluções, abra \Views\Shared\_Layout.cshtml e insira o seguinte código imediatamente antes da etiqueta de fecho<\head>. Este fragmento de JavaScript tem de ser inserido na <head> secção de cada página da sua aplicação que pretende monitorizar.

   @Html.Raw(JavaScriptSnippet.FullScript)
   

   

   Dica

   Uma alternativa à utilização FullScript é ScriptBody. Utilize ScriptBody se precisar de controlar a <script> etiqueta para definir uma Política de Segurança de Conteúdo:

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

Nota

A injeção de JavaScript proporciona uma experiência de configuração predefinida. Se precisar de configuração para além da definição do cadeia de ligação, terá de remover a injeção automática, conforme descrito acima, e adicionar manualmente o SDK JavaScript.

Ativar a monitorização de consultas de base de dados

Ao investigar as causas da degradação do desempenho, é importante incluir informações sobre chamadas de base de dados. Pode ativar a monitorização ao configurar o módulo de dependência. A monitorização de dependências, incluindo o SQL, está ativada por predefinição.

Siga estes passos para capturar o texto completo da consulta SQL.

Nota

O texto SQL pode conter dados confidenciais, como palavras-passe e PII. Tenha cuidado ao ativar esta funcionalidade.

1. No visual studio Explorador de Soluções, abra o ficheiro Program.cs.

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

   using Microsoft.ApplicationInsights.DependencyCollector;
   

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

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

   

Executar a aplicação Web do Azure Cafe

Depois de implementar o código da aplicação Web, a telemetria fluirá para o Application Insights. O SDK do Application Insights recolhe automaticamente pedidos Web recebidos para a sua aplicação.

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

   

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

   

   Quando a aplicação Web do Azure Cafe é publicada com êxito, é aberta uma nova janela do browser na aplicação Web do Azure Cafe.

   

3. Para gerar alguma telemetria, siga estes passos na aplicação Web para adicionar uma revisão.

   1. Para ver o menu e as críticas de um café, selecione Detalhes junto a um café.

      

   2. Para ver e adicionar críticas, no ecrã Café, selecione o separador Críticas . Selecione o botão Adicionar revisão para adicionar uma crítica.

      

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

      

   4. Se precisar de gerar telemetria adicional, adicione críticas adicionais.

Métricas em direto

Pode utilizar o Live Metrics para verificar rapidamente se a monitorização do Application Insights está configurada corretamente. O Live Metrics mostra a utilização da CPU do processo em execução quase em tempo real. Também pode mostrar outra telemetria, como Pedidos, Dependências e Rastreios. Tenha em atenção que a telemetria pode demorar alguns minutos a aparecer no portal e na análise.

Ver o mapa da aplicação

A aplicação de exemplo faz chamadas para vários recursos do Azure, incluindo SQL do Azure, Armazenamento de Blobs do Azure e o Serviço de Linguagem do Azure (para análise de sentimentos).

O Application Insights introspecta os dados telemétricos recebidos e consegue gerar um mapa visual das integrações do sistema que deteta.

1. Inicie sessão no portal do Azure.

2. Abra o grupo de recursos da aplicação de exemplo, que é application-insights-azure-cafe.

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

4. No menu esquerdo, por baixo do cabeçalho Investigar , selecione Mapa da aplicação. Observe o Mapa da aplicação gerado.

   

Ver chamadas HTTP e texto do comando SQL da base de dados

1. Na portal do Azure, abra o recurso do Application Insights.

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

3. O separador Operações contém detalhes das chamadas HTTP recebidas pela aplicação. Para alternar entre as vistas Servidor e Browser (do lado do cliente) dos dados, utilize o botão de alternar Servidor/Browser.

   

   Captura de ecrã do ecrã Desempenho do Application Insights no portal do Azure. A captura de ecrã mostra o botão de alternar Servidor/Browser e as chamadas HTTP recebidas pela aplicação realçadas.

4. Selecione uma Operação na tabela e opte por explorar uma amostra do pedido.

   

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

   A transação ponto a ponto é apresentada para o pedido selecionado. Neste caso, foi criada uma revisão, incluindo uma imagem, pelo que inclui chamadas para o Armazenamento do Microsoft Azure e para o Serviço de Linguagem (para análise de sentimentos). Também inclui chamadas de base de dados para SQL Azure para manter a revisão. Neste exemplo, o primeiro Evento selecionado apresenta informações relativas à chamada HTTP POST.

   

5. Selecione um item SQL para rever o texto do comando SQL emitido para a base de dados.

   

6. Opcionalmente, selecione os pedidos de Dependência (envio) para o Armazenamento do Azure ou para o Serviço de Idiomas.

7. Regresse ao ecrã Desempenho e selecione o separador Dependências para investigar chamadas para recursos externos. Repare que a tabela Operações inclui chamadas para Análise de Sentimentos, Armazenamento de Blobs e SQL do Azure.

   

Registo de aplicações com o Application Insights

Descrição geral do registo

O Application Insights é um tipo de fornecedor de registos disponível para ASP.NET Core aplicações que ficam disponíveis para aplicações quando o pacote NuGet do Application Insights para ASP.NET Core é instalado e a coleção de telemetria do lado do servidor está ativada.

Como lembrete, o seguinte código em Program.cs regista o ApplicationInsightsLoggerProvider com o contentor de injeção de dependências incorporado.

builder.Services.AddApplicationInsightsTelemetry();

Com o ApplicationInsightsLoggerProvider registado como fornecedor de registos, a aplicação está pronta para iniciar sessão no Application Insights através da injeção de construtores com ILogger ou da alternativa ILogger<TCategoryName>de tipo genérico .

Nota

Por predefinição, o fornecedor de registos está configurado para capturar automaticamente eventos de registo com uma gravidade igual LogLevel.Warning ou superior.

Considere o seguinte controlador de exemplo. Demonstra a injeção de ILogger, que é resolvida com o ApplicationInsightsLoggerProvider que está registado no contentor de injeção de dependências. Observe no método Get que uma mensagem Informativa, Aviso e Erro são gravadas.

Nota

Por predefinição, o rastreio ao nível da informação não será registado. Apenas os níveis 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 obter mais informações, veja Iniciar sessão no ASP.NET Core.

Ver registos no Application Insights

O ValuesController acima é implementado com a aplicação de exemplo e está localizado na pasta Controladores do projeto.

1. Com um browser, abra a aplicação de exemplo. Na barra de endereço, acrescente /api/Values e prima Enter.

   

2. No portal do Azure, aguarde alguns momentos e, em seguida, selecione o recurso azure-café-insights-{SUFFIX} Application Insights.

   

3. No menu esquerdo do recurso do Application Insights, na secção Monitorização , selecione Registos.

4. No painel Tabelas , na árvore do Application Insights , faça duplo clique na tabela de rastreios .

5. Modifique a consulta para obter rastreios para o controlador Valores da seguinte forma e, em seguida, selecione Executar para filtrar os resultados.

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

   Os resultados apresentam as mensagens de registo presentes no controlador. Uma gravidade de registo de 2 indica um nível de aviso e uma gravidade de registo de 3 indica um Nível de erro.

6. Em alternativa, também pode escrever a consulta para obter resultados com base na categoria do registo. Por predefinição, a categoria é o nome completamente qualificado da classe em que o ILogger é injectado. Neste caso, o nome da categoria é ValuesController (se existir um espaço de nomes associado à classe, o nome será prefixado no espaço de nomes). Volte a escrever e execute a seguinte consulta para obter resultados com base na categoria.

   traces 
   | where customDimensions.CategoryName == "ValuesController"
   

Controlar o nível de registos enviados para o Application Insights

ILogger as implementações têm um mecanismo incorporado para aplicar a filtragem de registos. Esta filtragem permite-lhe controlar os registos que são enviados para cada fornecedor registado, incluindo o fornecedor do Application Insights. Pode utilizar a filtragem na configuração (utilizando um ficheiro appsettings.json ) ou no código. Para obter mais informações sobre os níveis de registo e documentação de orientação sobre como utilizá-los adequadamente, veja a documentação do Nível de Registo .

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

Criar regras de filtro com configuração

O ApplicationInsightsLoggerProvider é aliased como ApplicationInsights na configuração. A secção seguinte de um ficheiro appsettings.json define o nível de registo predefinido para todos os fornecedores como LogLevel.Warning. A configuração do fornecedor applicationInsights, especificamente para categorias que começam com "ValuesController", substitui este valor predefinido com 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
      }
    }
  }
}

A implementação da aplicação de exemplo com o código anterior em appsettings.json produzirá apenas o rastreio de erros enviado para o Application Insights ao interagir com o ValuesController. Isto deve-se ao facto de o LogLevel da categoria ValuesController estar definido como Erro. Por conseguinte, o rastreio de aviso é suprimido.

Desativar o registo no Application Insights

Para desativar o registo com a configuração, defina todos os valores 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 predefinido para os ApplicationInsightsLoggerProvider níveis de registo e quaisquer níveis de registo 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 open source

• Leia e contribua para o código.

Para obter as atualizações mais recentes e correções de erros, veja as notas de versão.

Passos seguintes

• Explore os fluxos de utilizador para compreender como os utilizadores navegam através da sua aplicação.
• Configure uma coleção de instantâneos para ver o estado do código fonte e das variáveis no momento em que é emitida uma exceção.
• Utilize a API para enviar os seus próprios eventos e métricas para uma vista detalhada do desempenho e utilização da sua aplicação.
• Descrição geral da disponibilidade
• Injeção de Dependências no ASP.NET Core
• Iniciar sessão no ASP.NET Core
• Registos de rastreio .NET no Application Insights
• Autoinstrumentation for Application Insights