Schnellstart: Erste Schritte mit Application Insights in einem Java-WebprojektQuickstart: Get started with Application Insights in a Java web project

Wichtig

Der empfohlene Ansatz zur Überwachung von Java-Anwendungen ist die automatische Instrumentierung ohne Änderung des Codes.The recommended approach to monitor Java applications is to use the auto-instrumentation without changing the code. Befolgen Sie die Leitlinien für den Application Insights Java 3.0-Agent.Please follow the guidelines for Application Insights Java 3.0 agent.

In dieser Schnellstartanleitung verwenden Sie das Application Insights SDK, um Anforderungen zu instrumentieren, Abhängigkeiten zu verfolgen und Leistungsindikatoren zu sammeln, Leistungsprobleme und Ausnahmen zu diagnostizieren und Code zu schreiben, um die Aktivitäten der Benutzer Ihrer App zu verfolgen.In this quickstart, you use Application Insights SDK to 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 ist ein erweiterbarer Analysedienst für Webentwickler, der Ihnen dabei hilft, die Leistung und die Verwendung der Liveanwendung zu verstehen.Application Insights is an extensible analytics service for web developers that helps you understand the performance and usage of your live application. Application Insights unterstützt Java-Apps, die unter Linux, Unix oder Windows ausgeführt werden.Application Insights supports Java apps running on Linux, Unix, or Windows.

VoraussetzungenPrerequisites

Abrufen eines Application Insights-InstrumentationsschlüsselsGet an Application Insights instrumentation key

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Erstellen Sie im Azure-Portal eine Application Insights-Ressource.In the Azure portal, create an Application Insights resource. Legen Sie den Anwendungstyp auf "Java-Webanwendung" fest.Set the application type to Java web application.

  3. Suchen Sie den Instrumentationsschlüssel der neuen Ressource.Find the instrumentation key of the new resource. Dieser Schlüssel muss in Kürze in das Codeprojekt eingefügt werden.You'll need to paste this key into your code project shortly.

    Klicken Sie in der Übersicht über neue Ressourcen auf "Eigenschaften", und kopieren Sie den Instrumentationsschlüssel

Hinzufügen des Application Insights SDK für Java zu Ihrem ProjektAdd the Application Insights SDK for Java to your project

Wählen Sie Ihren Projekttyp aus.Choose your project type.

Wenn Ihr Projekt bereits für die Verwendung von Maven für den Buildprozess eingerichtet ist, fügen Sie Ihrer Datei pom.xml den folgenden Code hinzu.If your project is already set up to use Maven for build, merge the following code to your pom.xml file.

Aktualisieren Sie dann die Projektabhängigkeiten, damit die Binärdateien heruntergeladen werden.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>

FragenQuestions

  • Welche Beziehung besteht zwischen den Komponenten -web-auto, -web und -core?What's the relationship between the -web-auto, -web and -core components?

    • applicationinsights-web-auto bietet Ihnen Metriken, die die Anzahl der HTTP-Servletanforderungen und die Antwortzeiten nachverfolgen, indem sie den Application Insights-Servletfilter zur Runtime automatisch registrieren.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-web bietet Ihnen auch Metriken, die die Anzahl der HTTP-Servletanforderungen und die Antwortzeiten nachverfolgen, erfordert jedoch manuelle Registrierung der Application Insights-Servletfilter in Ihrer Anwendung.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-core bietet Ihnen lediglich die reine API, beispielsweise wenn Ihre Anwendung nicht auf Servlets basiert.applicationinsights-core gives you just the bare API, for example, if your application isn't servlet-based.
  • Wie aktualisiere ich das SDK auf die neueste Version?How should I update the SDK to the latest version?

    • Wenn Sie Gradle oder Maven verwenden...If you're using Gradle or Maven...
      • Aktualisieren Sie Ihre Builddatei, um die neueste Version anzugeben.Update your build file to specify the latest version.
    • Wenn Sie Abhängigkeiten manuell verwalten...If you're manually managing dependencies...

Hinzufügen einer Datei vom Typ ApplicationInsights.xmlAdd an ApplicationInsights.xml file

Fügen Sie dem Ressourcenordner in Ihrem Projekt die Datei ApplicationInsights.xml hinzu, oder stellen Sie sicher, dass sie dem Bereitstellungsklassenpfad Ihres Projekts hinzugefügt wird.Add ApplicationInsights.xml to the resources folder in your project, or make sure it's added to your project's deployment class path. Kopieren Sie den folgenden XML-Code in die Datei.Copy the following XML into it.

Ersetzen Sie den Instrumentationsschlüssel durch den, den Sie aus dem Azure-Portal abgerufen haben.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>

Die Konfigurationsdatei kann sich optional an einem beliebigen Speicherort befinden, auf den Ihre Anwendung Zugriff hat.Optionally, the configuration file can be in any location accessible to your application. Die Systemeigenschaft -Dapplicationinsights.configurationDirectory gibt das Verzeichnis an, in dem sich die Datei ApplicationInsights.xml befindet.The system property -Dapplicationinsights.configurationDirectory specifies the directory that contains ApplicationInsights.xml. Eine Konfigurationsdatei unter E:\myconfigs\appinsights\ApplicationInsights.xml wird beispielsweise mit der Eigenschaft -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights" konfiguriert.For example, a configuration file located at E:\myconfigs\appinsights\ApplicationInsights.xml would be configured with the property -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights".

  • Der Instrumentationsschlüssel wird zusammen mit jedem Telemetrieelement übermittelt und weist Application Insights an, ihn in Ihrer Ressource anzuzeigen.The instrumentation key is sent along with every item of telemetry and tells Application Insights to display it in your resource.
  • Die Komponente "HTTP-Anforderung" ist optional.The HTTP Request component is optional. Sie sendet automatisch Telemetriedaten zu Anforderungen und Antwortzeiten zum Portal.It automatically sends telemetry about requests and response times to the portal.
  • Die Ereigniskorrelation ist eine Ergänzung der HTTP-Anforderungskomponente.Event correlation is an addition to the HTTP request component. Sie weist jeder vom Server empfangenen Anforderung einen Bezeichner zu.It assigns an identifier to each request received by the server. Anschließend weist sie diesen Bezeichner jedem Telemetrieelement als die Eigenschaft „Operation.Id“ zu.It then adds this identifier as a property to every item of telemetry as the property 'Operation.Id'. Diese Eigenschaft ermöglicht das Korrelieren der jeder Anforderung zugeordneten Telemetriedaten, indem in Diagnosesucheein Filter festgelegt wird.It allows you to correlate the telemetry associated with each request by setting a filter in diagnostic search.

Alternative Methoden zum Festlegen des InstrumentationsschlüsselsAlternative ways to set the instrumentation key

Das Application Insights SDK sucht in dieser Reihenfolge nach dem Schlüssel:Application Insights SDK looks for the key in this order:

  1. Systemeigenschaft: -DAPPINSIGHTS_INSTRUMENTATIONKEY=Ihr_InstrumentierungsschlüsselSystem property: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. Umgebungsvariable: APPINSIGHTS_INSTRUMENTATIONKEYEnvironment variable: APPINSIGHTS_INSTRUMENTATIONKEY
  3. Konfigurationsdatei: ApplicationInsights.xmlConfiguration file: ApplicationInsights.xml

Sie können dies auch per Code festlegen:You can also set it in code:

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

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

Hinzufügen des AgentAdd agent

Installieren Sie den Java-Agent zum Erfassen ausgehender HTTP-Aufrufe, für JDBC-Abfragen, Anwendungsprotokollierung und zur besseren Vorgangsbenennung.Install the Java Agent to capture outgoing HTTP calls, JDBC queries, application logging, and better operation naming.

Ausführen der AnwendungRun your application

Führen Sie sie entweder im Debugmodus auf dem Entwicklungscomputer aus, oder veröffentlichen Sie sie auf Ihrem Server.Either run it in debug mode on your development machine, or publish to your server.

Anzeigen Ihrer Telemetriedaten in Application InsightsView your telemetry in Application Insights

Kehren Sie zur Application Insights-Ressource im Microsoft Azure-Portalzurück.Return to your Application Insights resource in Microsoft Azure portal.

HTTP-Anforderungsdaten werden auf dem Übersichtsblatt angezeigt.HTTP requests data appears on the overview blade. (Wenn sie nicht vorhanden sind, warten Sie einige Sekunden, und klicken Sie dann auf "Aktualisieren".)(If it isn't there, wait a few seconds and then click Refresh.)

Screenshot der Übersicht über die Beispieldaten

Weitere Informationen zu Metriken.Learn more about metrics.

Klicken Sie sich durch ein beliebiges Diagramm, um ausführliche aggregierte Metriken anzuzeigen.Click through any chart to see more detailed aggregated metrics.

Bereich für Application Insights-Fehler mit Diagrammen

InstanzdatenInstance data

Klicken Sie sich durch einen bestimmten Anforderungstyp, um einzelne Instanzen anzuzeigen.Click through a specific request type to see individual instances.

Detailinformationen in einer spezifischen Beispielansicht

Analytics: Leistungsfähige AbfragespracheAnalytics: Powerful query language

Wenn sich mehr Daten ansammeln, können Sie Abfragen sowohl zum Aggregieren von Daten als auch zum Ermitteln einzelner Instanzen ausführen.As you accumulate more data, you can run queries both to aggregate data and to find individual instances. Analytics ist ein leistungsfähiges Tool zum Nachvollziehen der Leistung und Nutzung sowie für Diagnosezwecke.Analytics is a powerful tool for both for understanding performance and usage, and for diagnostic purposes.

Analytics-Beispiel

Installieren der App auf dem ServerInstall your app on the server

Jetzt veröffentlichen Sie Ihre App auf dem Server, erlauben deren Benutzung und sehen sich an, wie die Telemetrie im Portal angezeigt wird.Now publish your app to the server, let people use it, and watch the telemetry show up on the portal.

  • Stellen Sie sicher, dass die Firewall der Anwendung das Senden von Telemetrie an die folgenden Ports erlaubt: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
  • Wenn ausgehender Datenverkehr über eine Firewall geleitet werden muss, legen Sie Systemeigenschaften wie http.proxyHost und http.proxyPort fest.If outgoing traffic must be routed through a firewall, define system properties http.proxyHost and http.proxyPort.

  • Installieren Sie auf Windows-Servern:On Windows servers, install:

Azure App Service, AKS, VM-KonfigurationAzure App Service, AKS, VMs config

Der beste und einfachste Ansatz zur Überwachung Ihrer Anwendungen, die bei einem der Azure-Ressourcenanbieter laufen, ist die Verwendung der automatischen Instrumentierung von Application Insights über den Java 3.0-Agent.The best and easiest approach to monitor your applications running on any of Azure resource providers is to use Application Insights auto-instrumentation via Java 3.0 agent.

Ausnahmen und AnforderungsfehlerExceptions and request failures

Unbehandelte Ausnahmen und Anforderungsfehler werden automatisch vom Application Insights-Webfilter erfasst.Unhandled exceptions and request failures are automatically collected by the Application Insights web filter.

Zum Sammeln von Daten zu anderen Ausnahmen können Sie Aufrufe von trackException() in Ihren Code einfügen.To collect data on other exceptions, you can insert calls to trackException() in your code.

Überwachen von Methodenaufrufen und externen AbhängigkeitenMonitor method calls and external dependencies

Installieren Sie den Java-Agent , um die angegebenen internen Methoden und Aufrufe über JDBC mit Zeitdaten zu protokollieren.Install the Java Agent to log specified internal methods and calls made through JDBC, with timing data.

Außerdem für die automatische Vorgangsbenennung.And for automatic operation naming.

W3C – verteilte AblaufverfolgungW3C distributed tracing

Das Application Insights Java SDK unterstützt jetzt die verteilte Ablaufverfolgung W3C.The Application Insights Java SDK now supports W3C distributed tracing.

Die SDK-Eingangskonfiguration wird ausführlicher in unserem Artikel zu Korrelation behandelt.The incoming SDK configuration is explained further in our article on correlation.

Die SDK-Ausgangskonfiguration wird in der Datei AI-Agent.xml definiert.Outgoing SDK configuration is defined in the AI-Agent.xml file.

LeistungsindikatorenPerformance counters

Unter Untersuchen > Metriken finden Sie eine Reihe von Leistungsindikatoren.Open Investigate, Metrics, to see a range of performance counters.

Screenshot des Bereichs für Metriken mit ausgewählter Option für die Verarbeitung privater Bytes

Anpassen der Erfassung von LeistungsindikatorenCustomize performance counter collection

Um die Erfassung der Standardgruppe von Leistungsindikatoren zu deaktivieren, fügen Sie unter dem Stammknoten der Datei ApplicationInsights.xml den folgenden Code hinzu: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>

Erfassen weiterer LeistungsindikatorenCollect additional performance counters

Sie können weitere Leistungsindikatoren angeben, die erfasst werden sollen.You can specify additional performance counters to be collected.

JMX-Leistungsindikatoren (von der Java Virtual Machine bereitgestellt)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 – Der im Application Insights-Portal angezeigte Name.displayName – The name displayed in the Application Insights portal.
  • objectName – Der JMX-Objektname.objectName – The JMX object name.
  • attribute – Das Attribut des abzurufenden JMX-Objektnamensattribute – The attribute of the JMX object name to fetch
  • type (optional) – Der Typ des Attributs des JMX-Objekts:type (optional) - The type of JMX object's attribute:
    • Standard: ein einfacher Typ wie "int" oder "long".Default: a simple type such as int or long.
    • composite: Die Leistungsindikatordaten haben das Format 'Attribut.Daten'.composite: the perf counter data is in the format of 'Attribute.Data'
    • tabular: Die Leistungsindikatordaten haben das Format einer Tabellenzeile.tabular: the perf counter data is in the format of a table row

Windows-LeistungsindikatorenWindows performance counters

Jeder Windows-Leistungsindikator gehört zu einer Kategorie (genauso wie ein Feld zu einer Klasse gehört).Each Windows performance counter is a member of a category (in the same way that a field is a member of a class). Kategorien können entweder global sein oder nummerierte oder benannte Instanzen haben.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 – Der im Application Insights-Portal angezeigte NamedisplayName – The name displayed in the Application Insights portal.
  • categoryName – Die Leistungsindikatorkategorie (Leistungsobjekt), der dieser Leistungsindikator zugeordnet istcategoryName – The performance counter category (performance object) with which this performance counter is associated.
  • counterName – Der Name des LeistungsindikatorscounterName – The name of the performance counter.
  • instanceName – Der Name der Instanz der Leistungsindikatorkategorie oder eine leere Zeichenfolge (""), wenn die Kategorie eine einzelne Instanz enthält.instanceName – The name of the performance counter category instance, or an empty string (""), if the category contains a single instance. Wenn "categoryName" auf "Process" festgelegt ist und der Leistungsindikator, den Sie erfassen möchten, aus dem aktuellen JVM-Prozess stammt, in dem Ihre Anwendung ausgeführt wird, geben Sie "__SELF__"an.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__".

Unix-LeistungsindikatorenUnix performance counters

Abrufen von Benutzer- und SitzungsdatenGet user and session data

Sie senden also Telemetriedaten vom Webserver.OK, you're sending telemetry from your web server. Um jetzt eine Rundum-Ansicht Ihrer Anwendung zu erhalten, können Sie weitere Überwachungsfunktionen hinzufügen:Now to get the full 360-degree view of your application, you can add more monitoring:

Senden eigener TelemetriedatenSend your own telemetry

Nachdem Sie das SDK installiert haben, können Sie die API verwenden, um eigene Telemetriedaten senden.Now that you've installed the SDK, you can use the API to send your own telemetry.

VerfügbarkeitswebtestsAvailability web tests

Application Insights kann Ihre Website in regelmäßigen Abständen testen, um zu überprüfen, ob sie betriebsbereit ist und gut reagiert.Application Insights can test your website at regular intervals to check that it's up and responding well.

Erfahren Sie mehr über das Einrichten von Verfügbarkeitswebtests.Learn more about how to set up availability web tests.

Fragen?Questions? Probleme?Problems?

Problembehandlung für JavaTroubleshooting Java

Nächste SchritteNext steps