クイック スタート:Java Web プロジェクトで Application Insights を使うQuickstart: Get started with Application Insights in a Java web project

このクイックスタートでは、Application Insights を使用して、要求のインストルメント化、依存関係の追跡、およびパフォーマンス カウンターの収集を自動的に行い、パフォーマンスの問題と例外を診断し、ユーザーによるアプリの操作内容を追跡するコードを作成します。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 は、ライブ アプリケーションのパフォーマンスと使用状況を把握するのに役立つ、Web 開発者向けの拡張可能な分析サービスです。Application Insights is an extensible analytics service for web developers that helps you understand the performance and usage of your live application. Application Insights は、Linux、Unix、Windows で動作する Java アプリをサポートします。Application Insights supports Java apps running on Linux, Unix, or Windows.

前提条件Prerequisites

Application Insights のインストルメンテーション キーを取得するGet an Application Insights instrumentation key

  1. Azure portal にサインインします。Sign in to the Azure portal.

  2. Azure portal で、Application Insights のリソースを作成します。In the Azure portal, create an Application Insights resource. アプリケーションの種類を [Java Web アプリケーション] に設定します。Set the application type to Java web application.

  3. 新しいリソースのインストルメンテーション キーを見つけます。Find the instrumentation key of the new resource. このキーは、後でコード プロジェクトに貼り付けます。You'll need to paste this key into your code project shortly.

    新しいリソース概要で、[プロパティ] をクリックし、インストルメンテーション キーをコピーします

Application Insights SDK for Java をプロジェクトに追加するAdd the Application Insights SDK for Java to your project

プロジェクトの種類を選択します。Choose your project type.

プロジェクトが既に Maven を使用してビルドする設定になっている場合は、pom.xml ファイルに次のコードをマージします。If your project is already set up to use Maven for build, merge the following code to your pom.xml file.

次に、バイナリがダウンロードされるように、プロジェクトの依存関係を更新します。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>

疑問がある場合Questions

  • -web-auto-web、および -core コンポーネントの関係はどのようなものですか。What's the relationship between the -web-auto, -web and -core components?

    • applicationinsights-web-auto は、実行時に Application Insights サーブレット フィルターを自動的に登録することによって、HTTP サーブレットの要求数と応答時間を追跡するメトリックを提供します。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 も HTTP サーブレットの要求数と応答時間を追跡するメトリックを提供しますが、アプリケーションでの Application Insights サーブレット フィルターの手動の登録が必要です。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 は、ベア API のみを提供します (アプリケーションがサーブレット ベースでない場合など)。applicationinsights-core gives you just the bare API, for example, if your application isn't servlet-based.
  • SDK を最新バージョンに更新するにはどうすればよいですか。How should I update the SDK to the latest version?

    • Gradle または Maven を使用している場合:If you're using Gradle or Maven...
      • 最新バージョンを指定するようにビルド ファイルを更新します。Update your build file to specify the latest version.
    • 依存関係を手動で管理している場合:If you're manually managing dependencies...

ApplicationInsights.xml ファイルを追加するAdd an ApplicationInsights.xml file

ApplicationInsights.xml をプロジェクトのリソース フォルダーに追加するか、プロジェクトのデプロイ クラス パスに追加されていることを確認します。Add ApplicationInsights.xml to the resources folder in your project, or make sure it's added to your project's deployment class path. 次の XML をファイルにコピーします。Copy the following XML into it.

インストルメンテーション キーを Azure portal から受け取ったものに置き換えます。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>

必要に応じて、構成ファイルをアプリケーションがアクセスできる任意の場所に置くことができます。Optionally, the configuration file can be in any location accessible to your application. システム プロパティ -Dapplicationinsights.configurationDirectory に、ApplicationInsights.xml があるディレクトリを指定します。The system property -Dapplicationinsights.configurationDirectory specifies the directory that contains ApplicationInsights.xml. たとえば、E:\myconfigs\appinsights\ApplicationInsights.xml にある構成ファイルは、プロパティ -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".

  • インストルメンテーション キーは、テレメトリのすべての項目と共に送信されます。インストルメンテーション キーを受け取った Application Insights は、リソース内にこのキーを表示します。The instrumentation key is sent along with every item of telemetry and tells Application Insights to display it in your resource.
  • HTTP 要求コンポーネントはオプションです。The HTTP Request component is optional. このコンポーネントは、要求と応答時間に関するテレメトリをポータルに自動的に送信します。It automatically sends telemetry about requests and response times to the portal.
  • イベントの関連付けは、HTTP 要求コンポーネントに対する追加の操作です。Event correlation is an addition to the HTTP request component. サーバーによって受信された各要求に識別子が割り当てられます。It assigns an identifier to each request received by the server. 次に、この識別子をプロパティとして (プロパティ 'Operation.Id' として) テレメトリのすべての項目に追加します。It then adds this identifier as a property to every item of telemetry as the property 'Operation.Id'. これにより、 診断検索でフィルターを設定して、テレメトリを各要求に関連付けることができます。It allows you to correlate the telemetry associated with each request by setting a filter in diagnostic search.

インストルメンテーション キーの他の設定方法Alternative ways to set the instrumentation key

Application Insights SDK は、次の順序でキーを探します。Application Insights SDK looks for the key in this order:

  1. システム プロパティ: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikeySystem property: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. 環境変数:APPINSIGHTS_INSTRUMENTATIONKEYEnvironment variable: APPINSIGHTS_INSTRUMENTATIONKEY
  3. 構成ファイル:ApplicationInsights.xmlConfiguration file: ApplicationInsights.xml

これは コードで設定することもできます。You can also set it in code:

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

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

エージェントを追加するAdd agent

Java エージェントをインストールして、送信 HTTP 呼び出し、JDBC クエリ、アプリケーションのログ記録、およびより適切な操作の名前付けをキャプチャします。Install the Java Agent to capture outgoing HTTP calls, JDBC queries, application logging, and better operation naming.

アプリケーションを実行するRun your application

開発用コンピューターでデバッグ モードで実行するか、サーバーに発行します。Either run it in debug mode on your development machine, or publish to your server.

Application Insights でのテレメトリを表示するView your telemetry in Application Insights

Microsoft Azure ポータルの Application Insights リソースに戻ります。Return to your Application Insights resource in Microsoft Azure portal.

HTTP 要求データが概要ブレードに表示されますHTTP requests data appears on the overview blade. (表示されない場合は、数秒待ってから [最新の情報に更新] をクリックします)。(If it isn't there, wait a few seconds and then click Refresh.)

概要サンプル データのスクリーンショット

メトリックの詳細についてはこちらをご覧ください。Learn more about metrics.

任意のグラフをクリックして、より詳細な集計メトリックを表示します。Click through any chart to see more detailed aggregated metrics.

チャート付きの Application Insights の [失敗] ペイン

インスタンス データInstance data

個々のインスタンスを表示するには、特定の要求の種類をクリックします。Click through a specific request type to see individual instances.

特定のサンプル ビューをドリルダウンする

Analytics:強力なクエリ言語Analytics: Powerful query language

より多くのデータが蓄積されると、データを集計するためのクエリと、個々のインスタンスを検索するためのクエリの両方を実行できます。As you accumulate more data, you can run queries both to aggregate data and to find individual instances. Analytics は、パフォーマンスと使用状況を把握したり、診断を行ったりするための強力なツールです。Analytics is a powerful tool for both for understanding performance and usage, and for diagnostic purposes.

Example of Analytics

サーバーへのアプリのインストールInstall your app on the server

次に、サーバーにアプリを発行してユーザーがアプリを使用できるようにし、ポータルに表示されるテレメトリを監視します。Now publish your app to the server, let people use it, and watch the telemetry show up on the portal.

  • アプリケーションがこれらのポートにテレメトリを送信できるようにファイアウォールが設定されていることを確認します。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
  • 送信トラフィックをファイアウォール経由でルーティングする必要がある場合は、システム プロパティの http.proxyHosthttp.proxyPort を定義します。If outgoing traffic must be routed through a firewall, define system properties http.proxyHost and http.proxyPort.

  • Windows サーバーに次のものをインストールします。On Windows servers, install:

Azure App Service の構成 (Spring Boot)Azure App Service config (Spring Boot)

Windows で動作する Spring Boot アプリでは、 Azure App Services での追加構成の実行を必要とします。Spring Boot apps running on Windows require additional configuration to run on Azure App Services. web.config を変更し、次の構成を追加します。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>

例外と要求エラーExceptions and request failures

ハンドルされない例外と要求エラーは、Application Insights Web フィルターによって自動的に収集されます。Unhandled exceptions and request failures are automatically collected by the Application Insights web filter.

他の例外に関するデータを収集するには、コードに trackException() への呼び出しを挿入することができます。To collect data on other exceptions, you can insert calls to trackException() in your code.

メソッドの呼び出しと外部依存関係の監視Monitor method calls and external dependencies

Java エージェントをインストール して、JDBC を通じて指定された内部メソッドと実行された呼び出しをタイミング データと共にログに記録します。Install the Java Agent to log specified internal methods and calls made through JDBC, with timing data.

また、自動的な操作の名前付けの場合。And for automatic operation naming.

W3C 分散トレースW3C distributed tracing

Application Insights Java SDK では、W3C 分散トレースがサポートされるようになりました。The Application Insights Java SDK now supports W3C distributed tracing.

受信 SDK の構成の詳細については、相関関係に関する記事をご覧ください。The incoming SDK configuration is explained further in our article on correlation.

送信 SDK の構成は、AI-Agent.xml ファイル内で定義されます。Outgoing SDK configuration is defined in the AI-Agent.xml file.

パフォーマンス カウンターPerformance counters

[調査][メトリック] の順に開くと、一連のパフォーマンス カウンターが表示されます。Open Investigate, Metrics, to see a range of performance counters.

プロセス プライベート バイトが選択されているメトリック ペインのスクリーンショット

パフォーマンス カウンター コレクションをカスタマイズするCustomize performance counter collection

パフォーマンス カウンターの標準セットのコレクションを無効にするには、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>

追加のパフォーマンス カウンターを収集するCollect additional performance counters

収集する追加のパフォーマンス カウンターを指定できます。You can specify additional performance counters to be collected.

JMX カウンター (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 - Application Insights ポータルに表示される名前。displayName – The name displayed in the Application Insights portal.
  • objectName - JMX オブジェクトの名前。objectName – The JMX object name.
  • attribute - 取得する JMX オブジェクト名の属性attribute – The attribute of the JMX object name to fetch
  • type (省略可能) - JMX オブジェクトの属性の型。type (optional) - The type of JMX object's attribute:
    • 既定値: int、long などの単純型。Default: a simple type such as int or long.
    • composite: パフォーマンス カウンター データは、"Attribute.Data" 形式です。composite: the perf counter data is in the format of 'Attribute.Data'
    • tabular: パフォーマンス カウンター データは、テーブル行形式です。tabular: the perf counter data is in the format of a table row

Windows パフォーマンス カウンターWindows performance counters

それぞれの Windows パフォーマンス カウンター は、(フィールドがクラスのメンバーであるのと同様に) カテゴリのメンバーです。Each Windows performance counter is a member of a category (in the same way that a field is a member of a class). カテゴリについては、グローバルに設定することも、数字または名前付きインスタンスを設定することもできます。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 - Application Insights ポータルに表示される名前。displayName – The name displayed in the Application Insights portal.
  • categoryName - このパフォーマンス カウンターが関連付けられているパフォーマンス カウンターのカテゴリ (パフォーマンス オブジェクト)。categoryName – The performance counter category (performance object) with which this performance counter is associated.
  • counterName - パフォーマンス カウンターの名前。counterName – The name of the performance counter.
  • instanceName - パフォーマンス カウンター カテゴリ インスタンスの名前、または空の文字列 ("") (カテゴリにインスタンスが 1 つ含まれている場合)。instanceName – The name of the performance counter category instance, or an empty string (""), if the category contains a single instance. categoryName が Process であり、アプリが実行されている現在の JVM プロセスからパフォーマンス カウンターを収集する場合は、 "__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__".

Unix パフォーマンス カウンターUnix performance counters

ユーザーとセッションのデータを取得するGet user and session data

Web サーバーからテレメトリを送信しようとしているところです。OK, you're sending telemetry from your web server. ここで、アプリケーションの状態を完全に把握するために、監視を追加することもできます。Now to get the full 360-degree view of your application, you can add more monitoring:

独自のテレメトリを送信するSend your own telemetry

SDK をインストールすると、API を使用して独自のテレメトリを送信できるようになります。Now that you've installed the SDK, you can use the API to send your own telemetry.

可用性 Web テストAvailability web tests

Application Insights では、Web サイトを定期的にテストして、Web サイトが正常に動作および応答していることを確認できます。Application Insights can test your website at regular intervals to check that it's up and responding well.

可用性 Web テストを設定する方法の詳細を確認してください。Learn more about how to set up availability web tests.

疑問がある場合Questions? 問題が発生した場合Problems?

Java のトラブルシューティングTroubleshooting Java

次のステップNext steps