Explorar os logs de rastreamento do .NET/.NET Core e do Python no Application Insights

  • Artigo

Envie logs de rastreamento de diagnóstico referentes ao seu aplicativo ASP.NET/ASP.NET Core do ILogger, NLog, log4Net ou System.Diagnostics.Trace para o Azure Application Insights. Para aplicativos do Python, envie logs de rastreamento de diagnóstico usando o AzureLogHandler no OpenCensus Python para o Azure Monitor. Em seguida, você pode explorá-los e pesquisá-los. Esses logs são mesclados com outros arquivos de log de seu aplicativo. Você pode usá-los para identificar rastreamentos associados a cada solicitação do usuário e correlacioná-los com outros eventos e relatórios de exceção.

Observação

Você precisa do módulo de captura de log? Ele é um adaptador útil para agentes de terceiros. No entanto, se você ainda não usa o NLog, o log4Net nem o System.Diagnostics.Trace, convém chamar apenas o Application Insights TrackTrace() diretamente.

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.

Instalar o log no seu aplicativo

Instale sua estrutura de registros em log escolhida em seu projeto, o que deve resultar em uma entrada em app.config ou em web.config.

 <configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener" type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Configurar o Application Insights para coletar logs

Adicione o Application Insights ao seu projeto se ainda não tiver feito isso e se houver uma opção para incluir o coletor de logs.

Ou então, clique com o botão direito do mouse no seu projeto no Gerenciador de Soluções para Configurar o Application Insights. Selecione a opção Configurar a coleta de rastreamento.

Observação

Não consegue ver o menu do Application Insights nem a opção de coletor de logs? Experimente Solucionar problemas.

Instalação manual

Use este método se o tipo de projeto não tiver suporte no instalador do Application Insights. Por exemplo, se for um projeto da área de trabalho do Windows.

  1. Se você pretende usar o log4net ou NLog, instale-o em seu projeto.

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

  3. Pesquise por Application Insights.

  4. Selecione um dos seguintes pacotes:

O pacote NuGet instala os assemblies necessários e, quando aplicável, modifica o web.config ou o app.config.

ILogger

Para obter exemplos de como usar a implementação de ILogger do Application Insights com aplicativos Console e ASP.NET Core, confira ApplicationInsightsLoggerProvider para logs do ILogger do .NET Core.

Inserir chamadas de log de diagnóstico

Se você usa System.Diagnostics.Trace, uma chamada típica é semelhante a:

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

Se você preferir log4net ou NLog, use:

    logger.Warn("Slow response - database01");

Usar eventos EventSource

É possível configurar eventos System.Diagnostics.Tracing.EventSource para que eles sejam enviados para o Application Insights como rastreamentos. Primeiro, instale o pacote NuGet Microsoft.ApplicationInsights.EventSourceListener. Depois, edite a seção TelemetryModules do arquivo ApplicationInsights.config.

    <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

Para cada fonte, você pode definir os seguintes parâmetros:

  • Nome especifica o nome do EventSource a ser coletado.
  • Nível especifica o nível de registros em log a ser coletado: Crítico, Erro, Informativo, LogAlways, Detalhado ou Aviso.
  • Palavras-chave (opcional) especificam o valor inteiro das combinações de palavras-chave a serem usadas.

Usar eventos DiagnosticSource

É possível configurar eventos System.Diagnostics.DiagnosticSource para que eles sejam enviados para o Application Insights como rastreamentos. Primeiro, instale o pacote NuGet Microsoft.ApplicationInsights.DiagnosticSourceListener. Em seguida, edite a seção "TelemetryModules" do arquivo ApplicationInsights.config.

    <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

Para cada origem de diagnóstico que você deseja rastrear, adicione uma entrada com o conjunto de atributos Name para definir o nome de sua origem de diagnóstico.

Usar eventos ETW

É possível configurar os eventos ETW (Rastreamento de Eventos para Windows) a serem enviados ao Application Insights como rastreamentos. Primeiro, instale o pacote NuGet Microsoft.ApplicationInsights.EtwCollector. Em seguida, edite a seção "TelemetryModules" do arquivo ApplicationInsights.config.

Observação

Eventos ETW só poderão ser coletados se o processo que hospeda o SDK estiver em execução em uma identidade que seja membro dos administradores ou usuários de log de desempenho.

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Para cada fonte, você pode definir os seguintes parâmetros:

  • ProviderName é o nome do provedor de ETW a ser coletado.
  • ProviderGuid especifica o GUID do provedor de ETW a ser coletado. Ele poderá ser usado em lugar de ProviderName.
  • Nível define o nível de registros em log a ser coletado. Ele pode ser Crítico, Erro, Informativo, LogAlways, Detalhado ou Aviso.
  • Palavras-chave (opcional) definem o valor inteiro das combinações de palavras-chave a serem usadas.

Usar a API de rastreamento diretamente

Você pode chamar a API de rastreamento do Application Insights diretamente. Os adaptadores de log usam essa API.

Por exemplo:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Uma vantagem de TrackTrace é que você pode colocar dados relativamente compridos na mensagem. Por exemplo, você pode codificar dados POST.

Você também pode adicionar um nível de severidade à mensagem. E, como ocorre com outros casos de telemetria, você pode adicionar valores de propriedade para ajudar a filtrar ou a pesquisar diferentes conjuntos de rastreamentos. Por exemplo:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

Agora em Pesquisa de Transações todas as mensagens de um nível de gravidade específico que se relacionam a um determinado banco de dados.

AzureLogHandler para OpenCensus Python

O Manipulador de Log do Azure Monitor permite exportar logs do Python para o Azure Monitor.

Instrumente o aplicativo com o SDK do OpenCensus Python para o Azure Monitor.

Este exemplo mostra como enviar um log de nível de aviso para Azure Monitor.

import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>'))
logger.warning('Hello, World!')

Explorar seus logs

Execute o aplicativo no modo de depuração ou implante-o em tempo real.

No painel de visão geral do aplicativo, no portal do Application Insights, escolha Pesquisa de Transações.

Por exemplo, você pode:

  • Filtre rastreamentos de log ou itens com propriedades específicas.
  • Inspecionar um item específico em detalhes.
  • Encontre outros dados de log do sistema relacionados à mesma solicitação de usuário (tem a mesma ID de operação).
  • Salve a configuração de uma página como um favorito.

Observação

Se o aplicativo enviar muitos dados e se você estiver usando o SDK do Application Insights para o ASP.NET versão 2.0.0-beta3 ou posterior, o recurso de amostragem adaptável poderá operar e enviar apenas uma parte de sua telemetria. Saiba mais sobre amostragem.

Solução de problemas

Encontre respostas para dúvidas comuns.

O que causa telemetria atrasada, uma rede sobrecarregada e transmissão ineficiente?

System.Diagnostics.Tracing tem um recurso de liberação automática. Esse recurso faz com que o SDK seja liberado com cada item de telemetria, o que é indesejável e pode causar problemas no adaptador de registro em log, como telemetria atrasada, uma rede sobrecarregada e transmissão ineficiente.

Como faço isso no Java?

Na instrumentação sem código Java, que é recomendada, os logs são coletados prontos para uso. Use o agente Java 3.0.

O agente Java do Application Insights coleta logs de Log4j, Logback e java.util.logging prontos para uso.

Não há nenhuma opção do Application Insights no menu de contexto do projeto?

  • Verifique se o Developer Analytics Tools está instalado no computador de desenvolvimento. No Visual Studio, vá para Ferramentas>Extensões e Atualizações e procure por Developer Analytics Tools. Se ele não estiver na aba Instalado, abra a guia Online e instale-o.
  • Esse tipo de projeto pode ser um no qual o Developer Analytics Tools não dá suporte. Use a instalação manual.

Não há nenhuma opção de adaptador de log na ferramenta de configuração?

  • Instale primeiro a estrutura de registros.
  • Se estiver usando System.Diagnostics.Trace, verifique se você o configurou no web.config.
  • Verifique se você tem a versão mais recente do Application Insights. No Visual Studio, acesse Ferramentas>Extensões e Atualizações e abra a guia Atualizações. Se o Developer Analytics Tools estiver presente, selecione-o para atualizá-lo.

Por que recebo a mensagem de erro "A chave de instrumentação não pode estar vazia"?

Você provavelmente instalou o pacote NuGet de adaptador de log sem instalar o Application Insights. No Gerenciador de Soluções, clique com o botão direito do mouse em ApplicationInsights.config e selecione Atualizar Application Insights. Você recebe uma solicitação para entrar no Azure e criar um recurso do Application Insights ou, alternativamente, reutilizar um recurso existente. Isso deve corrigir o problema.

Pode levar algum tempo para que todos os eventos e solicitações percorram o pipeline.

Que quantidade de dados é mantida?

Vários fatores afetam a quantidade dos dados retidos. Para obter mais informações, confira a seção de Limites da página de métricas de eventos do cliente.

Por que não vejo algumas entradas de log que eu esperava?

Talvez seu aplicativo envie grandes quantidades de dados e você esteja usando o SDK do Application Insights para ASP.NET, versão 2.0.0-beta3 ou posterior. Nesse caso, o recurso de amostragem adaptável pode operar e enviar apenas uma parte da telemetria. Saiba mais sobre amostragem.

Próximas etapas