OpenTelemetry

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

此扩展将 OpenTelemetry 与 Microsoft.Testing.Platform（MTP）集成，允许测试运行通过标准 OpenTelemetry SDK 发出跟踪和指标。

注释

从版本 2.1.0 开始，MTP 中提供了此扩展。

重要

从 MTP 2.4.0 开始，OpenTelemetry 扩展遵循 MTP 版本，其公共入口点不再具有实验性。

选择提供方归属

选择由 MTP 还是由您的应用程序负责管理 OpenTelemetry 提供程序。

使用 MTP 拥有的提供程序

禁用自动生成的入口点（<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();

该方法仅在您配置导出器或传入配置回调时才会添加检测功能，因此即使某些环境不导出遥测数据，您也可以在应用程序中保留这段注册代码。

使用应用程序拥有的提供程序

从 MTP 2.5 预览版开始，当应用程序已通过 Aspire ServiceDefaults、AddTestingPlatformDiagnostics 或其他组合根配置 OpenTelemetry 时，请调用 Microsoft.Extensions.Hosting。 此方法会激活 Microsoft.Testing.Platform 活动源和计量器，而不会创建、刷新或释放 TracerProvider 或 MeterProvider。

订阅应用程序拥有的提供程序，通过其跟踪和指标生成器上的 AddTestingPlatformInstrumentation。 应用程序保留其提供程序、导出者、资源标识和处置的所有权。

对于由 MSBuild 生成的托管入口点，请引用 Microsoft.Testing.Extensions.Hosting，将 TestingPlatformHostFactory 设置为主机工厂方法，并设置：

<TestingPlatformOpenTelemetryMode>HostOwned</TestingPlatformOpenTelemetryMode>

HostOwned 仅调用 AddTestingPlatformDiagnostics；它不会创建提供程序，也不会替换主机的资源标识。 有关主机生命周期和工厂要求，请参阅 主机集成。

API

AddTestingPlatformDiagnostics

为由应用程序拥有的侦听器或 OpenTelemetry 提供程序激活 MTP 的活动源和计量器，而无需将提供程序的所有权转移给 MTP。

AddOpenTelemetryProvider

将 OpenTelemetry 提供程序注册到 ITestApplicationBuilder 上。 接受两个可选回调：

• 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_EXPORTEROTEL_EXPORTER_OTLP_ENDPOINT激活导出。

活动来源和测量器

该扩展会在以下情况下发出遥测：

• 活动源： Microsoft.Testing.Platform
• 米： Microsoft.Testing.Platform

语义约定

MTP 会发出标准的 OpenTelemetry 测试属性和代码属性；在有相应约定的情况下，这些属性包括 test.case.name、test.suite.name、code.function.name、code.file.path、code.line.number、code.stacktrace、error.type 和 test.case.result.status。 失败的测试会将 Span 状态设为 Error，并添加一个 exception 事件。

MTP 在这些约定的基础上进行了扩展，新增了额外的结果状态（skipped、error、cancelled、timeout 和 unknown），以及用于 OpenTelemetry 未定义概念的测试属性。 为保留现有仪表板，旧版属性名称和指标名称默认保持启用。

当启动进程提供了 TRACEPARENT 和 TRACESTATE 时，MTP 会将此次测试运行归入该跟踪之下，而不是启动一个不相关的根跟踪。

MSTest 执行范围

从 MSTest 4.5 和 MTP 2.5 预览版开始，MSTest 原生运行在每次测试执行时都会使用一个由 MTP 管理的规范活动。 MSTest 在运行测试构造函数、初始化、测试方法、清理和自定义 TestMethodAttribute 代码时使活动保持最新状态。 自动检测 HttpClient、SQL、实体框架、WCF 和自定义活动将成为测试活动的子级。

MTP 将最终结果、时间信息、输出和工件添加到同一活动中，并在 MSTest 记录的执行结束时间将其停止。 此行为可避免重复的框架和结果范围，并防止异步结果处理膨胀测试持续时间。

不使用规范执行 API 的测试框架保留兼容性拓扑：框架执行活动和 MTP 结果活动保持同级，结果活动链接到框架发布正在进行的更新时当前活动。

输出的指标

仪器	类型	单位	说明
test.case.duration	直方图	s	测试持续时间，按结果状态和套件分组。
test.case.result.count	Counter	{test}	已完成的测试，按结果状态和套件分组。
test.case.active	UpDownCounter	{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	未设置	设置为 true 禁用 OpenTelemetry SDK。
OTEL_SERVICE_NAME	未设置	覆盖服务名称。
OTEL_EXPORTER_OTLP_ENDPOINT	未设置	设置 OTLP 终结点。
OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER	未设置	选择追踪和指标导出器。