Application Insights for Java 2.x

[アーティクル]
02/14/2023

注意事項

この記事は、推奨されなくなった Application Insights Java 2.x に適用されます。

最新バージョン用のドキュメントについては Application Insights Java 3.x に関するページをご覧ください。

この記事では、Application Insights Java 2.x を使用する方法について説明します。この記事で取り上げるテクニック:

概要と、要求のインストルメント化、依存関係の追跡、パフォーマンスカウンターの収集、パフォーマンスの問題と例外の診断、ユーザーがアプリで行っていることを追跡するためのコードの作成の説明。
Application Insights へのトレースログの送信、および Application Insights ポータルを使用したそれらの調査。
Java Web アプリでの依存関係、キャッチされた例外、メソッド実行時間の監視。
Java Web アプリでのテレメトリのフィルター処理。
collectd を使用した Application Insights での Linux システムパフォーマンスメトリックの調査。
Java 仮想マシン (JVM) ベースのアプリケーションコードのメトリックの測定。 Micrometer アプリケーション監視を使用した、お気に入りの監視システムへのデータのエクスポート。

注意

インストルメンテーションキーのインジェストのサポートは、2025 年 3 月 31 日に終了します。インストルメンテーションキーのインジェストは引き続き機能しますが、この機能の更新プログラムやサポートは提供されなくなります。接続文字列に移行することで、新機能をご利用いただけます。

Java Web プロジェクトで Application Insights を使う

このセクションでは、Application Insights SDK を使用して、要求のインストルメント化、依存関係の追跡、パフォーマンスカウンターの収集、パフォーマンスの問題と例外の診断、ユーザーがアプリで行う操作を追跡するコードの記述を行ないます。

Application Insights は、ライブアプリケーションのパフォーマンスと使用状況を把握するのに役立つ、Web 開発者向けの拡張可能な分析サービスです。 Application Insights は、Linux、Unix、Windows で動作する Java アプリをサポートします。

前提条件

必要なもの:

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
機能している Java アプリケーション。

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

Azure portal にサインインします。
Azure portal で、Application Insights のリソースを作成します。アプリケーションの種類を [Java Web アプリケーション] に設定します。
新しいリソースのインストルメンテーションキーを見つけます。このキーは、後でコードプロジェクトに貼り付けます。

Application Insights SDK for Java をプロジェクトに追加する

プロジェクトの種類を選択します。

Maven
Gradle

プロジェクトが既に Maven を使用してビルドする設定になっている場合は、pom.xml ファイルに次のコードをマージします。次に、バイナリがダウンロードされるように、プロジェクトの依存関係を更新します。

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

プロジェクトが既に Gradle を使用してビルドする設定になっている場合は、build.gradle ファイルに次のコードをマージします。次に、バイナリがダウンロードされるように、プロジェクトの依存関係を更新します。

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

よく寄せられる質問

-web-auto、-web、-core コンポーネントの関係はどのようなものですか。
- applicationinsights-web-auto は、実行時に Application Insights サーブレットフィルターを自動的に登録することによって、HTTP サーブレットの要求数と応答時間を追跡するメトリックを提供します。
- また、applicationinsights-web は HTTP サーブレット要求数と応答時間を追跡するメトリックを提供します。ただし、アプリケーションで Application Insights サーブレットフィルターを手動で登録する必要があります。
- applicationinsights-core は、ベア API を提供します (アプリケーションがサーブレットベースでない場合など)。
SDK を最新バージョンに更新するにはどうすればよいですか。
- 2020 年 11 月以降、Java アプリケーションの監視には、Application Insights Java 3.x の使用をお勧めします。開始方法について詳しくは、Application Insights Java 3.x に関するページを参照してください。

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

ApplicationInsights.xml をプロジェクトのリソースフォルダーに追加するか、プロジェクトのデプロイクラスパスに追加されていることを確認します。次の XML をファイルにコピーします。

インストルメンテーションキーを 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>

必要に応じて、構成ファイルをアプリケーションがアクセスできる任意の場所に置くことができます。システムプロパティ -Dapplicationinsights.configurationDirectory に、ApplicationInsights.xml があるディレクトリを指定します。たとえば、E:\myconfigs\appinsights\ApplicationInsights.xml にある構成ファイルは、プロパティ -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights" を使用して構成されます。

インストルメンテーションキーは、テレメトリのすべての項目と共に送信されます。インストルメンテーションキーを受け取った Application Insights は、リソース内にこのキーを表示します。
HTTP 要求コンポーネントはオプションです。このコンポーネントは、要求と応答時間に関するテレメトリをポータルに自動的に送信します。
イベントの関連付けは、HTTP 要求コンポーネントに対する追加の操作です。サーバーによって受信された各要求に識別子が割り当てられます。次に、この識別子をプロパティとして (プロパティ Operation.Id として) テレメトリのすべての項目に追加します。これにより、診断検索でフィルターを設定して、テレメトリを各要求に関連付けることができます。

インストルメンテーションキーの他の設定方法

Application Insights SDK は、次の順序でキーを探します。

システムプロパティ: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
環境変数: APPINSIGHTS_INSTRUMENTATIONKEY
構成ファイル: ApplicationInsights.xml

これはコードで設定することもできます。

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

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

エージェントを追加する

Java エージェントをインストールして、送信 HTTP 呼び出し、JDBC クエリ、アプリケーションのログ記録、およびより適切な操作の名前付けをキャプチャします。

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

開発用コンピューターでデバッグモードで実行するか、サーバーに発行します。

Application Insights でのテレメトリを表示する

Azure portal の Application Insights のリソースに戻ります。

HTTP 要求データが概要ペインに表示されます。表示されない場合は、数秒待ってから [最新の情報に更新] を選択します。

メトリックの詳細をご覧ください。

任意のグラフをクリックして、より詳細な集計メトリックを表示します。

インスタンスデータ

個々のインスタンスを表示するには、特定の要求の種類をクリックします。

Log Analytics - 強力なクエリ言語

より多くのデータが蓄積されると、データを集計して個々のインスタンスを検索するためにクエリを実行できます。 Log Analytics は、パフォーマンスと使用状況を把握したり、診断を行ったりするための強力なツールです。

サーバーへのアプリのインストール

次に、サーバーにアプリを発行してユーザーがアプリを使用できるようにし、ポータルに表示されるテレメトリを監視します。

アプリケーションがこれらのポートにテレメトリを送信できるようにファイアウォールが設定されていることを確認します。
- dc.services.visualstudio.com:443
- f5.services.visualstudio.com:443
送信トラフィックをファイアウォール経由でルーティングする必要がある場合は、システムプロパティの http.proxyHost と http.proxyPort を定義します。
Windows サーバーに次のものをインストールします。
- Microsoft Visual C++ 再頒布可能パッケージ
  
  このコンポーネントにより、パフォーマンスカウンターが有効になります。

Azure App Service、Azure Kubernetes Service、VM 構成

Azure リソースプロバイダーのいずれかで実行されているアプリケーションを監視する際に最適で最も簡単な方法は、Application Insights Java 3.x を使用することです。

例外と要求エラー

ハンドルされない例外と要求エラーは、Application Insights Web フィルターによって自動的に収集されます。

他の例外に関するデータを収集するには、コードに trackException() への呼び出しを挿入することができます。

メソッドの呼び出しと外部依存関係の監視

Java エージェントをインストールして、JDBC を通じて指定された内部メソッドと実行された呼び出しをタイミングデータと共にログに記録し、自動的な操作の名前付けを行います。

W3C 分散トレース

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

受信 SDK の構成については、「Application Insights のテレメトリの関連付け」で詳しく説明されています。

送信 SDK の構成は、AI-Agent.xml ファイル内で定義されます。

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

[調査]>[メトリック] を選択すると、一連のパフォーマンスカウンターが表示されます。

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

パフォーマンスカウンターの標準セットのコレクションを無効にするには、ApplicationInsights.xml ファイルのルートノードの下に次のコードを追加します。

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

その他のパフォーマンスカウンターを収集する

収集する追加のパフォーマンスカウンターを指定できます。

JMX カウンター (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: Application Insights ポータルに表示される名前。
objectName: JMX オブジェクトの名前。
attribute: 取得する JMX オブジェクト名の属性。
type (省略可能): JMX オブジェクトの属性の型:
- 既定値: int、long などの単純型。
- composite: パフォーマンスカウンターデータは、Attribute.Data 形式です。
- tabular: パフォーマンスカウンターデータは、テーブル行形式です。

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

それぞれの Windows パフォーマンスカウンターは、(フィールドがクラスのメンバーであるのと同様に) カテゴリのメンバーです。カテゴリについては、グローバルに設定することも、数字または名前付きインスタンスを設定することもできます。

    <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 ポータルに表示される名前。
categoryName: このパフォーマンスカウンターが関連付けられているパフォーマンスカウンターのカテゴリ (パフォーマンスオブジェクト)。
counterName: パフォーマンスカウンターの名前です。
instanceName: パフォーマンスカウンターカテゴリインスタンスの名前。カテゴリに含まれるインスタンスが 1 つだけの場合は空の文字列 ("")。 categoryName が Process であり、アプリが実行されている現在の JVM プロセスからパフォーマンスカウンターを収集する場合は、"__SELF__" を指定します。

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

Application Insights プラグインを使用して collectd をインストールし、さまざまな種類のシステムとネットワークに関するデータを取得します。

ユーザーとセッションのデータを取得する

Web サーバーからテレメトリを送信します。アプリケーションの状態を完全に把握するために、監視を追加することもできます。

Web ページにテレメトリを追加して、ページビューやユーザーメトリックを監視します。
Web テストを設定して、アプリケーションが動作していて応答できることを確認します。

独自のテレメトリを送信する

SDK をインストールすると、API を使用して独自のテレメトリを送信できるようになります。

アプリケーションでのユーザーの行動を把握するには、カスタムイベントおよびメトリックを追跡します。
イベントおよびログを検索します。

可用性 Web テスト

Application Insights では、Web サイトを定期的にテストして、Web サイトが正常に動作および応答していることを確認できます。

可用性 Web テストを設定する方法の詳細を確認してください。

トラブルシューティング

専用のトラブルシューティングに関する記事をご覧ください。

アプリケーションホストとインジェストサービスの間の接続をテストする

Application Insights SDK とエージェントからテレメトリが送信され、インジェストエンドポイントへの REST 呼び出しとして取り込まれます。 Web サーバーまたはアプリケーションホストマシンからインジェストサービスエンドポイントへの接続は、PowerShell の生の REST クライアントを使用するか、curl コマンドを使用してテストできます。「Azure Monitor Application Insights でアプリケーションテレメトリが見つからない場合のトラブルシューティング」をご覧ください。

Application Insights を使用した Java トレースログの探索

トレース用に Logback または Log4J (v1.2 または v2.0) を使用している場合は、トレースログを自動的に Application Insights に送信して、Application Insights でトレースログを探索および検索できます。

ヒント

Application Insights インストルメンテーションキーは、アプリケーションに対して 1 回だけ設定する必要があります。 Java Spring のようなフレームワークを使用している場合は、アプリの構成の別の場所で既にキーを登録済みである可能性があります。

Application Insights Java エージェントを使用する

既定では、Application Insights Java エージェントは、WARN レベル以上で実行されたログを自動的にキャプチャします。

AI-Agent.xml ファイルを使用して、キャプチャされるログのしきい値を変更できます。

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

AI-Agent.xml ファイルを使用して、Java エージェントによるログのキャプチャを無効にできます。

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

代替

Java エージェントを使用する代わりに、次の手順に従うことができます。

Java SDK をインストールする

Application Insights SDK for Java をまだインストールしていない場合は、インストールする手順に従います。

プロジェクトへのログライブラリの追加

プロジェクトに適した方法を選択してください。

Maven

プロジェクトが既に Maven を使用してビルドする設定になっている場合は、pom.xml ファイルに次のいずれかのコードスニペットをマージします。次に、バイナリがダウンロードされるように、プロジェクトの依存関係を更新します。

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

プロジェクトが既に Gradle を使用してビルドする設定になっている場合は、次のいずれかの行を build.gradle ファイルの dependencies グループに追加します。次に、バイナリがダウンロードされるように、プロジェクトの依存関係を更新します。

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.+'

jar リンクを使用する

ガイドラインに従って Application Insights Java SDK を手動でインストールし、jar をダウンロードします。 Maven Central ページで、適切なアペンダーのダウンロードセクションの jar リンクを選択します。ダウンロードしたアペンダー jar をプロジェクトに追加します。

ロガー	ダウンロード	ライブラリ
Logback	Logback アペンダー Jar	applicationinsights-logging-logback
Log4J v2.0	Log4J v2 アペンダー Jar	applicationinsights-logging-log4j2
Log4J v1.2	Log4J v1.2 アペンダー Jar	applicationinsights-logging-log4j1_2

ログフレームワークへのアペンダーの追加

トレースの取得を開始するには、適切なコードスニペットを Logback または 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>

Application Insights のアペンダーは、前述のコードサンプルに示されているように、構成済みの任意のロガーによって参照でき、必ずしもルートロガーを使用する必要はありません。

Application Insights ポータルでのトレースの探索

これで、Application Insights にトレースを送信するようにプロジェクトが構成されました。これらのトレースは、Application Insights ポータルの [検索] ウィンドウで表示して検索できます。

ロガー経由で送信された例外は、例外のテレメトリとしてポータルに表示されます。

Java Web アプリでの依存関係、キャッチされた例外、メソッド実行時間の監視

Java Web アプリを Application Insights SDK でインストルメント化した場合、Java エージェントを使用して、コードを変更することなく、詳細な分析を行うことができます。

依存関係: アプリケーションが他のコンポーネントに対して行った呼び出しについてのデータであり、次のものを含みます。
- 発信 HTTP 呼び出し: Apache HttpClient、OkHttp、java.net.HttpURLConnection を介して行われた呼び出しがキャプチャされます。
- Redis 呼び出し: Jedis クライアント経由で行われた呼び出しがキャプチャされます。
- JDBC クエリ: MySQL と PostgreSQL で呼び出しにかかる時間が 10 秒を超えた場合、エージェントはクエリプランをレポートします。
アプリケーションのログ記録: アプリケーションログをキャプチャし、HTTP 要求やその他のテレメトリに関連付けます。
- Log4j 1.2
- Log4j2
- Logback
操作の名前付けの改善: ポータルでの要求の集計に使用します。
- Spring: @RequestMapping に基づきます。
- JAX-RS: @Path に基づきます。

Java エージェントを使用するには、これをサーバーにインストールします。 Web アプリを Application Insights Java SDK を使用してインストルメント化する必要があります。

Jave 用の Application Insights エージェントのインストール

Java サーバーを実行しているコンピューターで 2.x エージェントをダウンロードします。使用する 2.x Java エージェントのバージョンが、使用する 2.x Application Insights Java SDK のバージョンと一致していることを確認してください。
アプリケーションサーバーのスタートアップスクリプトを編集し、次の JVM 引数を追加します。

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

たとえば、Linux マシンの Tomcat で以下を実行します。

export JAVA_OPTS="$JAVA_OPTS -javaagent:<full path to agent JAR file>"
アプリケーションサーバーを再起動します。

エージェントの構成

AI-Agent.xml という名前のファイルを作成し、エージェントの jar ファイルの場所と同じフォルダーに配置します。

XML ファイルの内容を設定します。次の例を編集して、必要に応じて、機能を含めるか省略します。

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

追加構成 (Spring Boot)

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

Azure App Service の場合、次の手順を行います。

[設定]>[アプリケーション設定] を選択します。
[アプリ設定] で、新しいキー値ペアを追加します。
- キー: JAVA_OPTS
- 値: -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.6.4.jar
エージェントは、D:/home/site/wwwroot/ で終わるようにプロジェクト内でリソースとしてパッケージ化する必要があります。 [開発ツール]>[高度なツール]>[デバッグコンソール] に進み、サイトディレクトリの内容を調べることで、エージェントが正しい App Service ディレクトリにあることを確認できます。
設定を保存し、アプリを再起動します。これらの手順は、Windows で実行しているアプリサービスにのみ適用されます。

注意

AI-Agent.xml とエージェントの jar ファイルは同じフォルダーに含まれている必要があります。多くの場合、これらはプロジェクトの /resources フォルダーに一緒に配置されます。

W3C 分散トレースを有効にする

AI-Agent.xml に次のスニペットを追加します。

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

注意

下位互換性モードは既定で有効になっています。 enableW3CBackCompat パラメーターは、省略可能で、このモードをオフにするときにのみ使用する必要があります。

すべてのサービスが、W3C プロトコルをサポートする新しいバージョンの SDK に更新されたときに、これを行うことが理想的です。 W3C サポートを使用して、できるだけ早く新しいバージョンの SDK に移行することをお勧めします。

"受信と送信 (エージェント) の構成が両方とも" 正確に同じであることを確認してください。

データの表示

Application Insights リソースでは、集計されたリモートの依存関係やメソッドの実行時間が [パフォーマンス] タイルに表示されます。

依存関係、例外、メソッドのレポートの個々のインスタンスを検索するには、[検索] を開きます。

依存関係の問題を診断する方法の詳細を確認してください。

質問または問題

次のリソースを使用します。

データが表示されない場合ファイアウォール例外の設定。
Java のトラブルシューティング。

Java Web アプリでのテレメトリのフィルター処理

フィルターは、お使いの Java Web アプリが Application Insights に送信するテレメトリを選択する方法を提供します。すぐに使用できるフィルターがいくつかあります。また、独自のカスタムフィルターを記述することもできます。

すぐに使えるフィルターは、次のとおりです。

重大度レベル。
特定の URL、キーワード、または応答コード。
高速応答。つまり、アプリが迅速に応答した要求です。
特定のイベント名。

Note

フィルターでは、アプリのメトリックにゆがみが生じます。たとえば、遅い応答を診断するために、高速な応答時間を破棄するフィルターを設定するとします。ただし、Application Insights によって報告される平均応答時間は実際の速度より低くなることに注意する必要があります。また、要求の数は実際の数よりも小さくなります。

これが問題になる場合は、代わりにサンプリングを使用します。

Set filters

ApplicationInsights.xml で、次の例のように TelemetryProcessors セクションを追加します。


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

すべてのビルトインプロセッサを確認します。

ビルトインフィルター

このセクションでは、使用できる組み込みフィルターについて説明します。

メトリックテレメトリフィルター


           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>

NotNeeded: カスタムメトリック名のコンマ区切りのリスト

ページビューテレメトリフィルター


           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="500"/>
                  <Add name="NotNeededNames" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>

DurationThresholdInMS: ここで、期間はページの読み込みにかかる時間です。このパラメーターを設定した場合、この時間よりも高速に読み込まれたページは報告されません。
NotNeededNames: ページ名のコンマ区切りリスト。
NotNeededUrls: URL フラグメントのコンマ区切りリスト。たとえば、"home" は URL に "home" のあるすべてのページを除外します。

要求テレメトリフィルター


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

合成ソースフィルター

SyntheticSource プロパティに値を持つすべてのテレメトリを除外します。ボット、スパイダー、および可用性テストからの要求が含まれます。

すべての合成要求のテレメトリを除外します。


           <Processor type="SyntheticSourceFilter" />

特定の合成ソースのテレメトリを除外します。


           <Processor type="SyntheticSourceFilter" >
                  <Add name="NotNeeded" value="source1,source2"/>
           </Processor>

NotNeeded: 合成ソース名のコンマ区切りのリスト

テレメトリイベントフィルター

TrackEvent() を使用してログに記録されたカスタムイベントをフィルター処理します。


           <Processor type="TelemetryEventFilter" >
                  <Add name="NotNeededNames" value="event1, event2"/>
           </Processor>

NotNeededNames: イベント名のコンマ区切りリスト

トレーステレメトリフィルター

TrackTrace() またはログ記録フレームワークコレクターを使用して記録されたログトレースをフィルターします。


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

FromSeverityLevel の有効な値は次のとおりです。
- OFF: "すべての" トレースを除外。
- TRACE: フィルタリングなし。 TRACE レベルに等しい。
- INFO: TRACE レベルを除外。
- WARN: TRACE と INFO を除外。
- ERROR: WARN、INFO、TRACE を除外。
- CRITICAL: CRITICAL 以外のすべてを除外。

カスタムフィルター

次のセクションでは、独自のカスタムフィルターを作成する手順について説明します。

フィルターをコーディングする

コード内に、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;
        }
    }

構成ファイルでフィルターを呼び出す

ApplicationInsights.xml で、以下を使用します。



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

お使いのフィルターを呼び出す (Java Spring)

Spring フレームワークに基づくアプリケーションの場合、カスタムのテレメトリプロセッサを、ご自身のメインアプリケーションクラスに Bean として登録する必要があります。その後、アプリケーションの開始時に自動接続されます。

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

application.properties で独自のフィルターパラメーターを作成します。次に、Spring Boot の外部化された構成フレームワークを使用して、これらのパラメーターをカスタムフィルターに渡します。

トラブルシューティング

このセクションでは、トラブルシューティングのヒントを提供します。

フィルターが機能しない

有効なパラメーター値を指定していることを確認してください。たとえば、期間は整数である必要があります。無効な値を指定すると、フィルターは無視されます。カスタムフィルターがコンストラクターまたは set メソッドから例外をスローした場合、これも無視されます。

collectd:Application Insights の Linux パフォーマンスメトリック (非推奨)

Application Insights で Linux システムのパフォーマンスメトリックを探索するには、collectd を Application Insights のプラグインと共にインストールします。このオープンソースソリューションでは、さまざまなシステムおよびネットワーク統計情報を収集します。

既に Application Insights で Java Web サービスをインストルメント化してある場合は、通常、collectd を使用します。 collectd を使用すると、アプリのパフォーマンスの向上や問題の診断に役立つ多くのデータを得られます。

インストルメンテーションキーの取得

Azure portal で、データを表示する Application Insights リソースを開きます。または新しいリソースを作成することもできます。

リソースを識別する、インストルメンテーションキーのコピーを取ります。

collectd とプラグインのインストール

Linux サーバーコンピューターで、次の操作を行います。

collectd のバージョン 5.4.0 またはそれ以降をインストールします。
Application Insights collectd ライタープラグインをダウンロードします。バージョン番号をメモしておきます。
プラグイン jar を /usr/share/collectd/javaにコピーします。

/etc/collectd/collectd.confを編集します:

Java プラグインが有効になっていることを確認します。
java.class.path の JVMArg を次の jar を含むように更新します。バージョン番号を、ダウンロードしたものと一致するように更新します。
- /usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar

リソースからのインストルメンテーションキーを使用して、次のスニペットを追加します。


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

サンプル構成ファイルの一部を次に示します。


    ...
    # 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>
    ...

その他の collectd プラグインを構成します。これにより、異なるソースからさまざまなデータを収集できます。

マニュアルに従って collectd を再起動します。

Application Insights でデータを表示する

Application Insights リソースで、[メトリック] を開き、グラフを追加します。 カスタム カテゴリから確認するメトリックを選択します。

既定では、メトリックは、メトリックの収集元のすべてのホストコンピューターにわたって集計されます。ホスト別のメトリックを表示するには、[グラフの詳細] ウィンドウで [グループ化] を有効にし、CollectD-Host 別のグループ化を選択します。

特定の統計のアップロードを除外する

既定では、Application Insights プラグインにより、すべての有効になっている collectd read プラグインによって収集されたすべてのデータが送信されます。

特定のプラグインまたはデータソースからのデータを除外するには:

構成ファイルを編集します。

<Plugin ApplicationInsightsWriter> で、次の表のようなディレクティブ行を追加します。

ディレクティブ	結果
`Exclude disk`	`disk` プラグインによって収集されたすべてのデータを除外します。
`Exclude disk:read,write`	`read` および `write` という名前のソースを `disk` プラグインから除外します。

各ディレクティブを改行で区切ります。

問題が発生した場合

このセクションでは、トラブルシューティングのヒントを提供します。

ポータルにデータが表示されません。

次のオプションを試してください。

[検索] を開き、未加工のイベントが到着しているかどうかを確認します。メトリックスエクスプローラーに表示されるまでに時間がかかる場合があります。
必要に応じてデータ送信についてファイアウォール例外を設定します。
Application Insights プラグインでトレースを有効にします。 <Plugin ApplicationInsightsWriter>に次の行を追加します。
- SDKLogger true
ターミナルを開き、詳細モードで collectd を起動して報告されている問題がないか確認します。
- sudo collectd -f

既知の問題

Application Insights 書き込みプラグインは、特定の読み取りプラグインと互換性がありません。一部のプラグインでは NaN を送信することがありますが、Application Insights プラグインでは浮動小数点数が必要です。

症状: collectd ログに、"AI: ...SyntaxError:Unexpected token N" を含むエラーが示されています。
対処法: 問題のある書き込みプラグインによって収集されるデータを除外します。

Application Insights Java SDK で Micrometer を使用する (非推奨)

Micrometer のアプリケーション監視では、JVM ベースのアプリケーションコードのメトリックが測定され、好みの監視システムにデータをエクスポートできます。このセクションでは、Spring Boot アプリケーションと非 Spring Boot アプリケーションの両方に対して、Application Insights で Micrometer を使用する方法について説明します。

Spring Boot 1.5x を使用する

次の依存関係を pom.xml または build.gradle ファイルに追加します。

Application Insights spring-boot-starter 2.5.0 以降。
Micrometer Azure Registry 1.1.0 以降。
Micrometer Spring Legacy 1.1.0 以降。 Spring フレームワークで自動構成コードをバックポートします。
Application Insights リソース。

次の手順に従います。

Spring Boot アプリケーションの pom.xml ファイルを更新し、次の依存関係を追加します。

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

次のプロパティを使用して、Application Insights のインストルメンテーションキーで application.properties または YML ファイルを更新します。

azure.application-insights.instrumentation-key=<your-instrumentation-key-here>
アプリケーションをビルドして実行します。

前の手順によって、集計前のメトリックが Azure Monitor に自動収集され、動作するはずです。

Spring 2.x を使用する

次の依存関係を pom.xml または build.gradle ファイルに追加します。

Application Insights Spring-boot-starter 2.1.2 以降
Azure-spring-boot-metrics-starters 2.0.7 以降
Application Insights リソース

次の手順に従います。

Spring Boot アプリケーションの pom.xml ファイルを更新し、次の依存関係を追加します。

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

次のプロパティを使用して、Application Insights のインストルメンテーションキーで application.properties または YML ファイルを更新します。

azure.application-insights.instrumentation-key=<your-instrumentation-key-here>
アプリケーションをビルドして実行します。

前の手順によって、集計前のメトリックが Azure Monitor に自動収集され、動作するはずです。 Application Insights Spring Boot スターターを微調整する方法の詳細については、GitHub の readme を参照してください。

既定のメトリック:

Tomcat、JVM、Logback メトリック、Log4J メトリック、アップタイムメトリック、プロセッサメトリック、FileDescriptorMetrics 用に自動構成されるメトリック。
たとえば、Netflix Hystrix がクラスパス上に存在する場合は、それらのメトリックも取得されます。
それぞれの Bean を追加することで、次のメトリックを使用できます。
- CacheMetrics (CaffeineCache、EhCache2、GuavaCache、HazelcastCache、JCache)
- DataBaseTableMetrics
- HibernateMetrics
- JettyMetrics
- OkHttp3 Metrics
- Kafka Metrics

自動メトリック収集をオフにする:

JVM メトリック:
- management.metrics.binders.jvm.enabled=false
Logback メトリック:
- management.metrics.binders.logback.enabled=false
アップタイムメトリック:
- management.metrics.binders.uptime.enabled=false
プロセッサメトリック:
- management.metrics.binders.processor.enabled=false
FileDescriptorMetrics:
- management.metrics.binders.files.enabled=false
Hystrix メトリック (classpath にライブラリがある場合):
- management.metrics.binders.hystrix.enabled=false
AspectJ メトリック (classpath にライブラリがある場合):
- spring.aop.enabled=false

Note

Spring Boot アプリケーションの application.properties または application.yml ファイルで、前述のプロパティを指定します。

非 Spring Boot Web アプリケーションで Micrometer を使用する

次の依存関係を pom.xml または build.gradle ファイルに追加します。

Application Insights Web Auto 2.5.0 以降
Micrometer Azure Registry 1.1.0 以降
Application Insights リソース

次の手順に従います。

次の依存関係を pom.xml または 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>

まだ行っていない場合は、ApplicationInsights.xml ファイルを resources フォルダーに追加します。詳しくは、「ApplicationInsights.xml ファイルを追加する」を参照してください。

Servlet クラスのサンプル (タイマーメトリックを出力):

    @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");
      }

    }

構成クラスのサンプル:

     @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) {

       }
     }

メトリックの詳細については、Micrometer のドキュメントを参照してください。

さまざまな種類のメトリックを作成する方法に関する他のサンプルコードは、Micrometer の公式 GitHub リポジトリで入手できます。

さらにメトリックコレクションをバインドする

次のセクションでは、より多くのメトリックを収集する方法について説明します。

SpringBoot/Spring

それぞれのメトリックのカテゴリの Bean を作成します。たとえば、Guava キャッシュメトリックが必要な場合は次のようになります。

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

いくつかのメトリックは既定では有効になっていませんが、上記の方法でバインドできます。完全な一覧については、Micrometer の GitHub リポジトリを参照してください。

非 Spring アプリ

構成ファイルに次のバインドコードを追加します。

    New GuavaCacheMetrics().bind(registry);

次のステップ

Web ページに監視機能を追加して、ページの読み込み時間、AJAX 呼び出し、ブラウザーの例外を監視する。
カスタムテレメトリを書き込んで、ブラウザーまたはサーバーでの使用状況を追跡する
Log Analytics を使用して、アプリからのテレメトリに対して強力なクエリを実行する。
診断検索を使用する。
フィルター処理に代わる方法として、メトリックが歪曲されないサンプリングを検討してください。
Micrometer の詳細については、Micrometer ドキュメントを参照してください。
Azure での Spring については、Azure の Spring ドキュメントを参照してください。
詳細については、Java 開発者向けの Azure に関するページを参照してください。

次の方法で共有

Application Insights for Java 2.x

Java Web プロジェクトで Application Insights を使う

前提条件

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

Application Insights SDK for Java をプロジェクトに追加する

よく寄せられる質問

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

インストルメンテーション キーの他の設定方法

エージェントを追加する

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

Application Insights でのテレメトリを表示する

インスタンス データ

Log Analytics - 強力なクエリ言語

サーバーへのアプリのインストール

Azure App Service、Azure Kubernetes Service、VM 構成

例外と要求エラー

メソッドの呼び出しと外部依存関係の監視

W3C 分散トレース

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

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

その他のパフォーマンス カウンターを収集する

JMX カウンター (Java 仮想マシンによって公開されます)

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

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

ユーザーとセッションのデータを取得する

独自のテレメトリを送信する

可用性 Web テスト

トラブルシューティング

アプリケーション ホストとインジェスト サービスの間の接続をテストする

Application Insights を使用した Java トレース ログの探索

Application Insights Java エージェントを使用する

代替

Java SDK をインストールする

プロジェクトへのログ ライブラリの追加

Maven

Gradle

jar リンクを使用する

ログ フレームワークへのアペンダーの追加

Application Insights ポータルでのトレースの探索

Java Web アプリでの依存関係、キャッチされた例外、メソッド実行時間の監視

Jave 用の Application Insights エージェントのインストール

エージェントの構成

追加構成 (Spring Boot)

W3C 分散トレースを有効にする

データの表示

質問または問題

Java Web アプリでのテレメトリのフィルター処理

Set filters

ビルトイン フィルター

メトリック テレメトリ フィルター

ページ ビュー テレメトリ フィルター

要求テレメトリ フィルター

合成ソース フィルター

テレメトリ イベント フィルター

トレース テレメトリ フィルター

カスタム フィルター

フィルターをコーディングする

構成ファイルでフィルターを呼び出す

お使いのフィルターを呼び出す (Java Spring)

トラブルシューティング

フィルターが機能しない

collectd:Application Insights の Linux パフォーマンス メトリック (非推奨)

インストルメンテーション キーの取得

collectd とプラグインのインストール

Application Insights でデータを表示する

特定の統計のアップロードを除外する

問題が発生した場合

ポータルにデータが表示されません。

既知の問題

Application Insights Java SDK で Micrometer を使用する (非推奨)

Spring Boot 1.5x を使用する

Spring 2.x を使用する

非 Spring Boot Web アプリケーションで Micrometer を使用する

さらにメトリック コレクションをバインドする

SpringBoot/Spring

非 Spring アプリ

次のステップ

その他のリソース

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

インストルメンテーションキーの他の設定方法

インスタンスデータ

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

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

その他のパフォーマンスカウンターを収集する

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

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

アプリケーションホストとインジェストサービスの間の接続をテストする

Application Insights を使用した Java トレースログの探索

プロジェクトへのログライブラリの追加

ログフレームワークへのアペンダーの追加

ビルトインフィルター

メトリックテレメトリフィルター

ページビューテレメトリフィルター

要求テレメトリフィルター

合成ソースフィルター

テレメトリイベントフィルター

トレーステレメトリフィルター

カスタムフィルター

collectd:Application Insights の Linux パフォーマンスメトリック (非推奨)

インストルメンテーションキーの取得

さらにメトリックコレクションをバインドする