Application Insights para Java 2.x

  • Artigo

Cuidado

Este artigo se aplica ao Application Insights Java 2.x, que não é mais recomendado.

A documentação da versão mais recente pode ser encontrada em Application Insights Java 3.x.

Neste artigo, você aprenderá a usar o Application Insights Java 2.x. Este artigo mostra como:

  • Iniciar e saber como instrumentar solicitações, rastrear dependências, coletar contadores de desempenho, diagnosticar problemas e exceções de desempenho e escrever código para rastrear o que os usuários fazem com o aplicativo.
  • Enviar logs de rastreamento ao Application Insights e explorá-los usando o portal do Application Insights.
  • Monitorar dependências, exceções identificadas e tempos de execução de método em aplicativos Web Java.
  • Filtrar a telemetria no aplicativo Web Java.
  • Explorar as métricas de desempenho do sistema Linux no Application Insights usando collectd.
  • Medir métricas para código de aplicativo baseado em JVM (Máquina Virtual Java). Exportar os dados para seus sistemas de monitoramento favoritos usando o monitoramento de aplicativo Micrometer.

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.

Introdução ao Application Insights em um projeto Web Java

Nesta seção, você usará o SDK do Application Insights para instrumentar solicitações, rastrear dependências, coletar contadores de desempenho, diagnosticar problemas e exceções de desempenho e escrever código para rastrear o que os usuários fazem com seu aplicativo.

Application Insights é um serviço de análise extensível para desenvolvedores da Web que ajuda você a entender o desempenho e o uso de seu aplicativo em tempo real. O Application Insights oferece suporte a aplicativos Java em execução no Windows, no Unix ou no Linux.

Pré-requisitos

Você precisa de:

Obter uma chave de instrumentação do Application Insights

  1. Entre no portal do Azure.

  2. No portal do Azure, crie um recurso Application Insights. Defina o tipo de aplicativo para aplicativo Web Java.

  3. Localize a chave de instrumentação do novo recurso. Você precisará colar essa chave no código de seu projeto em breve.

    Captura de tela do painel Visão geral de um recurso do Application Insights no portal do Azure com a chave de instrumentação realçada.

Adicionar o SDK do Application Insights para Java a seu projeto

Escolha o tipo de projeto.

Se o projeto já estiver configurado para usar o Maven para compilação, realize a mesclagem do código a seguir ao arquivo pom.xml. Em seguida, atualize as dependências do projeto para obter os binários baixados.

    <dependencies>
      <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <!-- or applicationinsights-web for manual web filter registration -->
        <!-- or applicationinsights-core for bare API -->
        <version>2.6.4</version>
      </dependency>
    </dependencies>

Perguntas frequentes

  • Qual é a relação entre os componentes -web-auto, -web e -core?

    • applicationinsights-web-auto fornece métricas que rastreiam as contagens de solicitações de servlet HTTP e tempos de resposta registrando automaticamente o filtro servlet do Application Insights em runtime.
    • applicationinsights-web também fornece métricas que rastreiam as contagens de solicitações de servlet HTTP e tempos de resposta. Mas é necessário o registro manual do filtro servlet do Application Insights no aplicativo.
    • applicationinsights-core fornecerá a API simples, por exemplo, se o aplicativo não for baseado em servlet.

  • Como fazer para atualizar o SDK para a versão mais recente?

    • A partir de novembro de 2020, é recomendável usar o Application Insights Java 3.x para monitorar os aplicativos Java. Para obter mais informações sobre como começar, confira Application Insights Java 3.x.

Adicionar um arquivo Application Insights.xml

Adicione o ApplicationInsights.xml à pasta de recursos no seu projeto; caso contrário, verifique se ele é adicionado ao caminho de classe de implantação do projeto. Copie o XML a seguir nele.

Cole a chave de instrumentação que você obteve no portal do Azure.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">

   <!-- The key from the portal: -->
   <InstrumentationKey>** Your instrumentation key **</InstrumentationKey>

   <!-- HTTP request component (not required for bare API) -->
   <TelemetryModules>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebSessionTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebUserTrackingTelemetryModule"/>
   </TelemetryModules>

   <!-- Events correlation (not required for bare API) -->
   <!-- These initializers add context data to each event -->
   <TelemetryInitializers>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationIdTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationNameTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebSessionTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserAgentTelemetryInitializer"/>
   </TelemetryInitializers>

</ApplicationInsights>

Opcionalmente, o arquivo de configuração pode residir em qualquer local que possa ser acessado pelo aplicativo. A propriedade do sistema -Dapplicationinsights.configurationDirectory especifica o diretório que contém o ApplicationInsights.xml. Por exemplo, um arquivo de configuração localizado em E:\myconfigs\appinsights\ApplicationInsights.xml é configurado com a propriedade -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights".

  • A chave de instrumentação é enviada junto com todos os itens de telemetria e orienta o Application Insights a exibi-los em seu recurso.
  • O componente de solicitação HTTP é opcional. Ele envia automaticamente a telemetria sobre solicitações e tempos de resposta para o portal.
  • A correlação de eventos é uma adição ao componente de solicitação HTTP. Ele atribui um identificador a cada solicitação recebida pelo servidor. Em seguida, ele adiciona esse identificador como uma propriedade a cada item de telemetria como a propriedade Operation.Id. Isso permite que você correlacione a telemetria associada a cada solicitação definindo um filtro em Pesquisa de diagnóstico.

Maneiras alternativas para definir a chave de instrumentação

O SDK do Application Insights procura a chave nesta ordem:

  • Propriedade do sistema: –DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  • Variável de ambiente: APPINSIGHTS_INSTRUMENTATIONKEY
  • Arquivo de configuração: ApplicationInsights.xml

Você também pode defini-lo no código:

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

Adicionar agente

Instale o agente Java para capturar chamadas de HTTP de saída, consultas JDBC, registro em log de aplicativo e melhor nomeação de operações.

Execute seu aplicativo.

Execute-o em modo de depuração no computador de desenvolvimento ou publique-o no servidor.

Exibir sua telemetria no Application Insights

Retorne ao recurso do Application Insights no portal do Azure.

Dados de solicitações HTTP são exibidos no painel de visão geral. Se não estiver lá, aguarde alguns segundos e selecione Atualizar.

Captura de tela que mostra os dados de exemplo de visão geral.

Saiba mais sobre métricas.

Clique em qualquer gráfico para ver métricas agregadas mais detalhadas.

Captura de tela que mostra um painel de falhas do Application Insights com gráficos.

Dados de instância

Clique em um tipo de solicitação específica para ver instâncias individuais.

Captura de tela que mostra o detalhamento em uma exibição de amostra específica.

Log Analytics: linguagem de consulta avançada

À medida que você acumular mais dados, poderá executar consultas para agregar os dados e localizar as instâncias individuais. O Log Analytics é uma ferramenta avançada para reconhecer o desempenho e o uso e para fins de diagnóstico.

Captura de tela que mostra um exemplo do Log Analytics no portal do Azure.

Instalar aplicativo no servidor

Agora, publique o aplicativo no servidor, permita que as pessoas utilizem o aplicativo e observe a telemetria mostrada no portal.

  • Verifique se o firewall permite que seu aplicativo envie telemetria para estas portas:

    • dc.services.visualstudio.com:443
    • f5.services.visualstudio.com:443

  • Se for necessário rotear o tráfego de saída por meio de um firewall, defina as propriedades do sistema http.proxyHost e http.proxyPort.

  • Nos servidores Windows, instale:

Configuração de VMs, Serviço de Aplicativo do Azure, Serviço de Kubernetes do Azure

A melhor e mais fácil abordagem para monitorar os aplicativos em execução nos provedores de recursos do Azure é usar o Application Insights Java 3.x.

Falhas de solicitação e exceções

Exceções não corrigidas e falhas de solicitação são coletadas automaticamente pelo filtro Web do Application Insights.

Para coletar dados sobre outras exceções, você pode inserir chamadas para trackException() no código.

Monitorar chamadas de método e dependências externas

Instale o agente Java para registrar os métodos internos especificados e as chamadas feitas por meio de JDBC, com os dados de tempo, e para nomeação automática de operações.

Rastreamento distribuído do W3C

O SDK do Java do Application Insights passou a dar suporte ao rastreamento distribuído do W3C.

A configuração do SDK de entrada é explicada com mais detalhes em Correlação de telemetria no Application Insights.

A configuração do SDK de saída é definida no arquivo AI-Agent.xml.

Contadores de desempenho

Selecione Investigar>Métricas para ver um intervalo de contadores de desempenho.

Captura de tela que mostra o painel Métricas de um recurso do Application Insights no portal do Azure com os bytes privados do processo selecionados.

Personalizar a coleta do contador de desempenho

Para desabilitar a coleta do conjunto padrão de contadores de desempenho, adicione o seguinte código no nó raiz do arquivo ApplicationInsights.xml:

    <PerformanceCounters>
       <UseBuiltIn>False</UseBuiltIn>
    </PerformanceCounters>

Coletar mais contadores de desempenho

É possível especificar mais contadores de desempenho para serem coletados.

Contadores JMX (expostos pela máquina virtual Java)
    <PerformanceCounters>
      <Jmx>
        <Add objectName="java.lang:type=ClassLoading" attribute="TotalLoadedClassCount" displayName="Loaded Class Count"/>
        <Add objectName="java.lang:type=Memory" attribute="HeapMemoryUsage.used" displayName="Heap Memory Usage-used" type="composite"/>
      </Jmx>
    </PerformanceCounters>
  • displayName: o nome exibido no portal do Application Insights.
  • objectName: o nome do objeto JMX.
  • attribute: o atributo do nome do objeto JMX a buscar.
  • type (opcional): o tipo do atributo do objeto JMX:
    • Padrão: um tipo simples como int ou long.
    • composite: os dados do contador para desempenho estão no formato de Attribute.Data.
    • tabular: os dados do contador de desempenho estão no formato de uma linha de tabela.
Contadores de desempenho do Windows

Cada contador de desempenho do Windows é membro de uma categoria (do mesmo modo que um campo é um membro de uma classe). As categorias podem ser globais ou ter instâncias numeradas ou nomeadas.

    <PerformanceCounters>
      <Windows>
        <Add displayName="Process User Time" categoryName="Process" counterName="%User Time" instanceName="__SELF__" />
        <Add displayName="Bytes Printed per Second" categoryName="Print Queue" counterName="Bytes Printed/sec" instanceName="Fax" />
      </Windows>
    </PerformanceCounters>
  • displayName: o nome exibido no portal do Application Insights.
  • categoryName: a categoria do contador de desempenho (objeto de desempenho) à qual esse contador de desempenho está associado.
  • counterName: o nome do contador de desempenho.
  • instanceName: o nome da instância da categoria do contador de desempenho ou uma cadeia de caracteres vazia (""), se a categoria contiver uma única instância. Se categoryName for Process e o contador de desempenho que você quer coletar pertencer ao processo da JVM atual no qual o aplicativo está sendo executado, especifique "__SELF__".

Contadores de desempenho do Unix

Instale o collectd com o plug-in do Application Insights para obter uma ampla variedade de dados do sistema e da rede.

Obter dados de usuário e de sessão

Agora, você está enviando a telemetria do servidor Web. Para obter a exibição em 360 graus completa do aplicativo, você poderá adicionar mais monitoramento:

Enviar sua própria telemetria

Agora que você instalou o SDK, poderá usar a API para enviar sua própria telemetria:

Testes de disponibilidade na Web

O Application Insights pode testar seu site em intervalos regulares para verificar ele está operante e respondendo bem.

Saiba mais sobre como configurar testes da Web de disponibilidade.

Solução de problemas

Confira o artigo de solução de problemas dedicado.

Testar a conectividade entre o host do aplicativo e o serviço de ingestão

Os SDKs e agentes do Application Insights enviam telemetria para serem ingeridos como chamadas REST para nossos pontos de extremidade de ingestão. Você pode testar a conectividade do servidor Web ou do computador host do aplicativo para os pontos de extremidade do serviço de ingestão usando clientes REST brutos do PowerShell ou comandos curl. Confira Solucionar problemas de telemetria de aplicativo ausente no Application Insights do Azure Monitor.

Explore os logs de rastreamento de Java no Application Insights

Se você estiver usando Logback ou Log4J (v 1.2 ou 2.0) para rastreamento, você pode enviar seus logs de rastreamento automaticamente para o Application Insights, no qual você pode explorá-los e pesquisar o conteúdo deles.

Dica

Será necessário definir a chave de instrumentação do Application Insights apenas uma vez para o aplicativo. Se você estiver usando uma estrutura como o Java Spring, talvez já tenha registrado a chave em outro local na configuração do aplicativo.

Usar o agente Java do Application Insights

Por padrão, o agente Java do Application Insights captura automaticamente o registro em log executado no nível WARN e superior.

Você poderá alterar o limite do registro em log capturado usando o arquivo AI-Agent.xml:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn>
         <Logging threshold="info"/>
      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Você poderá desabilitar a captura do registro em log do agente Java usando o arquivo AI-Agent.xml:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn>
         <Logging enabled="false"/>
      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Alternativas

Em vez de usar o agente Java, você poderá seguir estas instruções.

Instalar o SDK do Java

Siga as instruções para instalar o SDK do Application Insights para Java, se ainda não tiver feito isso.

Adicionar bibliotecas de log ao seu projeto

Escolha o modo apropriado para seu projeto.

Maven

Se o projeto já estiver configurado para usar o Maven para compilação, realize a mesclagem de um dos seguintes snippets de código no arquivo pom.xml. Em seguida, atualize as dependências do projeto para obter os binários baixados.

Logback


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-logback</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>

Log4J v2.0


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-log4j2</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>

Log4J v1.2


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-log4j1_2</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>
Gradle

Se o projeto já estiver configurado para usar o Gradle para compilação, adicione uma das seguintes linhas ao grupo dependencies no arquivo build.gradle. Em seguida, atualize as dependências do projeto para obter os binários baixados.

Logback


    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-logback', version: '2.0.+'

Log4J v2.0

    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j2', version: '2.0.+'

Log4J v1.2

    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j1_2', version: '2.0.+'

Siga as diretrizes para instalar manualmente o SDK do Java do Application Insights e baixar o jar. Na página do Maven Central, selecione o link do jar na seção de download para o appender apropriado. Adicione o jar do appender baixado ao projeto.

Agente Baixar Biblioteca
Logback Jar do appender de Logback applicationinsights-logging-logback
Log4J v2.0 Jar do appender de Log4J v2 applicationinsights-logging-log4j2
Log4J v1.2 Jar do appender de Log4J v1.2 applicationinsights-logging-log4j1_2

Adicionar o appender à sua estrutura de log

Para começar a obter os rastreamentos, mescle o snippet de código relevante ao arquivo de configuração Logback ou Log4J.

Logback


    <appender name="aiAppender" 
      class="com.microsoft.applicationinsights.logback.ApplicationInsightsAppender">
        <instrumentationKey>[APPLICATION_INSIGHTS_KEY]</instrumentationKey>
    </appender>
    <root level="trace">
      <appender-ref ref="aiAppender" />
    </root>

Log4J v2.0


    <Configuration packages="com.microsoft.applicationinsights.log4j.v2">
      <Appenders>
        <ApplicationInsightsAppender name="aiAppender" instrumentationKey="[APPLICATION_INSIGHTS_KEY]" />
      </Appenders>
      <Loggers>
        <Root level="trace">
          <AppenderRef ref="aiAppender"/>
        </Root>
      </Loggers>
    </Configuration>

Log4J v1.2


    <appender name="aiAppender" 
         class="com.microsoft.applicationinsights.log4j.v1_2.ApplicationInsightsAppender">
        <param name="instrumentationKey" value="[APPLICATION_INSIGHTS_KEY]" />
    </appender>
    <root>
      <priority value ="trace" />
      <appender-ref ref="aiAppender" />
    </root>

Os appenders do Application Insights podem ser referenciados por agentes configurados, e não necessariamente pelo agente raiz, conforme mostrado nos exemplos de código anteriores.

Explorar seus rastreamentos no portal do Application Insights

Agora que o projeto está configurado para enviar os rastreamentos ao Application Insights, você poderá exibir e pesquisar esses rastreamentos no portal do Application Insights, no painel Pesquisar.

As exceções enviadas por meio de agentes serão exibidas no portal como telemetria de Exceção.

Captura de tela que mostra o painel Pesquisar de um recurso do Application Insights no portal do Azure.

Monitorar dependências, exceções identificadas e tempos de execução de método em aplicativos Web Java

Se você instrumentou o aplicativo Web Java com o SDK do Application Insights, poderá usar o agente Java para obter insights mais detalhados sem alterações de código:

  • Dependências: dados sobre chamadas que o aplicativo faz para outros componentes, incluindo:

    • Chamadas de HTTP de saída: as chamadas feitas por meio de Apache HttpClient, OkHttp e java.net.HttpURLConnection são capturadas.
    • Chamadas do Redis: as chamadas feitas por meio do cliente Jedis são capturadas.
    • Consultas JDBC: para MySQL e PostgreSQL, se a chamada demorar mais de 10 segundos o agente informará o plano de consulta.

  • Log do aplicativo: capture e correlacione os logs do aplicativo com solicitações HTTP e outras telemetrias:

    • Log4j 1.2
    • Log4j2
    • Logback

  • Melhor nomeação de operações: utilizado para agregação de requisições no portal.

    • Spring: com base em @RequestMapping.
    • JAX-RS: com base em @Path.

Para usar o agente Java, instale-o no servidor. Seus aplicativos Web devem ser instrumentados com o SDK do Java do Application Insights.

Instalar o agente do Application Insights para Java

  1. No computador que executa o servidor Java, baixe o agente 2.x. Verifique se a versão do agente Java 2.x utilizada corresponde à versão do SDK Java do Application Insights 2.x que você usa.

  2. Edite o script de inicialização do servidor de aplicativos e adicione o seguinte argumento de JVM:

    -javaagent:<full path to the agent JAR file>

    Por exemplo, no Tomcat em um computador Linux:

    export JAVA_OPTS="$JAVA_OPTS -javaagent:<full path to agent JAR file>"

  3. Reinicie o servidor de aplicativos.

Configurar o agente

Crie um arquivo nomeado AI-Agent.xml e coloque-o na mesma pasta que o arquivo jar do agente.

Defina o conteúdo do arquivo XML. Edite o exemplo a seguir para incluir ou omitir os recursos desejados.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn enabled="true">

         <!-- capture logging via Log4j 1.2, Log4j2, and Logback, default is true -->
         <Logging enabled="true" />

         <!-- capture outgoing HTTP calls performed through Apache HttpClient, OkHttp,
              and java.net.HttpURLConnection, default is true -->
         <HTTP enabled="true" />

         <!-- capture JDBC queries, default is true -->
         <JDBC enabled="true" />

         <!-- capture Redis calls, default is true -->
         <Jedis enabled="true" />

         <!-- capture query plans for JDBC queries that exceed this value (MySQL, PostgreSQL),
              default is 10000 milliseconds -->
         <MaxStatementQueryLimitInMS>1000</MaxStatementQueryLimitInMS>

      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Mais configurações (Spring Boot)

java -javaagent:/path/to/agent.jar -jar path/to/TestApp.jar

Para o Serviço de Aplicativo do Azure, siga estas etapas:

  1. Selecione Configurações>Configurações do Aplicativo.

  2. Em Configurações do Aplicativo, adicione um novo par chave-valor:

    • Chave: JAVA_OPTS
    • Valor: -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.6.4.jar

    O agente deverá ser empacotado como um recurso no projeto para que permaneça no diretório D:/home/site/wwwroot/. Para confirmar se o agente está no diretório correto do Serviço de Aplicativo, vá para Ferramentas de Desenvolvimento>Ferramentas Avançadas>Console de Depuração e examine o conteúdo do diretório do site.

  3. Salve as configurações e reinicie seu aplicativo. Essas etapas se aplicam apenas a serviços de aplicativos em execução no Windows.

Observação

O AI-Agent.xml e o arquivo jar do agente devem estar na mesma pasta. Geralmente, eles são colocados juntos na pasta /resources do projeto.

Habilite o rastreamento distribuído do W3C

Adicione o seguinte snippet ao AI-Agent.xml:

<Instrumentation>
   <BuiltIn enabled="true">
      <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
   </BuiltIn>
</Instrumentation>

Observação

O modo de compatibilidade com versões anteriores é habilitado por padrão. O parâmetro enableW3CBackCompat é opcional e deverá ser utilizado somente quando você quiser desativá-lo.

Idealmente, esse seria o caso quando todos os serviços fossem atualizados para versões mais recentes dos SDKs com suporte para o protocolo W3C. É recomendável mudar para as versões mais recentes de SDKs com suporte a W3C o mais breve possível.

Verifique se ambas as configurações de entrada e saídas (agente) são exatamente as mesmas.

Exibir os dados

No recurso do Application Insights, a dependência remota agregada e os tempos de execução do método aparecem no bloco Desempenho.

Para procurar instâncias individuais de dependência, exceções e relatórios de método, abra Pesquisar.

Saiba mais sobre como diagnosticar problemas de dependência.

Perguntas ou problemas?

Use os seguintes recursos:

Filtrar a telemetria no aplicativo Web Java

Os filtros fornecem uma maneira de selecionar a telemetria que seu aplicativo Web Java envia ao Application Insights. Há alguns filtros prontos para uso que você poderá usar. Você também poderá gravar seus próprios filtros personalizados.

Os filtros prontos para uso incluem:

  • Nível de severidade de rastreamento.
  • URLs específicas, palavras-chave ou códigos de resposta.
  • Respostas rápidas. Em outras palavras, as solicitações que o aplicativo respondeu rapidamente.
  • Nomes de eventos específicos.

Observação

Os filtros distorcem as métricas do aplicativo. Por exemplo, você poderá decidir que, para diagnosticar as respostas lentas, definirá um filtro para descartar os tempos de resposta rápidos. Mas deverá estar ciente de que os tempos médios de resposta relatados pelo Application Insights serão mais lentos do que a velocidade real. Além disso, a contagem das solicitações será menor que a contagem real.

Se isso for um problema, use Amostragem.

Definir filtros

Em ApplicationInsights.xml, adicione uma seção TelemetryProcessors, como este exemplo:


    <ApplicationInsights>
      <TelemetryProcessors>

        <BuiltInProcessors>
           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="100"/>
                  <Add name="NotNeededResponseCodes" value="200-400"/>
           </Processor>

           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="100"/>
                  <Add name="NotNeededNames" value="home,index"/>
                  <Add name="NotNeededUrls" value=".jpg,.css"/>
           </Processor>

           <Processor type="TelemetryEventFilter">
                  <!-- Names of events we don't want to see -->
                  <Add name="NotNeededNames" value="Start,Stop,Pause"/>
           </Processor>

           <!-- Exclude telemetry from availability tests and bots -->
           <Processor type="SyntheticSourceFilter">
                <!-- Optional: specify which synthetic sources,
                     comma-separated
                     - default is all synthetics -->
                <Add name="NotNeededSources" value="Application Insights Availability Monitoring,BingPreview"
           </Processor>

        </BuiltInProcessors>

        <CustomProcessors>
          <Processor type="com.fabrikam.MyFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>

      </TelemetryProcessors>
    </ApplicationInsights>

Inspecione o conjunto completo de processadores internos.

Filtros internos

Esta seção aborda os filtros internos que estão disponíveis.

Filtro de telemetria da métrica


           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>
  • NotNeeded: lista de nomes de métricas personalizadas separados por vírgulas.

Filtro de telemetria da exibição de página


           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="500"/>
                  <Add name="NotNeededNames" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>
  • DurationThresholdInMS: a duração é o tempo necessário para carregar a página. Se esse parâmetro for definido, as páginas que carregarem mais rapidamente do que o tempo definido não serão relatadas.
  • NotNeededNames: lista de nomes de página separados por vírgula.
  • NotNeededUrls: lista de fragmentos de URL separados por vírgula. Por exemplo, "home" filtra todas as páginas que têm "início" na URL.

Filtro de telemetria da solicitação


           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="500"/>
                  <Add name="NotNeededResponseCodes" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>

Filtro de fonte sintética

Filtra toda a telemetria que possui valores na propriedade SyntheticSource. Solicitações de bots, spiders e testes de disponibilidade estão incluídos.

Filtra a telemetria de todas as solicitações sintéticas:


           <Processor type="SyntheticSourceFilter" />

Filtra a telemetria de fontes sintéticas específicas:


           <Processor type="SyntheticSourceFilter" >
                  <Add name="NotNeeded" value="source1,source2"/>
           </Processor>
  • NotNeeded: lista de nomes de fonte sintética separados por vírgula.

Filtro de eventos de telemetria

Filtra os eventos personalizados que foram registrados usando TrackEvent():


           <Processor type="TelemetryEventFilter" >
                  <Add name="NotNeededNames" value="event1, event2"/>
           </Processor>
  • NotNeededNames: lista de nomes de eventos separados por vírgula.

Filtro de telemetria de rastreamento

Filtra os rastreamentos de log registrados usando TrackTrace() ou um coletor de estrutura de registros:


           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

  • Os valores válidos de FromSeverityLevel são:

    • OFF: filtra todos os rastreamentos.
    • TRACE: sem filtragem. Igual a nível de TRACE.
    • INFO: filtra o nível de TRACE.
    • WARN: filtra TRACE e INFO.
    • ERROR: filtra WARN, INFO e TRACE.
    • CRITICAL: Filtra todos, menos CRITICAL.

Filtros personalizados

As seções a seguir mostram as etapas para criar seus próprios filtros personalizados.

Codificar seu filtro

No seu código, crie uma classe que implementa TelemetryProcessor:


    package com.fabrikam.MyFilter;
    import com.microsoft.applicationinsights.extensibility.TelemetryProcessor;
    import com.microsoft.applicationinsights.telemetry.Telemetry;

    public class SuccessFilter implements TelemetryProcessor {

        /* Any parameters that are required to support the filter.*/
        private final String successful;

        /* Initializers for the parameters, named "setParameterName" */
        public void setNotNeeded(String successful)
        {
            this.successful = successful;
        }

        /* This method is called for each item of telemetry to be sent.
           Return false to discard it.
           Return true to allow other processors to inspect it. */
        @Override
        public boolean process(Telemetry telemetry) {
            if (telemetry == null) { return true; }
            if (telemetry instanceof RequestTelemetry)
            {
                RequestTelemetry requestTelemetry = (RequestTelemetry)    telemetry;
                return request.getSuccess() == successful;
            }
            return true;
        }
    }

Invocar o filtro no arquivo de configuração

Agora, em ApplicationInsights.xml:



    <ApplicationInsights>
      <TelemetryProcessors>
        <CustomProcessors>
          <Processor type="com.fabrikam.SuccessFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>
      </TelemetryProcessors>
    </ApplicationInsights>

Invocar o filtro (Java Spring)

Para aplicativos baseados na estrutura do Spring, os processadores de telemetria personalizados devem ser registrados em sua classe de aplicativo principal como um bean. Eles conectarão automaticamente quando o aplicativo iniciar.

@Bean
public TelemetryProcessor successFilter() {
      return new SuccessFilter();
}

Crie seus parâmetros de filtro em application.properties. Em seguida, você usará a estrutura de configuração externalizada do Spring Boot para passar esses parâmetros para o filtro personalizado.

Solução de problemas

Esta seção oferece uma dica de solução de problemas.

Meu filtro não está funcionando.

Verifique se você forneceu valores de parâmetro válidos. Por exemplo, durações devem ser números inteiros. Valores inválidos farão com que o filtro seja ignorado. Se seu filtro personalizado lançar uma exceção de um construtor ou método set, ele será ignorado.

collectd: métricas de desempenho do Linux no Application Insights (preterido)

Para explorar as métricas de desempenho do sistema Linux no Application Insights, instale collectd com o plug-in do Application Insights. Essa solução de software livre reúne várias estatísticas de sistema e de rede.

Normalmente, você usará o collectd se já tiver instrumentado seu serviço Web Java com o Application Insights. Isso fornecerá mais dados para ajudar você a aprimorar o desempenho do aplicativo ou diagnosticar problemas.

Obter a chave de instrumentação

No portal do Azure, abra o recurso do Application Insights onde você quer que os dados sejam exibidos. Ou você poderá criar um novo recurso.

Faça uma cópia da chave de instrumentação que identifica o recurso.

Captura de tela que mostra o painel Visão geral de um recurso do Application Insights no portal do Azure com a chave de instrumentação realçada.

Instalar o plug-in e collectd

Em seus computadores com o servidor Linux:

  1. Instale collectd versão 5.4.0 ou posterior.
  2. Baixe o plug-in gravador do collectd do Application Insights. Observe o número de versão.
  3. Copie o jar do plug-in em /usr/share/collectd/java.
  4. Edite /etc/collectd/collectd.conf:

    • Verifique se o plug-in do Java está habilitado.

    • Atualize o JVMArg para o java.class.path incluir o seguinte jar. Atualize o número de versão para corresponder àquela que você baixou:

      • /usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar

    • Adicione este snippet usando a chave de instrumentação do recurso:

      
     LoadPlugin "com.microsoft.applicationinsights.collectd.ApplicationInsightsWriter"
     <Plugin ApplicationInsightsWriter>
        InstrumentationKey "Your key"
     </Plugin>

      Veja o exemplo de parte de um arquivo de configuração:

      
    ...
    # collectd plugins
    LoadPlugin cpu
    LoadPlugin disk
    LoadPlugin load
    ...

    # Enable Java Plugin
    LoadPlugin "java"

    # Configure Java Plugin
    <Plugin "java">
      JVMArg "-verbose:jni"
      JVMArg "-Djava.class.path=/usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar:/usr/share/collectd/java/collectd-api.jar"

      # Enabling Application Insights plugin
      LoadPlugin "com.microsoft.applicationinsights.collectd.ApplicationInsightsWriter"

      # Configuring Application Insights plugin
      <Plugin ApplicationInsightsWriter>
        InstrumentationKey "12345678-1234-1234-1234-123456781234"
      </Plugin>

      # Other plugin configurations ...
      ...
    </Plugin>
    ...

Configure outros plug-ins collectd que podem coletar vários dados de diferentes fontes.

Reinicie collectd de acordo com o manual.

Exibir os dados no Application Insights

No recurso do Application Insights, abra Métricas e adicione gráficos. Selecione as métricas que você quer ver na categoria Personalizada.

Por padrão, as métricas são agregadas em todos os computadores host dos quais as métricas foram coletadas. Para exibir as métricas por host, no painel Detalhes do gráfico, ative Agrupamento e, em seguida, escolha agrupar por CollectD-Host.

Excluir upload de estatísticas específicas

Por padrão, o plug-in do Application Insights envia todos os dados coletados por todos os plug-ins collectd read habilitados.

Para excluir os dados de plug-ins ou as fontes de dados específicos:

  • Edite o arquivo de configuração.

  • Em <Plugin ApplicationInsightsWriter>, adicione linhas de diretivas como as da tabela a seguir:

    Diretiva Efeito
    Exclude disk Exclua todos os dados coletados pelo plug-in disk.
    Exclude disk:read,write Exclua as fontes nomeadas read e write do plug-in disk.

Diretivas separadas por uma nova linha.

Problemas?

Esta seção oferece dicas de solução de problemas.

Não vejo dados no portal

Tente estas opções:

  • Abra Pesquisar para ver se os eventos brutos aparecem. Às vezes, eles levam mais tempo para aparecer no Metrics Explorer.
  • Talvez seja necessário definir as exceções de firewall para os dados de saída.
  • Habilite o rastreamento no plug-in do Application Insights. Adicione esta linha em <Plugin ApplicationInsightsWriter>:
    • SDKLogger true
  • Abra um terminal e inicie collectd no modo detalhado para ver os problemas que ele está relatando:
    • sudo collectd -f

Problema conhecido

O plug-in de gravação do Application Insights é incompatível com determinados plug-ins de leitura. Às vezes, alguns plug-ins enviam NaN, mas o plug-in do Application Insights espera um número de ponto flutuante.

  • Sintoma: o log collectd mostra os erros que incluem "AI: ... SyntaxError: token inesperado N."
  • Solução alternativa: exclua os dados coletados pelos plug-ins de gravação de problemas.

O monitoramento de aplicativos de micrômetros mede as métricas para código de aplicativo baseado em JVM e permite exportar os dados para seus sistemas de monitoramento favoritos. Esta seção ensina como usar o Micrometer com o Application Insights para aplicativos Spring Boot e não Spring Boot.

Usar o Spring Boot 1.5x

Adicione as seguintes dependências ao arquivo pom.xml ou build.gradle:

Siga estas etapas:

  1. Atualize o arquivo pom.xml do aplicativo Spring Boot e adicione as seguintes dependências nele:

    <dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>applicationinsights-spring-boot-starter</artifactId>
    <version>2.5.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-spring-legacy</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-azure-monitor</artifactId>
    <version>1.1.0</version>
</dependency>

  2. Atualize o arquivo application.properties ou YML com a chave de instrumentação do Application Insights usando a seguinte propriedade:

    azure.application-insights.instrumentation-key=<your-instrumentation-key-here>

  3. Compile o aplicativo e execute-o.

As etapas anteriores deverão ajudar você a começar a usar métricas pré-agregadas coletadas automaticamente para Azure Monitor.

Usar o Spring 2.x

Adicione as seguintes dependências ao arquivo pom.xml ou build.gradle:

Siga estas etapas:

  1. Atualize o arquivo pom.xml do aplicativo Spring Boot e adicione a seguinte dependência nele:

    <dependency> 
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure-spring-boot-metrics-starter</artifactId>
      <version>2.0.7</version>
</dependency>

  2. Atualize o arquivo application.properties ou YML com a chave de instrumentação do Application Insights usando a seguinte propriedade:

    azure.application-insights.instrumentation-key=<your-instrumentation-key-here>

  3. Compile o aplicativo e execute-o.

As etapas anteriores deverão ajudar você a começar a usar métricas pré-agregadas coletadas automaticamente para Azure Monitor. Para obter mais informações sobre como ajustar o iniciador do Spring Boot do Application Insights, consulte o leia-me no GitHub.

Métricas padrão:

  • Métricas configuradas automaticamente para Tomcat, JVM, Logback Metrics, Log4J Métricas, Métricas de Tempo de Ativação, Métricas do Processador e FileDescriptorMetrics.
  • Por exemplo, se o Hystrix do Netflix estiver presente no caminho da classe, também obteremos essas métricas.
  • As seguintes métricas poderão ficar disponíveis adicionando os respectivos beans:
    • CacheMetrics (CaffeineCache, EhCache2, GuavaCache, HazelcastCache e JCache)
    • DataBaseTableMetrics
    • HibernateMetrics
    • JettyMetrics
    • Métricas do OkHttp3
    • Métricas do Kafka

Desative a coleta automática de métricas:

  • Métricas JVM:
    • management.metrics.binders.jvm.enabled=false
  • Métricas Logback:
    • management.metrics.binders.logback.enabled=false
  • Métricas de tempo de atividade:
    • management.metrics.binders.uptime.enabled=false
  • Métricas de processador:
    • management.metrics.binders.processor.enabled=false
  • FileDescriptorMetrics:
    • management.metrics.binders.files.enabled=false
  • Métricas de Hystrix se a biblioteca estiver em classpath:
    • management.metrics.binders.hystrix.enabled=false
  • Métricas de AspectJ se a biblioteca estiver em classpath:
    • spring.aop.enabled=false

Observação

Especifique as propriedades anteriores no arquivo application.properties ou application.yml do aplicativo Spring Boot.

Use micrômetro com aplicativos da web que não sejam do Spring Boot

Adicione as seguintes dependências ao arquivo pom.xml ou build.gradle:

Siga estas etapas:

  1. Inclua as seguintes dependências no arquivo pom.xml ou build.gradle:

        <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-azure-monitor</artifactId>
        <version>1.1.0</version>
    </dependency>

    <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <version>2.5.0</version>
    </dependency>

  2. Se você ainda não tiver feito isso, adicione o arquivoApplicationInsights.xml na pasta de recursos. Para obter mais informações, confira Adicionar um arquivo ApplicationInsights.xml.

  3. Classe de servlet de amostra (emite uma métrica de timer):

        @WebServlet("/hello")
    public class TimedDemo extends HttpServlet {

      private static final long serialVersionUID = -4751096228274971485L;

      @Override
      @Timed(value = "hello.world")
      protected void doGet(HttpServletRequest request, HttpServletResponse response)
          throws ServletException, IOException {

        response.getWriter().println("Hello World!");
        MeterRegistry registry = (MeterRegistry) getServletContext().getAttribute("AzureMonitorMeterRegistry");

    //create new Timer metric
        Timer sampleTimer = registry.timer("timer");
        Stream<Integer> infiniteStream = Stream.iterate(0, i -> i+1);
        infiniteStream.limit(10).forEach(integer -> {
          try {
            Thread.sleep(1000);
            sampleTimer.record(integer, TimeUnit.MILLISECONDS);
          } catch (Exception e) {}
           });
      }
      @Override
      public void init() throws ServletException {
        System.out.println("Servlet " + this.getServletName() + " has started");
      }
      @Override
      public void destroy() {
        System.out.println("Servlet " + this.getServletName() + " has stopped");
      }

    }

  4. Classe de configuração de amostra:

         @WebListener
     public class MeterRegistryConfiguration implements ServletContextListener {

       @Override
       public void contextInitialized(ServletContextEvent servletContextEvent) {

     // Create AzureMonitorMeterRegistry
       private final AzureMonitorConfig config = new AzureMonitorConfig() {
         @Override
         public String get(String key) {
             return null;
         }
        @Override
           public Duration step() {
             return Duration.ofSeconds(60);}

         @Override
         public boolean enabled() {
             return false;
         }
     };

  MeterRegistry azureMeterRegistry = AzureMonitorMeterRegistry.builder(config);

         //set the config to be used elsewhere
         servletContextEvent.getServletContext().setAttribute("AzureMonitorMeterRegistry", azureMeterRegistry);

       }

       @Override
       public void contextDestroyed(ServletContextEvent servletContextEvent) {

       }
     }

Para saber mais sobre métricas, consulte a documentação do Micrometer.

Para ver outros exemplos de código sobre como criar diferentes tipos de métricas, confira o repositório GitHub oficial do Micrometer.

Associar mais coleta de métricas

As seções a seguir mostram como coletar mais métricas.

SpringBoot/Spring

Crie um bean da respectiva categoria de métrica. Por exemplo, se você precisar de métricas do Cache do Guava:

    @Bean
    GuavaCacheMetrics guavaCacheMetrics() {
        Return new GuavaCacheMetrics();
    }

Várias métricas não são habilitadas por padrão, mas poderão ser associadas da maneira anterior. Para obter uma lista completa, consulte o repositório GitHub do Micrometer.

Aplicativos não-Spring

Adicione o seguinte código de ligação ao arquivo de configuração:

    New GuavaCacheMetrics().bind(registry);

Próximas etapas