OpenTelemetry

此功能需要 Microsoft.Testing.Extensions.OpenTelemetry NuGet 套件。

此擴充整合了 OpenTelemetry 與 Microsoft。Testing.Platform （MTP），允許透過標準 OpenTelemetry SDK 進行測試，並發出追蹤與指標。

備註

此擴充功能自 2.1.0 版本起可在 MTP 中使用。

這很重要

從 MTP 2.4.0 開始，OpenTelemetry 擴充套件遵循 MTP 版本，其公開入口不再是實驗性。

Registration

備註

這個擴充功能不支援自動註冊。 你必須手動註冊，方法是關閉自動產生的入口點（<GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>），並在AddOpenTelemetryProvider 方法中呼叫 Main。

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

這個方法只有在你設定匯出器或通過設定回調時才會新增儀器，所以當某些環境不匯出遙測時，你可以將註冊留在應用程式中。

API

AddOpenTelemetryProvider

註冊 OpenTelemetry 供應商於 ITestApplicationBuilder。 接受兩種可選回撥：

  • withTracing：設定 TracerProviderBuilder 來進行分散式追蹤。
  • withMetrics：配置 MeterProviderBuilder 用於指標收集。

AddTestingPlatformInstrumentation

請使用 TracerProviderBuilder 或 MeterProviderBuilder 訂閱內建的 Microsoft.Testing.Platform 活動來源與計量器。

AddTestingPlatformResource

呼叫 ResourceBuilder 以新增測試組件、主機、作業系統及執行階段屬性。 該偵測器同時識別 GitHub Actions、Azure Pipelines、GitLab CI 及 Jenkins 的 CI 提供者、管線、分支及提交資訊。

AddOpenTelemetryProviderFromEnvironment

從標準 OpenTelemetry 環境變數註冊追蹤、指標、資源偵測及 OTLP 匯出器。 OTEL_SDK_DISABLED=true 關閉整合。 設定 OTEL_TRACES_EXPORTER、 OTEL_METRICS_EXPORTER，或 OTEL_EXPORTER_OTLP_ENDPOINT 啟用匯出。

活動源與計量表

擴充套件會發送以下遙測數據：

  • 活動來源： Microsoft.Testing.Platform
  • 計量器： Microsoft.Testing.Platform

語意慣例

MTP 會在已有慣例的情況下，發出標準的 OpenTelemetry 測試和程式碼屬性，包括 test.case.name、test.case.result.status、test.suite.name、error.type、code.function.name、code.file.path、code.line.number 和 code.stacktrace。 測試失敗時，將 span 狀態設為 Error，並新增 exception 事件。

MTP 透過額外的結果狀態（skipped、error、cancelledtimeout、 unknown和 ）來擴充慣例，並針對 OpenTelemetry 未定義的概念設置測試屬性。 為了保留現有儀表板，舊有屬性與儀器名稱預設仍啟用。

當啟動程序提供 TRACEPARENT 和 TRACESTATE時，MTP 會將測試執行置於該追蹤線下方，而非開始無關的根追蹤。

輸出度量

樂器 類型 單位 Description
test.case.duration 直方圖 s 測試持續時間，依結果狀態和套件分組。
test.case.result.count 計數器 {test} 已完成的測試，依結果狀態和測試套件分組。
test.case.active UpDownCounter {test} 目前正在進行的測試。
test.run.duration 直方圖 s 執行時間，依結果狀態和退出代碼分組。
test.case.retry.count 計數器 {test} 由重試擴充功能排定再次嘗試的測試。

環境設定

環境變數 預設值 Description
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 未設定 將其設為 true，即可停用 OpenTelemetry SDK。
OTEL_SERVICE_NAME 未設定 覆蓋服務名稱。
OTEL_EXPORTER_OTLP_ENDPOINT 未設定 設定 OTLP 端點。
OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER 未設定 選擇追蹤器與公制匯出器。
  • Last updated on