OpenTelemetry

この機能には、 Microsoft.Testing.Extensions.OpenTelemetry NuGet パッケージが必要です。

この拡張機能は、OpenTelemetry をMicrosoftと統合します。Testing.Platform (MTP) を使用すると、テスト実行で標準の OpenTelemetry SDK を介してトレースとメトリックを出力できます。

注

この拡張機能は、バージョン 2.1.0 以降の MTP で使用できます。

Important

MTP 2.4.0 以降、OpenTelemetry 拡張機能は MTP リリース バージョンに従い、パブリック エントリ ポイントは試験的ではなくなりました。

プロバイダーの所有権を選択する

MTP またはアプリケーションが OpenTelemetry プロバイダーを所有しているかどうかを選択します。

MTP 所有のプロバイダーを使用する

自動生成されたエントリ ポイント (<GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>) を無効にし、Main メソッドでAddOpenTelemetryProviderを呼び出します。

var builder = await TestApplication.CreateBuilderAsync(args);

builder.AddOpenTelemetryProvider(
    withTracing: tracing => tracing
        .AddTestingPlatformInstrumentation()
        .AddConsoleExporter(),
    withMetrics: metrics => metrics
        .AddTestingPlatformInstrumentation()
        .AddConsoleExporter()
);

using var app = await builder.BuildAsync();
return await app.RunAsync();

標準 OTEL_* 環境変数からインストルメンテーション、リソース属性、および OTLP エクスポーターを構成するには、次を呼び出します。

builder.AddOpenTelemetryProviderFromEnvironment();

このメソッドは、エクスポーターを構成するか、構成コールバックを渡す場合にのみインストルメンテーションを追加するため、一部の環境でテレメトリをエクスポートしない場合にアプリケーションに登録を残すことができます。

アプリケーション所有のプロバイダーを使用する

MTP 2.5 プレビュー以降では、アプリケーションが既に Aspire ServiceDefaults、Microsoft.Extensions.Hosting、または別のコンポジション ルートを介して OpenTelemetry を構成している場合に、AddTestingPlatformDiagnosticsを呼び出します。 このメソッドは、TracerProviderやMeterProviderを作成、フラッシュ、または破棄することなく、Microsoft.Testing.Platformアクティビティのソースとメーターをアクティブ化します。

トレースビルダーとメトリックビルダーで AddTestingPlatformInstrumentation を使用して、アプリケーション所有のプロバイダーをサブスクライブします。 アプリケーションは、プロバイダー、エクスポーター、リソース ID、破棄の所有権を保持します。

MSBuild で生成されたホストされたエントリ ポイントの場合は、 Microsoft.Testing.Extensions.Hostingを参照し、 TestingPlatformHostFactory をホスト ファクトリ メソッドに設定し、次の値を設定します。

<TestingPlatformOpenTelemetryMode>HostOwned</TestingPlatformOpenTelemetryMode>

HostOwned は AddTestingPlatformDiagnosticsのみを呼び出します。プロバイダーを作成したり、ホストのリソース ID を置き換えたりすることはありません。 ホストのライフサイクルとファクトリの要件については、 ホストの統合に関するページを参照してください。

API

AddTestingPlatformDiagnostics

プロバイダーの所有権を MTP に移管することなく、アプリケーションが所有するリスナーまたは OpenTelemetry プロバイダーに対して、MTP のアクティビティ ソースとメーターを有効にします。

AddOpenTelemetryProvider

ITestApplicationBuilderに OpenTelemetry プロバイダーを登録します。 次に示す2つの省略可能なコールバックを受け付けます。

  • withTracing: 分散トレースの TracerProviderBuilder を構成します。
  • withMetrics: メトリック収集の MeterProviderBuilder を構成します。

AddTestingPlatformInstrumentation

TracerProviderBuilderまたはMeterProviderBuilderを呼び出して、組み込みのMicrosoft.Testing.Platformアクティビティのソースとメーターをサブスクライブします。

AddTestingPlatformResource

ResourceBuilderを呼び出して、テスト アセンブリ、ホスト、オペレーティング システム、およびランタイム属性を追加します。 また、この検出機能は、GitHub Actions、Azure Pipelines、GitLab CI、Jenkins の CI プロバイダー、パイプライン、ブランチ、コミット情報も識別します。

特化したリソースヘルパー

アプリケーション所有のプロバイダーの場合は、AddTestingPlatformTestResource を呼び出してテスト固有の識別情報を追加し、AddTestingPlatformCIResource を呼び出して CI とソース管理の来歴を追加します。 これらの優先ヘルパーは、アプリケーション所有の service.*、 host.*、 os.*、または process.* 属性を置き換えることはありません。

AddOpenTelemetryProviderFromEnvironment

標準の OpenTelemetry 環境変数からトレース、メトリック、リソース検出、OTLP エクスポーターを登録します。 OTEL_SDK_DISABLED=true は統合を無効にします。 エクスポートをアクティブ化するために、 OTEL_TRACES_EXPORTER、 OTEL_METRICS_EXPORTER、または OTEL_EXPORTER_OTLP_ENDPOINT を構成します。

アクティビティソースとメーター

拡張機能は、次の下でテレメトリを出力します。

  • アクティビティ ソース: Microsoft.Testing.Platform
  • メーター： Microsoft.Testing.Platform

セマンティック規則

MTP は、 test.case.name、 test.case.result.status、 test.suite.name、 code.function.name、 code.file.path、 code.line.number、 code.stacktrace、 error.typeなど、規則が存在する標準の OpenTelemetry テストとコード属性を出力します。 失敗したテストでは、スパンの状態が Error に設定され、 exception イベントが追加されます。

MTP は、追加の結果状態 (skipped、 error、 timeout、 cancelled、 unknown) で規則を拡張し、OpenTelemetry で定義されていない概念の属性をテストします。 既存のダッシュボードを保持するために、レガシ属性とインストルメント名は既定で有効なままになります。

起動プロセスで TRACEPARENT と TRACESTATEが提供されると、MTP は、関連のないルート トレースを開始するのではなく、そのトレースの下にテスト実行を配置します。

MSTest の実行範囲

MSTest 4.5 および MTP 2.5 プレビュー以降、ネイティブ MSTest の実行では、テストの実行ごとに 1 つの正規の MTP 所有アクティビティが使用されます。 MSTest は、テスト コンストラクター、初期化、テスト メソッド、クリーンアップ、およびカスタム TestMethodAttribute コードを実行している間、アクティビティを最新の状態にします。 そのため、 HttpClient、SQL、Entity Framework、WCF、およびカスタム アクティビティが自動的にインストルメント化され、テスト アクティビティの子になります。

MTP は、最終的な結果、タイミング、出力、成果物を同じアクティビティに追加し、MSTest によって記録された実行終了時刻に停止します。 この動作により、フレームワークと結果のスパンの重複が回避され、非同期の結果処理によってテスト期間が増えるのを防ぐことができます。

正規実行 API を使用しないテスト フレームワークは互換性トポロジを保持します。フレームワーク実行アクティビティと MTP 結果アクティビティは兄弟のままであり、結果アクティビティは、フレームワークが進行中の更新プログラムを発行したときに現在のアクティビティにリンクします。

出力されるメトリック

楽器 タイプ 単位 説明
test.case.duration ヒストグラム s 結果の状態とスイート別にグループ化されたテスト期間。
test.case.result.count Counter {test} 結果の状態とスイート別にグループ化された、完了したテスト。
test.case.active アップダウンカウンター {test} 現在実行中のテスト。
test.run.duration ヒストグラム s 実行時間。結果の状態と終了コードでグループ化されます。
test.case.retry.count Counter {test} 再試行拡張機能によって、テストの再実行がスケジュールされました。

環境構成

環境変数 デフォルト 説明
TRACEPARENT、TRACESTATE 未設定 親ランの W3C トレースコンテキスト。
TESTINGPLATFORM_OTEL_CAPTURE_TEST_OUTPUT 1 キャプチャされた標準出力とエラーをテスト スパンにアタッチします。 出力にシークレットが含まれる可能性がある場合に 0 に設定します。
TESTINGPLATFORM_OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT 8192 文字列属性に保持される最大文字数を設定します。
TESTINGPLATFORM_OTEL_EMIT_LEGACY_ATTRIBUTES 1 セマンティック規約名とあわせて、レガシー属性名およびレガシーインストルメント名を出力します。
OTEL_SDK_DISABLED 未設定 OpenTelemetry SDK を無効にするには、 true に設定します。
OTEL_SERVICE_NAME 未設定 サービス名をオーバーライドします。
OTEL_EXPORTER_OTLP_ENDPOINT 未設定 OTLP エンドポイントを設定します。
OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER 未設定 トレースおよびメトリック エクスポーターを選択します。
  • 最終更新: