Java Web プロジェクトで Application Insights を使うGet started with Application Insights in a Java web project

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. 要求の自動的なインストルメント化、依存関係の追跡、パフォーマンス カウンターの収集、パフォーマンスの問題と例外の診断、ユーザーがアプリで行っていることを追跡するためのコードの作成に使用します。Use it 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 は、Linux、Unix、Windows で動作する Java アプリをサポートします。Application Insights supports Java apps running on Linux, Unix, or Windows.

必要なもの:You need:

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

  1. Microsoft Azure ポータルにサインインします。Sign in to the Microsoft Azure portal.

  2. Application Insights リソースを作成します。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.

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

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

プロジェクトに適した方法を選択してください。Choose the appropriate way for your project.

Maven を使用している場合: If you're using Maven...

プロジェクトが既に 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>

Gradle を使用している場合: If you're using Gradle...

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

次に、バイナリがダウンロードされるように、プロジェクトの依存関係を更新します。Then refresh the project dependencies to get the binaries downloaded.

    dependencies {
      compile group: 'com.microsoft.azure', name: 'applicationinsights-web-auto', version: '2.5.0'
      // or applicationinsights-web for manual web filter registration
      // or applicationinsights-core for bare API
    }

それ以外で、依存関係を手動で管理している場合:Otherwise, if you are manually managing dependencies ...

最新バージョンをダウンロードし、必要なファイルをプロジェクトにコピーして、以前のバージョンを置き換えます。Download the latest version and copy the necessary files into your project, replacing any previous versions.

疑問がある場合...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 is not servlet-based.
  • SDK を最新バージョンに更新するにはどうすればよいですか。How should I update the SDK to the latest version?

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

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

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

インストルメンテーション キーについては、Azure ポータルで入手したキーを使用してください。Substitute the instrumentation key 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 reside 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. この操作では、サーバーで受信した各要求に識別子を割り当てた後、この識別子をテレメトリのすべての項目に "Operation.Id" プロパティとして追加します。It assigns an identifier to each request received by the server, and 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);
    }

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

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

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

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

6.Application Insights でのテレメトリを表示する6. 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

7.サーバーへのアプリのインストール7. 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:

<?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