.NET、Node.js、Python、Java アプリケーション用の Azure Monitor OpenTelemetry を有効にする

  • [アーティクル]

この記事では、OpenTelemetry ベースのデータ収集を有効にして、Azure Monitor Application Insights 内のエクスペリエンスを強化するように構成する方法について説明します。 「Azure Monitor OpenTelemetry Distro」のインストール方法を説明します。 OpenTelemetry の概念の詳細については、「OpenTelemetry の概要」または「OpenTelemetry FAQ」をご覧ください。

OpenTelemetry のリリースの状態

OpenTelemetry オファリングは、.NET、Node.js、Python、Java アプリケーションで使用できます。

Language リリースの状態
Java ✅1
.NET ⚠️ 2
Node.js ⚠️ 2
Python ⚠️ 2

脚注

注意

機能別のリリースの状態については、「よく寄せられる質問」を参照してください。

作業の開始

このセクションの手順に従い、OpenTelemetry を使用してアプリケーションをインストルメント化します。

前提条件

  • 正式にサポートされているバージョンの .NET Core または .NET Framework (少なくとも .NET Framework 4.6.2) を使用するアプリケーション

注意事項

OpenTelemetry コミュニティ パッケージと並行して実行されている Azure Monitor OpenTelemetry Distro はテストされていません。 Distro をインストールする前に、OpenTelemetry 関連のパッケージをアンインストールすることをお勧めします。

クライアント ライブラリをインストールする

最新の Azure.Monitor.OpenTelemetry.AspNetCore NuGet パッケージをインストールします。

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.AspNetCore

Azure Monitor Application Insights を有効にする

Azure Monitor Application Insights を有効にするには、アプリケーションに軽微な変更を加え、"接続文字列" を設定します。 接続文字列は、Distro が収集するテレメトリを送信する場所をアプリケーションに通知します。これはユーザーに固有です。

アプリケーションを変更する

アプリケーション スタートアップに UseAzureMonitor() を追加します。 .NET のバージョンに応じて、これは startup.cs または program.cs クラスのいずれかになります。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

Application Insights リソースから接続文字列をコピーします

ヒント

まだお持ちでない場合、 Application Insights リソースを作成する絶好のタイミングです。

一意の接続文字列をコピーするには:

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

  1. Application Insights リソースの [概要] ペインにアクセスしてください。
  2. 接続文字列を見つけます。
  3. 接続文字列をポイントし、[クリップボードにコピー] アイコンを選択します。

環境に接続文字列を貼り付ける

接続文字列を貼り付けるには、次のオプションから選択します。

A. 環境変数を使用して設定する (推奨)

次のコマンドの <Your Connection String> を、独自の一意の接続文字列に置き換えます。

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

B. 構成ファイルを使用して設定する - Java のみ (推奨)

次のコンテンツを使って、applicationinsights.json という名前の構成ファイルを作成し、applicationinsights-agent-3.4.13.jar と同じディレクトリに配置します。

{
  "connectionString": "<Your Connection String>"
}

上記の JSON の <Your Connection String> を、独自の一意の接続文字列に置き換えます。

C. コードを使用して設定 - ASP.NET Core、Node.js、Python のみ (非推奨)

コードを使用した接続文字列の設定の例については、「接続文字列の構成」をご覧ください。

Note

接続文字列を複数の場所に設定する場合は、次の優先順位に従います。

  1. コード
  2. 環境変数
  3. 構成ファイル

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

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

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

これで終了です。 アプリケーションは現在、Application Insights によって監視されています。 以下にあるその他すべてはオプションであり、さらにカスタマイズすることができます。

動作していませんか? ASP.NET Core、Java、Node.js、または Python のトラブルシューティング ページを確認してください。

重要

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

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

自動データ収集

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

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

Requests

依存関係

ログの記録

  • ILogger

ILogger の詳細については、「C# および .NET でのログ記録」と「コード例」を参照してください。

脚注

  • 1: ハンドルされない例外の自動レポートをサポートします
  • 2: OpenTelemetry メトリクスをサポートする
  • 3: デフォルトでは、ログは INFO レベル以上でのみ収集されます。 この設定を変更するには、「構成オプション」に関する記事を参照してください。
  • 4: デフォルトでは、ログは WARNING レベル以上でのみ収集されます。

Note

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

ヒント

現在、OpenTelemetry ベースのオファリングは、すべての OpenTelemetry メトリックをカスタム メトリックとパフォーマンス カウンターとしてメトリックス エクスプローラーに出力します。 .NET、Node.js、Python の場合、測定名として設定したものはすべてメトリックの名前空間になります。

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

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

Note

コミュニティインストルメンテーション ライブラリの品質はサポートされておらず、保証できません。 コミュニティインストルメンテーション ライブラリを提案する場合は、 フィードバック コミュニティにアイデアを投稿またはアップ投票します。

注意事項

インストルメンテーション ライブラリの一部は、試験的な OpenTelemetry のセマンティック仕様に基づいています。 追加すると、将来の破壊的変更に対して脆弱になる可能性があります。

コミュニティ ライブラリを追加するには、 ConfigureOpenTelemetryMeterProvider メソッドまたは ConfigureOpenTelemetryTraceProvider メソッドを使用します。

次の例では、追加のメトリックを収集するためにランタイム インストルメンテーションを追加する方法を示します。

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

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

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

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

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

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

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

Note

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

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

Note

カスタム メトリックは、Azure Monitor Application Insights でプレビュー段階にあります。 ディメンションのないカスタム メトリックは、既定で使用できます。 ディメンションを表示してアラートを表示するには、オプトインする必要があります。

インストルメンテーション ライブラリによって提供されるメトリックを超えた、より多くのメトリックを収集することを検討してください。

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 インストルメントはアプリケーションのパフォーマンスに与える影響が少なくなります。

ヒストグラム例

アプリケーションの起動では、名前による測定をサブスクライブする必要があります。

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

Meter は 、同じ名前を使用して初期化する必要があります。

var meter = new Meter("OTel.AzureMonitor.Demo");
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

var rand = new Random();
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

カウンターの例

アプリケーションの起動では、名前による測定をサブスクライブする必要があります。

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

Meter は 、同じ名前を使用して初期化する必要があります。

var meter = new Meter("OTel.AzureMonitor.Demo");
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

ゲージの例

アプリケーションの起動では、名前による測定をサブスクライブする必要があります。

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

Meter は 、同じ名前を使用して初期化する必要があります。

var process = Process.GetCurrentProcess();

var meter = new Meter("OTel.AzureMonitor.Demo");
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    foreach (ProcessThread thread in process.Threads)
    {
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

カスタム例外の追加

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

  • アクティビティを使用して例外をログに記録するには: 
    using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    try
    {
        throw new Exception("Test exception");
    }
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}
  • ILogger を使用して例外をログに記録するには: 
    var logger = loggerFactory.CreateLogger(logCategoryName);

try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

カスタム スパンを追加する

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

Note

System.Diagnostics 名前空間の Activity および ActivitySource クラスは、それぞれ Span と Tracer の OpenTelemetry での概念を表しています。 TracerProvider を使用する代わりに、コンストラクターを使用して ActivitySource を直接作成します。 各 ActivitySource クラスは、AddSource() を使用して TracerProvider に明示的に接続する必要があります。 これは、OpenTelemetry トレース API の一部が .NET ランタイムに直接組み込まれているためです。 詳細については、「Introduction to OpenTelemetry .NET Tracing API」 (OpenTelemetry .NET Tracing API の概要) を参照してください。

internal static readonly ActivitySource activitySource = new("ActivitySourceName");

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.MapGet("/", () =>
{
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    return $"Hello World!";
});

app.Run();

既定では、アクティビティは依存関係の種類が InProc の Application Insights dependencies テーブルに配置されます。

インストルメンテーション ライブラリによってキャプチャされないバックグラウンド ジョブを表すコードの場合は、Application Insights の requests テーブルに確実に表示されるように、StartActivity メソッドで ActivityKind.Server を設定することをお勧めします。

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

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

これは、.NET では使用できません。

テレメトリの変更

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

スパン属性を追加する

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

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

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

スパン属性を追加するには、次の 2 つの方法のいずれかを使用します。

ヒント

インストルメンテーション ライブラリで提供されるオプションを使用できる利点は、コンテキスト全体を使用できることです。 その結果、ユーザーは、追加する属性を選択したり、フィルター処理したりできます。 たとえば、HttpClient インストルメンテーション ライブラリの enrich オプションを使用すると、ユーザーは HttpRequestMessage や HttpResponseMessage 自体にアクセスできます。 そこからは何でも選択して、属性として保存できます。

  1. 多くのインストルメンテーション ライブラリには、強化オプションが用意されています。 ガイダンスについては、個々のインストルメンテーション ライブラリの Readme ファイルを参照してください。

  2. カスタム プロセッサの使用:

ヒント

ここに示すプロセッサを、Azure Monitor を追加する前に追加します。

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

次のコードを使用して、プロジェクトに ActivityEnrichingProcessor.cs を追加します。

public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

ユーザー IP を設定する

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

カスタム プロパティの追加の例を使用しますが、次の ActivityEnrichingProcessor.cs のコード行を置き換えます。

// only applicable in case of activity.Kind == Server
activity.SetTag("http.client_ip", "<IP Address>");

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

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

重要

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

[カスタム プロパティの例] の追加を使用します。

activity?.SetTag("enduser.id", "<User Id>");

ログ属性を追加する

OpenTelemetry は .NET の ILogger を使用します。 カスタム ディメンションをログに添付するには、 [メッセージ テンプレート] を使用します。

テレメトリのフィルター処理

テレメトリがアプリケーションから離れる前に、次の方法を使用してテレメトリをフィルター処理できます。

  1. 多くのインストルメンテーション ライブラリには、フィルター オプションが用意されています。 ガイダンスについては、個々のインストルメンテーション ライブラリの Readme ファイルを参照してください。

  2. カスタム プロセッサの使用:

    ヒント

    ここに示すプロセッサを、Azure Monitor を追加する前に追加します。

    var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityFilteringProcessor()));
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

    次のコードを使用して、プロジェクトに ActivityFilteringProcessor.cs を追加します。

    public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
    public override void OnStart(Activity activity)
    {
        // prevents all exporters from exporting internal activities
        if (activity.Kind == ActivityKind.Internal)
        {
            activity.IsAllDataRequested = false;
        }
    }
}

  3. AddSource("ActivitySourceName") を使用して特定のソースが明示的に追加されていない場合、そのソースを使用して作成されたアクティビティはエクスポートされません。

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

トレース ID またはスパン ID の取得をお勧めする場合があります。 Application Insights 以外の宛先にログを送信する場合は、トレース ID またはスパン ID を追加することを検討してください。 これにより、問題のデバッグと診断時の相関関係が向上します。

Note

System.Diagnostics 名前空間の Activity および ActivitySource クラスは、それぞれ Span と Tracer の OpenTelemetry での概念を表しています。 これは、OpenTelemetry トレース API の一部が .NET ランタイムに直接組み込まれているためです。 詳細については、「Introduction to OpenTelemetry .NET Tracing API」 (OpenTelemetry .NET Tracing API の概要) を参照してください。

Activity activity = Activity.Current;
string traceId = activity?.TraceId.ToHexString();
string spanId = activity?.SpanId.ToHexString();

サポート

OpenTelemetry のフィードバック

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

次のステップ