Início rápido: introdução ao Application Insights em um projeto Web JavaQuickstart: Get started with Application Insights in a Java web project

Neste guia de início rápido, você usa Application Insights para instrumentar automaticamente a solicitação, controlar dependências e coletar contadores de desempenho, diagnosticar problemas de desempenho e exceções e escrever código para controlar o que os usuários fazem com seu aplicativo.In this quickstart, you use Application Insights to automatically instrument request, track dependencies, and collect performance counters, diagnose performance issues and exceptions, and write code to track what users do with your app.

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.Application Insights is an extensible analytics service for web developers that helps you understand the performance and usage of your live application. O Application Insights oferece suporte a aplicativos Java em execução no Windows, no Unix ou no Linux.Application Insights supports Java apps running on Linux, Unix, or Windows.

Pré-requisitosPrerequisites

Obter uma chave de instrumentação do Application InsightsGet an Application Insights instrumentation key

  1. Entre no portal do Azure.Sign in to the Azure portal.

  2. No portal do Azure, crie um recurso Application Insights.In the Azure portal, create an Application Insights resource. Defina o tipo de aplicativo para aplicativo Web Java.Set the application type to Java web application.

  3. Localize a chave de instrumentação do novo recurso.Find the instrumentation key of the new resource. Você precisará colar essa chave no código de seu projeto em breve.You'll need to paste this key into your code project shortly.

    Na visão geral do novo recurso, clique em Propriedades e copie a chave de instrumentação

Adicionar o SDK do Application Insights para Java a seu projetoAdd the Application Insights SDK for Java to your project

Escolha o tipo de projeto.Choose your project type.

Se o seu projeto já estiver configurado para usar o Maven para compilação, mescle o código a seguir ao arquivo de pom.xml .If your project is already set up to use Maven for build, merge the following code to your pom.xml file.

Em seguida, atualize as dependências do projeto para obter os binários baixados.Then, refresh the project dependencies to get the binaries downloaded.

    <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.5.0</version>
      </dependency>
    </dependencies>

PerguntasQuestions

  • Qual é a relação entre os -web-auto -web componentes e -core ?What's the relationship between the -web-auto, -web and -core components?

    • applicationinsights-web-autofornece métricas que rastreiam contagens de solicitação e tempos de resposta do servlet HTTP, registrando automaticamente o filtro de Application Insights servlet em tempo de execução.applicationinsights-web-auto gives you metrics that track HTTP servlet request counts and response times, by automatically registering the Application Insights servlet filter at runtime.
    • applicationinsights-webtambém fornece métricas que controlam as contagens de solicitação e os tempos de resposta do servlet HTTP, mas exigem o registro manual do filtro de Application Insights servlet em seu aplicativo.applicationinsights-web also gives you metrics that track HTTP servlet request counts and response times, but requires manual registration of the Application Insights servlet filter in your application.
    • applicationinsights-coreoferece apenas a API Bare, por exemplo, se seu aplicativo não for baseado em servlet.applicationinsights-core gives you just the bare API, for example, if your application isn't servlet-based.
  • Como fazer para atualizar o SDK para a versão mais recente?How should I update the SDK to the latest version?

    • Se você estiver usando gradle ou Maven...If you're using Gradle or Maven...
      • Atualize o arquivo de compilação para especificar a versão mais recente.Update your build file to specify the latest version.
    • Se você estiver gerenciando dependências manualmente...If you're manually managing dependencies...

Adicionar um arquivo de ApplicationInsights.xmlAdd an ApplicationInsights.xml file

Adicione ApplicationInsights.xml à pasta de recursos em seu projeto ou verifique se ele foi adicionado ao caminho de classe de implantação do seu projeto.Add ApplicationInsights.xml to the resources folder in your project, or make sure it's added to your project's deployment class path. Copie o XML a seguir nele.Copy the following XML into it.

Substitua a chave de instrumentação por aquela que você obteve da portal do Azure.Replace the instrumentation key with the one that you got from the Azure portal.

<?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 estar em qualquer local acessível ao seu aplicativo.Optionally, the configuration file can be in any location accessible to your application. A propriedade System -Dapplicationinsights.configurationDirectory especifica o diretório que contém ApplicationInsights.xml.The system property -Dapplicationinsights.configurationDirectory specifies the directory that contains ApplicationInsights.xml. Por exemplo, um arquivo de configuração localizado em E:\myconfigs\appinsights\ApplicationInsights.xml seria configurado com a propriedade -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights".For example, a configuration file located at E:\myconfigs\appinsights\ApplicationInsights.xml would be configured with the property -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.The instrumentation key is sent along with every item of telemetry and tells Application Insights to display it in your resource.
  • O componente de solicitação HTTP é opcional.The HTTP Request component is optional. Ele envia automaticamente a telemetria sobre solicitações e tempos de resposta para o portal.It automatically sends telemetry about requests and response times to the portal.
  • A correlação de eventos é uma adição ao componente de solicitação HTTP.Event correlation is an addition to the HTTP request component. Ele atribui um identificador a cada solicitação recebida pelo servidor.It assigns an identifier to each request received by the server. Em seguida, ele adiciona esse identificador como uma propriedade a cada item de telemetria como a propriedade ' Operation.Id '.It then adds this identifier as a property to every item of telemetry as the property 'Operation.Id'. Ele permite que você correlacione a telemetria associada com cada solicitação, definindo um filtro na pesquisa de diagnóstico.It allows you to correlate the telemetry associated with each request by setting a filter in diagnostic search.

Maneiras alternativas para definir a chave de instrumentaçãoAlternative ways to set the instrumentation key

O SDK do Application Insights procura a chave nesta ordem:Application Insights SDK looks for the key in this order:

  1. Propriedade do sistema:-DAPPINSIGHTS_INSTRUMENTATIONKEY = your_ikeySystem property: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. Variável de ambiente: APPINSIGHTS_INSTRUMENTATIONKEYEnvironment variable: APPINSIGHTS_INSTRUMENTATIONKEY
  3. Arquivo de configuração: ApplicationInsights.xmlConfiguration file: ApplicationInsights.xml

Você também pode defini-lo no código:You can also set it in code:

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

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

Adicionar agenteAdd agent

Instale o agente Java para capturar chamadas http de saída, consultas JDBC, log de aplicativo e melhor nomenclatura de operação.Install the Java Agent to capture outgoing HTTP calls, JDBC queries, application logging, and better operation naming.

Execute seu aplicativo.Run your application

Execute-o no modo de depuração no computador de desenvolvimento ou publique em seu servidor.Either run it in debug mode on your development machine, or publish to your server.

Exibir sua telemetria no Application InsightsView your telemetry in Application Insights

Retorne para seu recurso do Application Insights no Portal do Microsoft Azure.Return to your Application Insights resource in Microsoft Azure portal.

Dados de solicitações HTTP são exibidos na folha de visão geral.HTTP requests data appears on the overview blade. (Se não estiverem lá, aguarde alguns segundos e, em seguida, clique em Atualizar.)(If it isn't there, wait a few seconds and then click Refresh.)

Captura de tela de visão geral de dados de exemplo

Saiba mais sobre métricas.Learn more about metrics.

Clique em qualquer gráfico para ver métricas agregadas mais detalhadas.Click through any chart to see more detailed aggregated metrics.

Painel de falhas Application Insights com gráficos

Dados de instânciaInstance data

Clique em um tipo de solicitação específica para ver instâncias individuais.Click through a specific request type to see individual instances.

Analisar uma exibição de exemplo específica

Análise: linguagem de consulta poderosaAnalytics: Powerful query language

À medida que acumular mais dados, você poderá executar consultas para agregar dados e localizar instâncias individuais.As you accumulate more data, you can run queries both to aggregate data and to find individual instances. Análise é uma ferramenta poderosa para entender o desempenho e o uso e para fins de diagnóstico.Analytics is a powerful tool for both for understanding performance and usage, and for diagnostic purposes.

Exemplo de Análise

Instalar aplicativo no servidorInstall your app on the server

Agora, publique seu aplicativo no servidor, permita que as pessoas o usem e observe a telemetria mostrada no portal.Now publish your app to the server, let people use it, and watch the telemetry show up on the portal.

  • Verifique se o firewall permite que seu aplicativo envie telemetria para estas portas:Make sure your firewall allows your application to send telemetry to these ports:

    • dc.services.visualstudio.com:443dc.services.visualstudio.com:443
    • f5.services.visualstudio.com:443f5.services.visualstudio.com:443
  • Se o tráfego de saída precisar passar por um firewall, defina as propriedades do sistema http.proxyHost e http.proxyPort.If outgoing traffic must be routed through a firewall, define system properties http.proxyHost and http.proxyPort.

  • Nos servidores Windows, instale:On Windows servers, install:

Configuração do serviço de Azure App (Spring boot)Azure App Service config (Spring Boot)

Os aplicativos Spring boot em execução no Windows exigem configuração adicional para serem executados em serviços Azure Apps.Spring Boot apps running on Windows require additional configuration to run on Azure App Services. Modifique web.config e adicione a seguinte configuração:Modify web.config and add the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
        </handlers>
        <httpPlatform processPath="%JAVA_HOME%\bin\java.exe" arguments="-Djava.net.preferIPv4Stack=true -Dserver.port=%HTTP_PLATFORM_PORT% -jar &quot;%HOME%\site\wwwroot\AzureWebAppExample-0.0.1-SNAPSHOT.jar&quot;">
        </httpPlatform>
    </system.webServer>
</configuration>

Falhas de solicitação e exceçõesExceptions and request failures

As exceções não tratadas e as falhas de solicitação são coletadas automaticamente pelo filtro da Web Application Insights.Unhandled exceptions and request failures are automatically collected by the Application Insights web filter.

Para coletar dados sobre outras exceções, você pode inserir chamadas para trackexception () em seu código.To collect data on other exceptions, you can insert calls to trackException() in your code.

Monitorar chamadas de método e dependências externasMonitor method calls and external dependencies

Instale o Agente Java para registrar métodos internos especificados e chamadas feitas por meio de JDBC, com dados de tempo.Install the Java Agent to log specified internal methods and calls made through JDBC, with timing data.

E para a nomenclatura de operação automática.And for automatic operation naming.

Rastreamento distribuído do W3CW3C distributed tracing

O SDK do Java do Application Insights passou a dar suporte ao rastreamento distribuído do W3C.The Application Insights Java SDK now supports W3C distributed tracing.

A configuração do SDK de entrada será mais bem explicada em nosso artigo sobre correlação.The incoming SDK configuration is explained further in our article on correlation.

A configuração do SDK de saída é definida no arquivo AI-Agent.xml.Outgoing SDK configuration is defined in the AI-Agent.xml file.

Contadores de desempenhoPerformance counters

Abra investigar, métricas, para ver um intervalo de contadores de desempenho.Open Investigate, Metrics, to see a range of performance counters.

Captura de tela do painel de métricas com bytes particulares de processo selecionados

Personalizar a coleta do contador de desempenhoCustomize performance counter collection

Para desabilitar a coleta do conjunto padrão de contadores de desempenho, adicione o seguinte código sob o nó raiz do arquivo de ApplicationInsights.xml :To disable collection of the standard set of performance counters, add the following code under the root node of the ApplicationInsights.xml file:

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

Coletar contadores de desempenho adicionaisCollect additional performance counters

Você pode especificar contadores de desempenho adicionais a serem coletados.You can specify additional performance counters to be collected.

Contadores JMX (expostos pela Máquina Virtual Java)JMX counters (exposed by the Java Virtual Machine)

    <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.displayName – The name displayed in the Application Insights portal.
  • objectName – o nome do objeto JMX.objectName – The JMX object name.
  • attribute – o atributo do nome do objeto JMX a buscarattribute – The attribute of the JMX object name to fetch
  • type(opcional)-o tipo de atributo do objeto JMX:type (optional) - The type of JMX object's attribute:
    • Padrão: um tipo simples como “int” ou “long”.Default: a simple type such as int or long.
    • composite: os dados do contador de desempenho estão no formato “Attribute.Data”composite: the perf counter data is in the format of 'Attribute.Data'
    • tabular: os dados do contador de desempenho estão no formato de uma linha de tabelatabular: the perf counter data is in the format of a table row

Contadores de desempenho do WindowsWindows performance counters

Cada contador de desempenho do Windows é membro de uma categoria (do mesmo modo que um campo é um membro de uma classe).Each Windows performance counter is a member of a category (in the same way that a field is a member of a class). Categorias podem ser globais, ou podem ter instâncias numeradas ou nomeadas.Categories can either be global, or can have numbered or named instances.

    <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.displayName – The name displayed in the Application Insights portal.
  • categoryName – a categoria de contador de desempenho (objeto de desempenho) a qual este contador de desempenho está associadocategoryName – The performance counter category (performance object) with which this performance counter is associated.
  • counterName – o nome do contador de desempenhocounterName – The name of the performance counter.
  • instanceName – o nome da instância da categoria do contador de desempenho ou uma cadeia de caracteres vazia (""), se a categoria contém uma única instância.instanceName – The name of the performance counter category instance, or an empty string (""), if the category contains a single instance. Se categoryName é o processo, e o contador de desempenho que você gostaria de coletar faz parte do processo atual da JVM em que seu aplicativo está sendo executado, especifique "__SELF__".If the categoryName is Process, and the performance counter you'd like to collect is from the current JVM process on which your app is running, specify "__SELF__".

Contadores de desempenho do UnixUnix performance counters

Obter dados de usuário e de sessãoGet user and session data

OK, você está enviando a telemetria do seu servidor Web.OK, you're sending telemetry from your web server. Agora, para ver o panorama completo do seu aplicativo, você pode adicionar um monitoramento mais:Now to get the full 360-degree view of your application, you can add more monitoring:

Enviar sua própria telemetriaSend your own telemetry

Agora que você instalou o SDK, você pode usar a API para enviar sua próprias telemetrias.Now that you've installed the SDK, you can use the API to send your own telemetry.

Testes de disponibilidade na WebAvailability web tests

O Application Insights pode testar seu site em intervalos regulares para verificar ele está operante e respondendo bem.Application Insights can test your website at regular intervals to check that it's up and responding well.

Saiba mais sobre como configurar testes da Web de disponibilidade.Learn more about how to set up availability web tests.

Perguntas?Questions? Problemas?Problems?

Solucionar problemas de JavaTroubleshooting Java

Próximas etapasNext steps