英語で読む

次の方法で共有


.NET、Java、Node.js、Python アプリケーション用の Azure Monitor OpenTelemetry を追加および変更する

この記事では、Azure Monitor Application Insights を使用してアプリケーションの OpenTelemetry を追加および変更する方法に関するガイダンスを提供します。

OpenTelemetry の概念の詳細については、OpenTelemetry の概要または OpenTelemetry に関する FAQ に関する記事を参照してください。

自動データ収集

ディストリビューションは、OpenTelemetry のインストルメンテーション ライブラリをバンドルすることでデータを自動的に収集します。

インストルメンテーション ライブラリを含む

要求数

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

注意

サーブレットおよび Netty 自動インストルメンテーションは、Java EE、Jakarta EE、Spring Boot、Quarkus、Micronaut などの Java HTTP サービスの大部分をカバーしています。

依存関係 (とダウンストリームへの分散トレースの伝達)

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

依存関係 (ダウンストリームへの分散トレースの伝達なし)

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

メトリック

  • Micrometer メトリック (Spring Boot アクチュエータ メトリックを含む)
  • JMX メトリック

ログ

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

既定の収集

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

[//]: # "Azure Cosmos DB 4.22.0+ due to https://github.com/Azure/azure-sdk-for-java/pull/25571"
[//]: # "the remaining above names and links scraped from https://azure.github.io/azure-sdk/releases/latest/java.html"
[//]: # "and version synched manually against the oldest version in maven central built on azure-core 1.14.0"
[//]: # ""
[//]: # "var table = document.querySelector('#tg-sb-content > div > table')"
[//]: # "var str = ''"
[//]: # "for (var i = 1, row; row = table.rows[i]; i++) {"
[//]: # "  var name = row.cells[0].getElementsByTagName('div')[0].textContent.trim()"
[//]: # "  var stableRow = row.cells[1]"
[//]: # "  var versionBadge = stableRow.querySelector('.badge')"
[//]: # "  if (!versionBadge) {"
[//]: # "    continue"
[//]: # "  }"
[//]: # "  var version = versionBadge.textContent.trim()"
[//]: # "  var link = stableRow.querySelectorAll('a')[2].href"
[//]: # "  str += '* [' + name + '](' + link + ') ' + version + '\n'"
[//]: # "}"
[//]: # "console.log(str)"

脚注

  • ¹: "ハンドルされない/キャッチされない" 例外の自動レポートをサポートします
  • ²: OpenTelemetry メトリックをサポートします
  • ³: 既定では、ログは INFO レベル以上でのみ収集されます。 この設定を変更するには、「構成オプション」に関する記事を参照してください。
  • ⁴: 既定では、ログは警告レベル以上でログが実行された場合にのみ収集されます。

注意

Azure Monitor OpenTelemetry Distros には、 Application Insights 標準メトリックを自動的に出力するためのカスタム マッピングとロジックが含まれています。

ヒント

インストルメンテーション ライブラリから自動的に収集されたか、またはカスタム コーディングから手動で収集されたかに関係なく、すべての OpenTelemetry メトリックは、現在、課金目的で Application Insights の "カスタム メトリック" と見なされます。 詳細情報。

コミュニティ インストルメンテーション ライブラリを追加する

OpenTelemetry コミュニティからインストルメンテーション ライブラリを含めると、より多くのデータを自動的に収集できます。

注意事項

コミュニティ インストルメンテーション ライブラリの品質は、サポートおよび保証していません。 ディストリビューションについてのご提案は、フィードバック コミュニティで投稿するか賛成に投票してください。 一部は実験的な OpenTelemetry 仕様に基づいており、今後、破壊的変更が生じる可能性があることにご注意ください。

コミュニティ インストルメンテーション ライブラリを使用して Java Distro を拡張することはできません。 別のインストルメンテーション ライブラリを含めるように要求するには、GitHub ページで issue をオープンしてください。 GitHub ページへのリンクについては、[次の手順] を参照してください。

カスタム テレメトリを収集する

このセクションでは、アプリケーションからカスタム テレメトリを収集する方法について説明します。

言語とシグナルの種類によって、次のようにさまざまなカスタム テレメトリの収集方法があります。

  • OpenTelemetry API
  • 言語固有のログとメトリックのライブラリ
  • Application Insights Classic API

次の表は、現在サポートされているカスタム テレメトリの種類をまとめたものです。

言語 [カスタム イベント] カスタム メトリック 依存関係 例外 ページ ビュー Requests トレース
ASP.NET Core
   OpenTelemetry API はい イエス イエス はい
   ILogger API はい
   AI Classic API
Java
   OpenTelemetry API はい イエス イエス はい
   Logback、Log4j、JUL はい はい
   Micrometer メトリック はい
   AI Classic API はい イエス イエス イエス イエス イエス はい
Node.js
   OpenTelemetry API はい イエス イエス はい
Python
   OpenTelemetry API はい イエス イエス はい
   Python ログ モジュール はい
   イベント拡張機能 はい はい

注意

Application Insights Java 3.x は、Application Insights Classic API に送信されたテレメトリをリッスンします。 同様に、Application Insights Node.js 3.x は、Application Insights Classic API で作成されたイベントを収集します。 そのため、アップグレードは容易であり、すべてのカスタム テレメトリの種類が OpenTelemetry API 経由でサポートされるまで、カスタム テレメトリ サポートのギャップを埋めることができます。

カスタム メトリックを追加する

このコンテキストで、カスタム メトリックという用語は、OpenTelemetry インストルメンテーション ライブラリで自動的に収集されるメトリック以外の追加のメトリックを収集するために、コードを手動でインストルメント化することを指します。

OpenTelemetry API には、さまざまなメトリック シナリオに対応する 6 つのメトリック "インストルメント" が用意されており、メトリックス エクスプローラーでメトリックを視覚化する場合は、適切な "集計の種類" を選択する必要があります。 この要件は、OpenTelemetry Metric API を使用してメトリックを送信する場合と、インストルメンテーション ライブラリを使用する場合に当てはまります。

次の表は、OpenTelemetry メトリック インストルメントごとに推奨される 集計の種類 を示しています。

OpenTelemetry インストルメント Azure Monitor の集計の種類
カウンタ SUM
非同期カウンター SUM
ヒストグラム Min、Max、Average、Sum、Count
非同期ゲージ Average
UpDownCounter SUM
非同期 UpDownCounter SUM

注意事項

通常、表に表示される以外の集計の種類は意味がありません。

OpenTelemetry の仕様」では、インストルメントについて説明し、それぞれを使用する場合の例を示します。

ヒント

ヒストグラムは最も汎用性が高く、Application Insights GetMetric Classic API と最も近いものです。 Azure Monitor では現在、ヒストグラム インストルメントがサポートされている 5 種類の集計にフラット化されており、パーセンタイルのサポートが進行中です。 汎用性は低くなりますが、他の OpenTelemetry インストルメントはアプリケーションのパフォーマンスに与える影響が少なくなります。

ヒストグラム例

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.metrics.DoubleHistogram;
import io.opentelemetry.api.metrics.Meter;

public class Program {

    public static void main(String[] args) {
        Meter meter = GlobalOpenTelemetry.getMeter("OTEL.AzureMonitor.Demo");
        DoubleHistogram histogram = meter.histogramBuilder("histogram").build();
        histogram.record(1.0);
        histogram.record(100.0);
        histogram.record(30.0);
    }
}

カウンターの例

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.Meter;

public class Program {

    public static void main(String[] args) {
        Meter meter = GlobalOpenTelemetry.getMeter("OTEL.AzureMonitor.Demo");

        LongCounter myFruitCounter = meter
                .counterBuilder("MyFruitCounter")
                .build();

        myFruitCounter.add(1, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "red"));
        myFruitCounter.add(2, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));
        myFruitCounter.add(1, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));
        myFruitCounter.add(2, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "green"));
        myFruitCounter.add(5, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "red"));
        myFruitCounter.add(4, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));
    }
}

ゲージの例

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.metrics.Meter;

public class Program {

    public static void main(String[] args) {
        Meter meter = GlobalOpenTelemetry.getMeter("OTEL.AzureMonitor.Demo");

        meter.gaugeBuilder("gauge")
                .buildWithCallback(
                        observableMeasurement -> {
                            double randomNumber = Math.floor(Math.random() * 100);
                            observableMeasurement.record(randomNumber, Attributes.of(AttributeKey.stringKey("testKey"), "testValue"));
                        });
    }
}

カスタム例外の追加

インストルメンテーション ライブラリを選ぶと、Application Insights の例外が自動的に報告されます。 ただし、インストルメンテーション ライブラリで報告される以外の例外を手動で報告することもできます。 たとえば、コードによってキャッチされた例外は、通常は報告されません。 エラー セクションやエンドツーエンドのトランザクション ビューなど、関連するエクスペリエンスで注目を集めるために、それらを報告することができます。

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

  1. opentelemetry-api-1.0.0.jar (以降) をアプリケーションに追加します。

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

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

カスタム スパンの追加

2 つのシナリオでカスタム スパンを追加することもできます。 最初に、インストルメンテーション ライブラリによってまだ収集されていない依存関係要求がある場合です。 2 つ目は、アプリケーション プロセスをエンドツーエンドのトランザクション ビューのスパンとしてモデル化する場合です。

  • OpenTelemetry の注釈を使用する

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

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

    1. opentelemetry-instrumentation-annotations-1.32.0.jar (以降) をアプリケーションに追加します。

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

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

    既定では、スパンは最終的に依存関係の種類 InProcdependencies テーブルに入ります。

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

  • OpenTelemetry API を使用する

    前述の OpenTelemetry @WithSpan 注釈がニーズを満たさない場合は、OpenTelemetry API を使用してスパンを追加できます。

    1. opentelemetry-api-1.0.0.jar (以降) をアプリケーションに追加します。

      <dependency>
          <groupId>io.opentelemetry</groupId>
          <artifactId>opentelemetry-api</artifactId>
          <version>1.0.0</version>
      </dependency>
      
    2. GlobalOpenTelemetry クラスを使用して Tracer を作成します。

      import io.opentelemetry.api.GlobalOpenTelemetry;
      import io.opentelemetry.api.trace.Tracer;
      
      static final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example");
      
    3. スパンを作成し、最新の状態にしてから終了します。

      Span span = tracer.spanBuilder("my first span").startSpan();
      try (Scope ignored = span.makeCurrent()) {
          // do stuff within the context of this 
      } catch (Throwable t) {
          span.recordException(t);
      } finally {
          span.end();
      }
      

Application Insights Classic API を使ってカスタム テレメトリを送信する

可能な限り OpenTelemetry API を使用することをお勧めしますが、Application Insights の Classic API を使用することが必要なシナリオもあります。

  1. アプリケーションに applicationinsights-core を追加します:

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>applicationinsights-core</artifactId>
      <version>3.4.18</version>
    </dependency>
    
  2. TelemetryClient インスタンスを作成します。

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

    イベント

    telemetryClient.trackEvent("WinGame");
    

    ログ

    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    

    メトリック

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

    例外

    try {
        ...
    } catch (Exception e) {
        telemetryClient.trackException(e);
    }
    
    
    

テレメトリの変更

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

スパン属性を追加する

これらの属性には、テレメトリへのカスタム プロパティの追加が含まれる可能性があります。 また、属性を使用して、Application Insights スキーマに [クライアント IP] などのオプション フィールドを設定することもできます。

スパンにカスタム プロパティを追加する

スパンに追加した属性は、カスタム プロパティとしてエクスポートされます。 これらは、要求、依存関係、トレース、または例外テーブルの customDimensions フィールドに設定されます。

opentelemetry-api を使用して、スパンに属性を追加することができます。

1 つ以上のスパン属性を追加すると、requestsdependenciestraces、または exceptions テーブル内の customDimensions フィールドにデータが入力されます。

  1. opentelemetry-api-1.0.0.jar (以降) をアプリケーションに追加します。

    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
        <version>1.0.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");
    

ユーザー IP を設定する

スパンに属性を設定することで、要求の client_IP フィールドにデータを入力できます。 Application Insights では、この IP アドレスを使用してユーザーの位置属性を生成した後、既定でそれを破棄します

このフィールドは Java によって自動的に設定されます。

ユーザー ID または認証されたユーザー ID を設定する

次のガイダンスを参考にして、要求の user_Id または user_AuthenticatedId フィールドを設定できます。 ユーザー ID は匿名のユーザー識別子です。 認証されたユーザー ID は既知のユーザー識別子です。

重要

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

requestsdependencies、または exceptions テーブルの user ID フィールドに入力します。

  1. opentelemetry-api-1.0.0.jar (以降) をアプリケーションに追加します。

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

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

ログ属性の追加

Logback、Log4j、および java.util.logging は自動的にインストルメント化されます。 カスタム ディメンションのログへのアタッチは、次の方法で実行できます。

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

次の手順を使って、現在アクティブなスパンの Trace IDSpan ID を取得できます。

opentelemetry-api を使用して、トレース ID またはスパン ID を取得することができます。

  1. opentelemetry-api-1.0.0.jar (以降) をアプリケーションに追加します。

    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
        <version>1.0.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();
    

次のステップ