Ativar insights de aplicações para aplicações ASP.NET Core

Este artigo descreve como ativar o Application Insights para uma aplicação ASP.NET Core implementada como uma App Web Azure. Esta implementação utiliza uma abordagem baseada em SDK, uma abordagem de auto-instrumentação também está disponível.

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

  • Pedidos
  • Dependências
  • Exceções
  • Contadores de desempenho
  • Batimentos cardíacos
  • Registos

Usaremos um exemplo de aplicação de MVC ASP.NET Core que visanet6.0. Pode aplicar estas instruções a todas as ASP.NET Core aplicações. Se estiver a usar o Serviço de Trabalhadores, use as instruções daqui.

Nota

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

Cenários suportados

O Application Insights SDK para ASP.NET Core pode monitorizar as suas aplicações independentemente de onde ou como funcionam. Se a sua aplicação estiver em execução e tiver conectividade de rede com a Azure, a telemetria pode ser recolhida. A monitorização de Insights de Aplicação é suportada em todos os lugares .NET Core é suportado. O suporte abrange os seguintes cenários:

  • Sistema operativo: Windows, Linux ou Mac
  • Método de hospedagem: Em processo ou fora do processo
  • Método de implantação: Quadro dependente ou autossuficiente
  • Servidor Web: IIS (Internet Information Server) ou Kestrel
  • Plataforma de hospedagem: A funcionalidade Aplicações Web de Serviço de Aplicações do Azure, Azure VM, Docker, Azure Kubernetes Service (AKS), e assim por diante
  • .NET Core versão: Todas as versões oficialmente suportadas .NET Core que não estão em pré-visualização
  • IDE: Visual Studio, Visual Studio Code ou linha de comando

Pré-requisitos

Se quiser seguir as orientações deste artigo, são necessários alguns pré-requisitos.

  • Visual Studio 2022
  • Cargas de trabalho do Estúdio Visual: ASP.NET e desenvolvimento web, armazenamento e processamento de dados e 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

Por favor, siga as orientações para implementar a aplicação da amostra a partir do seu repositório GitHub..

A fim de fornecer nomes globalmente únicos a alguns recursos, foi atribuído um sufixo de 5 caracteres. Por favor, tome nota deste sufixo para ser usado mais tarde neste artigo.

A listagem de recursos Azure implantado apresenta com o sufixo de 5 caracteres realçado.

Criar um recurso do Application Insights

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

  2. A partir do menu de barra de ferramentas superior, selecione + Criar.

    O grupo de recursos application-insights-azure-café exibe com o botão + Criar realçado no menu da barra de ferramentas.

  3. No ecrã criar um ecrã de recursos , procure e selecione Application Insights na caixa de texto de pesquisa do mercado.

    O Criar um ecrã de recursos apresenta com Insights de Aplicação introduzidos na caixa de pesquisa e Insights de Aplicação realçados pelos resultados da pesquisa.

  4. No ecrã geral do recurso 'Insights' de aplicação, selecione Criar.

    O ecrã geral do Application Insights apresenta com o botão Criar realçado.

  5. No separador 'Basics' do ecrã 'Insights de Aplicação'. Preencha o formulário da seguinte forma e, em seguida, selecione o botão 'Rever +' criar . Os campos não especificados no quadro abaixo podem manter os seus valores predefinidos.

    Campo Valor
    Nome Introduza azure-cafe-application-insights-{SUFFIX}, substituindo {SUFFIX} pelo valor de sufixo apropriado registado anteriormente.
    Região Selecione a mesma região escolhida para a implementação dos recursos do artigo.
    Área de trabalho do Log Analytics Selecione azure-cafe-log-analytics-workspace, em alternativa, um novo espaço de trabalho de analítica de registo pode ser criado aqui.

    O separador 'Insights Basics' apresenta um formulário povoado com os valores anteriores.

  6. Uma vez passada a validação, selecione Criar para implementar o recurso.

    O ecrã de validação do Application Insights apresenta visualizações que indicam a validação passada e o botão Criar é realçado.

  7. Uma vez concluída a implementação, volte ao application-insights-azure-cafe grupo de recursos e selecione o recurso Application Insights implantado.

    O grupo de recursos Azure Cafe exibe com o recurso Application Insights realçado.

  8. No ecrã geral do recurso Application Insights, copie o valor da cadeia de ligação para utilização na secção seguinte deste artigo.

    O ecrã de visão geral do Pedido apresenta-se com o valor de cadeia de ligação realçado e o botão Copy selecionado.

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

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

    O grupo de recursos Azure Cafe exibe com o recurso azure-café-web-{SUFFIX} realçado.

  2. A partir do menu esquerdo, por baixo do cabeçalho Definições, selecione Configuração. Em seguida, no separador Definições de Aplicação , selecione + Nova definição de aplicação por baixo do cabeçalho de definições de aplicação.

    O ecrã de Serviço de Aplicações apresenta-se com o item de Configuração selecionado a partir do menu esquerdo e o botão de ferramentas de definição de aplicação + novo.

  3. Na lâmina de definição de aplicação Add/Edit, preencha o formulário da seguinte forma e selecione OK.

    Campo Valor
    Nome APPLICATIONINSIGHTS_CONNECTION_STRING
    Valor Cole a cadeia de ligação Application Insights obtida na secção anterior.

    A lâmina de definição de aplicação Add/Edit exibe povoados com os valores anteriores.

  4. No ecrã de configuração Serviço de Aplicações, selecione o botão Guardar o botão Guardar o menu da barra de ferramentas. Quando solicitado para guardar as alterações, selecione Continue.

    O ecrã de configuração Serviço de Aplicações apresenta-se com o botão Guardar realçado no menu da barra de ferramentas.

Instale o pacote NuGet Insights de Aplicações

Precisamos configurar a aplicação web ASP.NET Core MVC para enviar telemetria. Isto é realizado usando o pacote De Aplicações Insights para aplicações web ASP.NET Core.

  1. Com o Visual Studio, aberto 1 - Starter Application\src\AzureCafe.sln.

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

    O Explorador de Soluções exibe com Pacotes Manage NuGet selecionados a partir do menu de contexto.

  3. Selecione o separador Procurar e, em seguida, procurar e selecionar Microsoft.ApplicationInsights.AspNetCore. Selecione Instalar e aceitar os termos da licença. Recomenda-se a utilização da versão mais recente do estável. Encontre notas de lançamento completas para o SDK no repo GitHub de código aberto.

    O separador NuGet aparece com o separador Browse selecionado e Microsoft.ApplicationInsights.AspNetCore está inserido na caixa de pesquisa. O pacote Microsoft.ApplicationInsights.AspNetCore é selecionado a partir de uma lista de resultados. No painel direito, a versão mais recente estáveis é selecionada a partir de uma lista de drop down e o botão De instalar é realçado.

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

Ativar a telemetria do lado do servidor do Servidor Do Servidor

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

  1. A partir do Explorador de Soluções do Estúdio Visual, localize e abra o ficheiro .cs Programa.

    O Estúdio Visual Explorador de Soluções exibe com o programa.cs destacado.

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

    builder.Services.AddApplicationInsightsTelemetry();
    

    Uma janela de código aparece com o corte de código anterior realçado.

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

Os passos anteriores são suficientes para ajudá-lo a começar a recolher telemetria do lado do servidor. Esta aplicação tem componentes do lado do cliente, siga os próximos passos para começar a recolher telemetria de uso.

  1. No explorador visual Studio Solution, localize e abra \Views\_ViewImports.cshtml. Adicione o seguinte código no final do ficheiro existente.

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    

    O ficheiro _ViewImports.cshtml apresenta-se com a linha de código anterior realçada.

  2. Para ativar adequadamente a monitorização do lado do cliente para a sua aplicação, o snippet JavaScript deve aparecer na <head> secção de cada página da sua aplicação que pretende monitorizar. No Visual Studio Explorador de Soluções, localizar e abrir\Views\Shared\_Layout.cshtml, insira o seguinte código imediatamente antes da etiqueta de fecho<\head>.

    @Html.Raw(JavaScriptSnippet.FullScript)
    

    O ficheiro _Layout.cshtml apresenta-se com a linha de código anterior realçada na secção principal da página.

    Dica

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

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

Nota

A injeção javaScript proporciona uma experiência de configuração padrão. Se necessitar de configuração para além da definição da cadeia de ligação, é-lhe exigido que remova a injeção automática como descrito acima e adicione manualmente o JavaScript SDK.

Permitir a monitorização das consultas de base de dados

Ao investigar causas para a degradação do desempenho, é importante incluir insights nas chamadas de base de dados. Ativar a monitorização através da configuração do módulo de dependência. A monitorização da dependência, incluindo o SQL, é ativada por padrão. Os seguintes passos podem ser seguidos para capturar todo o texto de consulta SQL.

Nota

O texto SQL pode conter dados sensíveis, tais como palavras-passe e PII. Tenha cuidado ao ativar esta função.

  1. A partir do Explorador de Soluções do Estúdio Visual, localize e abra o ficheiro .cs Programa.

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

    using Microsoft.ApplicationInsights.DependencyCollector;
    
  3. Imediatamente seguindo o builder.Services.AddApplicationInsightsTelemetry() código, insira o seguinte para ativar a instrumentação do texto de comando SQL.

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

    Uma janela de código aparece com o código anterior realçado.

Executar a aplicação web do Azure Cafe

Após a implementação do código de aplicação web, a telemetria fluirá para o Application Insights. O Application Insights SDK recolhe automaticamente pedidos web de entrada na sua aplicação.

  1. Clique com o direito no projeto AzureCafe em Explorador de Soluções e selecione Publicar no menu de contexto.

    O Visual Studio Explorador de Soluções apresenta com o projeto Azure Cafe selecionado e o item do menu de contexto De publicação em destaque.

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

    O AzureCafe publica ecrãs de perfil com o botão Publicar em destaque.

  3. Uma vez que a publicação tenha sido bem sucedida, uma nova janela do navegador abre para a aplicação web do Azure Cafe.

    A aplicação web Azure Cafe exibe.

  4. Realizar várias atividades na aplicação web para gerar alguma telemetria.

    1. Selecione Detalhes ao lado de um Café para ver o seu menu e comentários.

      Uma parte da lista do Café Azure aparece com o botão Detalhes realçado.

    2. No ecrã do Café, selecione o separador Avaliações para visualizar e adicione comentários. Selecione o botão de revisão Adicionar para adicionar uma revisão.

      O ecrã de detalhes do Café apresenta com o botão de revisão Adicionar realçado.

    3. No diálogo de revisão Criar, insira um nome, classificação, comentários e carremine uma foto para a revisão. Uma vez concluído, selecione 'Adicionar' à revisão.

      O Diálogo de revisão Criar.

    4. Repita a adição de comentários conforme desejado para gerar telemetria adicional.

Métricas ao vivo

As Métricas Vivas podem ser utilizadas para verificar rapidamente se a monitorização do Application Insights está configurada corretamente. Pode levar alguns minutos para a telemetria aparecer no portal e na análise, mas live metrics mostra o uso do CPU do processo de execução em tempo real. Também pode mostrar outras telemetrias como Pedidos, Dependências e Vestígios.

Mapa da aplicação

A aplicação da amostra faz chamadas para vários recursos Azure, incluindo SQL do Azure, Armazenamento de Blobs do Azure e o Serviço de Línguas Azure (para análise de sentimentos de revisão).

A arquitetura da aplicação de amostra do Azure Cafe exibe.

Application Insights introspects incoming telemetria data e é capaz de gerar um mapa visual de integrações detetadas do sistema.

  1. Acesso e entrada no portal do Azure.

  2. Abra o grupo application-insights-azure-cafede recursos de aplicação de amostra .

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

  4. Selecione mapa de aplicação a partir do menu esquerdo, por baixo do título Investigar . Observe o mapa de aplicação gerado.

    O mapa de aplicações do Application Insights exibe.

Visualização de chamadas HTTP e texto de comando SQL de base de dados

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

  2. Por baixo do cabeçalho Investigar no menu esquerdo, selecione Performance.

  3. O separador Operações contém detalhes das chamadas HTTP recebidas pela aplicação. Também pode alternar entre as visualizações de dados do Servidor e do Browser (lado do cliente).

    O ecrã de Desempenho do Application Insights apresenta-se com o alternância entre o Servidor e o Browser destacado juntamente com a lista de chamadas HTTP recebidas pela aplicação.

  4. Selecione uma operação da tabela e opte por perfurar uma amostra do pedido.

    O ecrã de desempenho apresenta-se com uma operação POST selecionada, o botão Drill em amostras é realçado e uma amostra é selecionada da lista sugerida.

  5. A transação de ponta a ponta apresenta o pedido selecionado. Neste caso, foi criada uma revisão incluindo uma imagem, incluindo chamadas para o Azure Storage, o Serviço de Linguagem (para análise de sentimento), bem como chamadas de base de dados para SQL Azure persistir a revisão. Neste exemplo, o primeiro Evento selecionado apresenta informações relativas à chamada HTTP POST.

    A transação de ponta a ponta apresenta-se com a chamada HTTP Post selecionada.

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

    A transação de ponta a ponta apresenta-se com detalhes do comando SQL.

  7. Selecione opcionalmente Pedidos de Dependência (outgoing) para o Azure Storage ou o Serviço de Idiomas.

  8. Volte ao ecrã Performance e selecione o separador Dependencies para investigar chamadas em recursos externos. Note que a tabela Operações inclui chamadas para Análise de Sentimento, Armazenamento de Bolhas e SQL do Azure.

    O ecrã 'Desempenho' apresenta-se com o separador Dependencies selecionado e a tabela Operações em destaque.

Registo de aplicações com Insights de Aplicação

Visão geral do registo

O Application Insights é um tipo de prestador de serviços de registo disponível para aplicações ASP.NET Core que fica disponível para aplicações quando o pacote NuGet de aplicações para ASP.NET Core é instalado e a recolha de telemetria do lado do servidor está ativada. Como lembrete, o seguinte código no Programa.cs regista o ApplicationInsightsLoggerProvider com o recipiente de injeção de dependência incorporada.

builder.Services.AddApplicationInsightsTelemetry();

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

Nota

Com as definições predefinidas, o fornecedor de registos está configurado para capturar automaticamente eventos de registo com uma gravidade ou LogLevel.Warning maior.

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

Nota

Por predefinição, o rastreio do nível de informação não será registado. Apenas 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.LogInfo("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 mais informações, consulte iniciar sessão em ASP.NET Core.

Ver registos em Insights de Aplicação

O ValuesController acima é implantado com a aplicação da amostra e está localizado na pasta controladores do projeto.

  1. Utilizando um navegador de internet, abra a aplicação da amostra. Na barra de endereços, apêndice /api/Values e prima Enter.

    Uma janela do navegador exibe com /api/Valores anexados ao URL na barra de endereços.

  2. Aguarde alguns momentos e, em seguida, volte ao recurso Application Insights no portal do Azure.

    Um grupo de recursos exibe com o recurso Application Insights realçado.

  3. A partir do menu esquerdo do recurso Application Insights, selecione Registos por baixo da secção de Monitorização . No painel tabelas , clique duas vezes na tabela de vestígios , localizada sob a árvore De Insights de Aplicação . Modificar a consulta para obter vestígios para o controlador Valores da seguinte forma e, em seguida, selecione Executar para filtrar os resultados.

    traces 
    | where operation_Name == "GET Values/Get"
    
  4. Observe os resultados, apresentando as mensagens de registo presentes no controlador. Uma gravidade do registo de 2 indica um nível de aviso, e uma gravidade do registo de 3 indica um nível de Erro.

  5. Em alternativa, a consulta também pode ser escrita para obter resultados com base na categoria do registo. Por predefinição, a categoria é o nome totalmente qualificado da classe onde o ILogger é injetado, neste caso ValuesController (se houver um espaço de nome associado à classe o nome será pré-fixado com o espaço de nome). Reescreva 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 Insights de Aplicação

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

Os exemplos a seguir mostram como aplicar regras de ApplicationInsightsLoggerProvider filtro 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 seguinte secção de um ficheiro appsettings.json define o nível de registo predefinido para todos os fornecedores para LogLevel.Warning. A configuração para o fornecedor ApplicationInsights especificamente para categorias que começam com "ValuesController" sobrepõe este valor padrão com LogLevel.Error e mais alto.

{
  //... 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 da amostra com o código anterior em appsettings.json produzirá apenas o traço de erro enviado para o Application Insights ao interagir com o ValuesController. Isto porque o LogLevel para a categoria ValuesController está definido como Error, pelo que o traço de aviso é suprimido.

Desativar o registo de registos para Insights de Aplicação

Para desativar a configuração de registo, deslote todos os valores do LogLevel para "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, dentro do código, desafine o nível predefinido para os ApplicationInsightsLoggerProvider níveis de registo e quaisquer subsequentes para Nenhum.

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

SDK de código aberto

Para obter as últimas atualizações e correções de erros, consulte as notas de lançamento.

Passos seguintes