Java アプリケーションのための Azure Monitor OpenTelemetry ベースの自動インストルメンテーション

この記事では、OpenTelemetry ベースの Azure Monitor Java オファリングを有効にして構成する方法について説明します。 オンプレミスを含む任意の環境で使用できます。 この記事の手順を完了すると、Azure Monitor Application Insights を使用してアプリケーションを監視できるようになります。

注意

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

はじめに

Java の自動インストルメンテーションは、構成の変更によって有効になります。コードの変更は必要ありません。

必須コンポーネント

Azure Monitor Application Insights を有効にする

このセクションでは、自動インストルメンテーション jar ファイルをダウンロードする方法について説明します。

jar ファイルのダウンロード

applicationinsights-agent-3.4.4.jar ファイルをダウンロードします。

警告

以前の 3.x バージョンからアップグレードする場合

3.4.0 以降:

  • レート制限サンプリングが既定値になりました (以前に固定パーセンテージを構成していない場合)。 既定では、1 秒あたり最大約 5 件の要求がキャプチャされます (依存関係、トレース、カスタム イベントと共に)。 要求の 100% をキャプチャする以前の動作に戻す場合は、固定率のサンプリングに関する記事をご覧ください。

3.3.0 以降:

  • LoggingLevel は、トレースのカスタム ディメンションの一部として既定ではキャプチャされません。そのデータは既に SeverityLevel フィールドでキャプチャされているためです。 必要に応じてこれを有効にする方法については、「構成オプション」を参照してください。
  • 失敗した依存関係の例外レコードは記録されなくなり、失敗した要求についてのみ記録されます。

3.2.0 以降:

  • コントローラー "InProc" の依存関係は既定ではキャプチャされません。 これをもう一度有効にする方法については、構成オプションに関する記事をご覧ください。
  • 完全な (サニタイズされた) クエリは変わらず data フィールド内に存在しながら、データベースの依存関係名がより簡潔になりました。 HTTP の依存関係名がよりわかりやすいものになっています。 この変更は、以前の値に依存しているカスタム ダッシュボードまたはアラートに影響を与える場合があります。 詳細については、3.2.0 のリリース ノートを参照してください。

3.1.0 以降:

  • 操作名と要求テレメトリ名の先頭には、HTTP メソッド (GETPOST など) が付けられます。 この変更は、以前の値に依存しているカスタム ダッシュボードまたはアラートに影響を与える場合があります。 詳細については、3.1.0 のリリース ノートを参照してください。

JVM が jar ファイルを指すようにする

アプリケーションの JVM 引数に -javaagent:"path/to/applicationinsights-agent-3.4.4.jar" を追加します。

ヒント

アプリケーションの JVM 引数の構成に関するヘルプについては、JVM の引数の更新に関するヒントのページを参照してください。

ヒント

Spring Boot アプリケーションを開発する場合は、JVM 引数をプログラムによる構成で置き換えることができます。 詳しくは、こちらをご覧ください

Application Insights の接続文字列を設定する

  1. jar ファイルを Application Insights リソースにポイントするには、次の 2 つの方法があります。

    • 環境変数を設定できます。

      APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>
      
    • または、applicationinsights.json という名前の構成ファイルを作成できます。 applicationinsights-agent-3.4.4.jar と同じディレクトリに配置し、次の内容を設定します。

      {
        "connectionString": "Copy connection string from Application Insights Resource Overview"
      }
      
  2. Application Insights リソースの接続文字列を見つけます。

    Application Insights の概要と接続文字列を示すスクリーンショット。

データが流れていることを確認する

アプリケーションを実行し、Azure portal で [Application Insights リソース] タブを開きます。 ポータルにデータが表示されるまでに数分かかることがあります。

注意

アプリケーションを実行できない場合、または期待どおりにデータを取得できない場合は、「トラブルシューティング」セクションをご覧ください。

サーバー要求とサーバー応答時間が強調表示されている Application Insights の [概要] タブのスクリーンショット。

重要

同じ Application Insights リソースにテレメトリを出力しているサービスが 2 つ以上ある場合は、アプリケーション マップ上で正しく表すために、クラウド ロール名を設定する必要があります。

Application Insights インストルメンテーションの使用時に、診断データが収集され、Microsoft に送信されます。 このデータは、Application Insights の実行と改善に役立ちます。 不要なデータ収集を無効にすることができます。 詳細については、「Azure Application Insights の Statsbeat」を参照してください。

構成オプション

applicationinsights.json ファイルでは、以下の設定を構成することができます。

  • クラウド ロール名
  • クラウド ロール インスタンス
  • サンプリング
  • JMX メトリック
  • カスタム ディメンション
  • テレメトリ プロセッサ (プレビュー)
  • 自動収集されるログ
  • 自動収集される Micrometer メトリック (Spring Boot アクチュエータ メトリックを含む)
  • Heartbeat
  • HTTP プロキシ
  • 自己診断

詳しくは、「構成オプション」をご覧ください。

自動インストルメンテーション

Java 3.x には、次自動のインストルメンテーションが含まれています。

自動収集される要求

  • JMS コンシューマー
  • Kafka コンシューマー
  • Netty/WebFlux
  • Quartz
  • Servlets
  • Spring スケジュール

自動収集される依存関係

自動収集される依存関係とダウンストリームへの分散トレースの伝達:

  • Apache HttpClient
  • Apache HttpAsyncClient
  • AsyncHttpClient
  • Google HttpClient
  • gRPC
  • java.net.HttpURLConnection
  • Java 11 HttpClient
  • JAX-RS クライアント
  • Jetty HttpClient
  • JMS
  • Kafka
  • Netty クライアント
  • OkHttp

自動収集される依存関係 (ダウンストリームへの分散トレースの伝達なし):

  • Cassandra
  • JDBC
  • MongoDB (非同期および同期)
  • Redis (Lettuce および Jedis)

自動収集されるログ

  • Log4j (MDC/スレッド コンテキストのプロパティを含む)
  • Logback (MDC のプロパティを含む)
  • JBoss ログ (MDC のプロパティを含む)
  • java.util.logging

自動収集されるメトリック

  • Spring Boot アクチュエータ メトリックを含むマイクロメーター
  • JMX メトリック

Azure SDK

次の Azure SDK によって出力されるテレメトリは、既定で自動収集されます。

テレメトリの変更

このセクションでは、テレメトリを変更する方法について説明します。

スパンの追加

独自のスパンを追加する最も簡単な方法は、OpenTelemetry の @WithSpan 注釈を使用することです。

スパンによって、Application Insights の requestsdependencies テーブルが入力されます。

注意

この機能は、3.2.0 以降でのみ利用できます。

  1. アプリケーションに opentelemetry-extension-annotations-1.16.0.jar を追加します:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-extension-annotations</artifactId>
      <version>1.16.0</version>
    </dependency>
    
  2. @WithSpan 注釈を使用して、メソッドが実行されるたびにスパンを出力します。

     import io.opentelemetry.extension.annotations.WithSpan;
    
     @WithSpan(value = "your span name")
     public void yourMethod() {
     }
    

既定では、スパンは、依存関係の種類 InProcを持つ依存関係テーブルになります。

メソッドが、自動インストルメンテーションによってまだキャプチャされていないバックグラウンド ジョブを表す場合は、属性 kind = SpanKind.SERVER@WithSpan 注釈に適用して、Application Insights の requests テーブルになるようにすることをお勧めします。

スパン イベントの追加

opentelemetry-api を使用して、Application Insights 内のトレース テーブルに値を設定するスパン イベントを作成できます。 addEvent() に渡された文字列は、トレース内の "メッセージ" フィールド に保存されます。

注意

この機能は、3.2.0 以降でのみ利用できます。

  1. アプリケーションに opentelemetry-api-1.6.0.jar を追加します:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. コードにスパン イベントを追加します。

     import io.opentelemetry.api.trace.Span;
    
     Span.current().addEvent("eventName");
    

スパン属性を追加する

opentelemetry-api を使用して、スパンに属性を追加することができます。 これらの属性には、テレメトリへのカスタム ビジネス ディメンションの追加を含めることができます。 また、属性を使用して、Application Insights のスキーマの省略可能なフィールド ([ユーザー ID] や [クライアント IP] など) を設定することもできます。

1 つ以上のスパン属性を追加すると、要求、依存関係、トレース、または例外テーブル内の customDimensions フィールドにデータが入力されます。

注意

この機能は、3.2.0 以降でのみ利用できます。

  1. アプリケーションに opentelemetry-api-1.6.0.jar を追加します:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. コードにカスタム ディメンションを追加します:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.common.AttributeKey;
    
     AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");
     Span.current().setAttribute(attributeKey, "myvalue1");
    

スパン状態の更新と例外の記録

opentelemetry-api を使用して、スパンの状態を更新したり、例外を記録したりできます。

注意

この機能は、3.2.0 以降でのみ利用できます。

  1. アプリケーションに opentelemetry-api-1.6.0.jar を追加します:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. 状態をエラーに設定し、コード内の例外を記録します。

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.trace.StatusCode;
    
     Span span = Span.current();
     span.setStatus(StatusCode.ERROR, "errorMessage");
     span.recordException(e);
    

ユーザー ID を設定する

要求、依存関係、または例外テーブルの [ユーザー ID] フィールドにデータを入力します。

重要

認証されたユーザー ID を設定する前に、該当するプライバシーに関する法律を調べてください。

注意

この機能は、3.2.0 以降でのみ利用できます。

  1. アプリケーションに opentelemetry-api-1.6.0.jar を追加します:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. コードに user_Id を設定します。

    import io.opentelemetry.api.trace.Span;
    
    Span.current().setAttribute("enduser.id", "myuser");
    

トレース ID またはスパン ID を取得する

opentelemetry-api を使用して、トレース ID またはスパン ID を取得することができます。 このアクションは、これらの識別子を既存のログ テレメトリに追加して、問題のデバッグや診断時の相関関係を改善するために行われる場合があります。

注意

この機能は、3.2.0 以降でのみ利用できます。

  1. アプリケーションに opentelemetry-api-1.6.0.jar を追加します:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. コードで要求のトレース ID とスパン ID を取得します。

    import io.opentelemetry.api.trace.Span;
    
    Span span = Span.current();
    String traceId = span.getSpanContext().getTraceId();
    String spanId = span.getSpanContext().getSpanId();
    

カスタムのテレメトリ

Application Insights Java 3.x での目標は、標準 API を使用してカスタム テレメトリを送信できるようにすることです。

現時点では、Micrometer、一般的なログ記録フレームワーク、および Application Insights Java 2.x SDK をサポートしています。 Application Insights Java 3.x を使用すると、これらの API を使用して送信されたテレメトリが自動的にキャプチャされ、自動収集されたテレメトリと関連付けられます。

サポートされているカスタム テレメトリ

次の表は、現在サポートされているカスタム テレメトリの種類を示しています。これを有効にすると、Java 3.x エージェントを補完することができます。 まとめ

  • カスタム メトリックは、マイクロメーターを通じてサポートされます。
  • カスタム例外とトレースは、ログ記録フレームワークを通じてサポートされます。
  • カスタム要求、依存関係、メトリック、および例外は、opentelemetry-api を通じてサポートされます。
  • カスタム テレメトリのすべての種類は、Application Insights Java 2.x SDK を通じてサポートされます。
カスタム テレメトリの種類 Micrometer Log4j、logback、JUL 2.x SDK opentelemetry-api
カスタム イベント はい
カスタム メトリック はい はい はい
依存関係 はい はい
例外 はい はい はい
ページ ビュー はい
Requests はい はい
トレース はい はい

現時点では、Application Insights 3.x を使用した SDK をリリースする予定はありません。

Application Insights Java 3.x では、Application Insights Java 2.x SDK に送信されるテレメトリを既にリッスンしています。 この機能は、既存の 2.x ユーザーのアップグレード ストーリーの重要な部分です。 また、すべてのカスタム テレメトリの種類が OpenTelemetry API 経由でサポートされるまで、カスタム テレメトリ サポートの重要なギャップを埋めます。

Micrometer を使用してカスタム メトリックを送信する

  1. アプリケーションに Micrometer を追加します。

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-core</artifactId>
      <version>1.6.1</version>
    </dependency>
    
  2. Micrometer のグローバル レジストリを使用して、メーターを作成します。

    static final Counter counter = Metrics.counter("test.counter");
    
  3. カウンターを使用してメトリックを記録します。

    counter.increment();
    
  4. メトリックは customMetrics テーブルに取り込まれます。このとき、タグは 列にキャプチャされます。 メトリックは、"ログベースのメトリック" メトリック名前空間のメトリックス エクスプローラーで表示することもできます。

    注意

    Application Insights Java では、Micrometer メトリック名内のすべての英数字以外の文字 (ダッシュを除く) がアンダースコアに置き換えられます。そのため、test.counter のメトリックは test_counter として表示されます。

お気に入りのログ記録フレームワークを使用してカスタム トレースと例外を送信する

Log4j、Logback、および java. util. ログは自動インストルメント化されます。 これらのログ記録フレームワークを使用して実行されるログは、トレースと例外テレメトリとして自動収集されます。

既定では、INFO レベル以上でログ記録が実行された場合にのみ、ログが収集されます。 このレベルを変更するには、構成オプションに関する記事を参照してください。

カスタム ディメンションをログにアタッチする場合は、Log4j 1.2 MDCLog4j 2 MDC、または Logback MDC を使用します。 Application Insights Java 3.x では、これらの MDC プロパティがトレースおよび例外テレメトリのカスタム ディメンションとして自動的にキャプチャされます。

2.x SDK を使用してカスタム テレメトリを送信する

  1. アプリケーションに applicationinsights-core-2.6.4.jar を追加します。 すべての 2.x バージョンは Application Insights Java 3.x でサポートされています。 選択肢がある場合は、最新バージョンを使用する価値があります。

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>applicationinsights-core</artifactId>
      <version>2.6.4</version>
    </dependency>
    
  2. TelemetryClient を作成します。

    static final TelemetryClient telemetryClient = new TelemetryClient();
    
  3. クライアントを使用してカスタム テレメトリを送信します。

    events
    telemetryClient.trackEvent("WinGame");
    
    メトリック
    telemetryClient.trackMetric("queueLength", 42.0);
    
    依存関係
    boolean success = false;
    long startTime = System.currentTimeMillis();
    try {
        success = dependency.call();
    } finally {
        long endTime = System.currentTimeMillis();
        RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
        telemetry.setSuccess(success);
        telemetry.setTimestamp(new Date(startTime));
        telemetry.setDuration(new Duration(endTime - startTime));
        telemetryClient.trackDependency(telemetry);
    }
    
    ログ
    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    
    例外
    try {
        ...
    } catch (Exception e) {
        telemetryClient.trackException(e);
    }
    

トラブルシューティング

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

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

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

リリース ノート

GitHub のリリース ノートを表示します。

サポート

サポートを受けるには:

OpenTelemetry のフィードバック

フィードバックを提供するには:

次のステップ