OpenTelemetry

Dieses Feature erfordert das NuGet-Paket "Microsoft.Testing.Extensions.OpenTelemetry ".

Diese Erweiterung integriert OpenTelemetry in Microsoft.Testing.Platform (MTP), sodass Testläufe Ablaufverfolgungen und Metriken über das standardmäßige OpenTelemetry SDK ausgeben können.

Hinweis

Diese Erweiterung ist ab Version 2.1.0 in MTP verfügbar.

Von Bedeutung

Ab MTP 2.4.0 folgt die OpenTelemetry-Erweiterung der MTP-Version, und ihre öffentlichen Einstiegspunkte sind nicht mehr experimentell.

Anbieterbesitz auswählen

Wählen Sie aus, ob MTP oder Ihre Anwendung besitzer der OpenTelemetry-Anbieter ist.

MTP-eigene Anbieter verwenden

Deaktivieren Sie den automatisch generierten Einstiegspunkt (<GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>) und rufen Sie AddOpenTelemetryProvider in Ihrer Main-Methode auf:

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

Um die Instrumentierung, Ressourcenattribute und einen OTLP-Exporter anhand der standardmäßigen Umgebungsvariablen OTEL_* zu konfigurieren, rufen Sie Folgendes auf:

builder.AddOpenTelemetryProviderFromEnvironment();

Die Methode fügt die Instrumentierung nur hinzu, wenn Sie einen Exporter konfigurieren oder einen Konfigurationsrückruf übergeben, sodass Sie die Registrierung in der Anwendung verlassen können, wenn einige Umgebungen keine Telemetrie exportieren.

Verwenden Sie anwendungseigene Provider

Ab der MTP 2.5-Vorschau rufen Sie AddTestingPlatformDiagnostics auf, wenn Ihre Anwendung OpenTelemetry bereits über Aspire ServiceDefaults, Microsoft.Extensions.Hosting oder eine andere Kompositionswurzel konfiguriert hat. Mit dieser Methode werden die Aktivitätsquelle und das Microsoft.Testing.Platform Meter aktiviert, ohne ein TracerProvider oder MeterProvider zu erstellen, zu leeren oder zu verwerfen.

Registrieren Sie den anwendungseigenen Provider mit AddTestingPlatformInstrumentation bei seinen Tracing- und Metrik-Buildern. Die Anwendung behält den Besitz ihrer Anbieter, Exporteure, Ressourcenidentität und Entsorgung bei.

Für einen von MSBuild generierten gehosteten Einstiegspunkt Microsoft.Testing.Extensions.Hosting referenzieren, TestingPlatformHostFactory auf die Host-Factorymethode festlegen und Folgendes festlegen:

<TestingPlatformOpenTelemetryMode>HostOwned</TestingPlatformOpenTelemetryMode>

HostOwned ruft nur AddTestingPlatformDiagnosticsauf. Er erstellt keine Anbieter oder ersetzt die Ressourcenidentität des Hosts. Informationen zu Hostlebenszyklus- und Factoryanforderungen finden Sie unter Hostintegration.

API

AddTestingPlatformDiagnostics

Aktiviert die Aktivitätsquelle und den Meter von MTP für anwendungseigene Listener oder OpenTelemetry-Anbieter, ohne die Inhaberschaft des Anbieters auf MTP zu übertragen.

AddOpenTelemetryProvider

Registriert den OpenTelemetry-Anbieter auf ITestApplicationBuilder. Akzeptiert zwei optionale Rückrufe:

• withTracing: konfiguriert die TracerProviderBuilder für die verteilte Ablaufverfolgung.
• withMetrics: konfiguriert das MeterProviderBuilder zur Sammlung von Metriken.

AddTestingPlatformInstrumentation

Rufen Sie TracerProviderBuilder oder MeterProviderBuilder auf, um die integrierte Microsoft.Testing.Platform Aktivitätsquelle und den -zähler zu abonnieren.

AddTestingPlatformResource

Rufen Sie ResourceBuilder auf, um Testassembly-, Host-, Betriebssystem- und Runtimeattribute hinzuzufügen. Der Detektor identifiziert auch CI-Anbieter, Pipeline, Zweig und Commit-Informationen für GitHub Actions, Azure Pipelines, GitLab CI und Jenkins.

Gezielte Ressourcenhilfen

Rufen Sie für einen anwendungseigenen Anbieter AddTestingPlatformTestResource auf, um testbezogene Identitäten hinzuzufügen, und AddTestingPlatformCIResource, um CI- und Versionsverwaltungs-Herkunftsinformationen hinzuzufügen. Diese fokussierten Helfer ersetzen keine anwendungseigenen service.*, , host.*, oder os.*process.* Attribute.

AddOpenTelemetryProviderFromEnvironment

Registriert Tracing, Metriken, Ressourcenerkennung und einen OTLP-Exporter anhand der standardmäßigen OpenTelemetry-Umgebungsvariablen. OTEL_SDK_DISABLED=true deaktiviert die Integration. Konfigurieren OTEL_TRACES_EXPORTER, , OTEL_METRICS_EXPORTERoder OTEL_EXPORTER_OTLP_ENDPOINT zum Aktivieren des Exports.

Aktivitätsquelle und -meter

Die Erweiterung sendet Telemetrie unter:

• Aktivitätsquelle: Microsoft.Testing.Platform
• Messgerät: Microsoft.Testing.Platform

Semantische Konventionen

MTP emittiert standardisierte OpenTelemetry-Test- und Codeattribute, für die eine Konvention existiert, einschließlich test.case.name, test.case.result.status, test.suite.name, code.function.name, code.line.number, code.file.path, code.stacktrace und error.type. Fehlgeschlagene Tests setzen den Span-Status auf Error und fügen ein exception-Ereignis hinzu.

MTP erweitert die Konventionen mit zusätzlichen Ergebniszuständen (skipped, error, timeout, cancelledund unknown) und Testattributen für Konzepte, die OpenTelemetry nicht definiert. Um vorhandene Dashboards beizubehalten, bleiben veraltete Attribut- und Instrumentnamen standardmäßig aktiviert.

Wenn der Startprozess TRACEPARENT und TRACESTATE bereitstellt, ordnet MTP den Testlauf dieser Trace zu, anstatt eine nicht zusammenhängende Root-Trace zu starten.

MSTest-Ausführungsspanne

Ab MSTest 4.5 und der Vorschau von MTP 2.5 verwenden native MSTest-Ausführungen für jede Testausführung eine kanonische, MTP-eigene Aktivität. MSTest macht die Aktivität aktuell, während sie den Testkonstruktor, die Initialisierung, die Testmethode, die Bereinigung und den benutzerdefinierten TestMethodAttribute Code ausführt. Automatisch instrumentierte HttpClient, SQL, Entity Framework, WCF und benutzerdefinierte Aktivitäten werden daher zu untergeordneten Elementen der Testaktivität.

MTP fügt derselben Aktivität das Endergebnis, die Zeitangaben, die Ausgabe und die Artefakte hinzu und stoppt sie zum von MSTest aufgezeichneten Ausführungsendzeitpunkt. Dieses Verhalten verhindert doppelte Framework- und Ergebnisspannen und verhindert, dass die asynchrone Ergebnisverarbeitung die Testdauer überhöht.

Testframeworks, die nicht die kanonische Ausführungs-API verwenden, behalten die Kompatibilitätstopologie bei: die Framework-Ausführungsaktivität und die MTP-Ergebnisaktivität bleiben gleichrangig, und die Ergebnisaktivität ist mit der Aktivität verknüpft, die aktuell war, als das Framework die Aktualisierung zum laufenden Vorgang veröffentlicht hat.

Ausgegebene Metriken

Instrument	Typ	Einheit	Description
test.case.duration	Histogramm	s	Testdauer, gruppiert nach Ergebnisstatus und Suite.
test.case.result.count	Counter	{test}	Abgeschlossene Tests, gruppiert nach Ergebnisstatus und Suite.
test.case.active	UpDownCounter	{test}	Derzeit ausgeführte Tests.
test.run.duration	Histogramm	s	Laufzeit, gruppiert nach Ergebnisstatus und Beendigungscode.
test.case.retry.count	Counter	{test}	Tests, die für einen anderen Versuch durch die Wiederholungserweiterung geplant sind.

Umgebungskonfiguration

Umgebungsvariable	Vorgabe	Description
TRACEPARENT, TRACESTATE	Nicht festgelegt	W3C-Ablaufverfolgungskontext für die übergeordnete Ausführung.
TESTINGPLATFORM_OTEL_CAPTURE_TEST_OUTPUT	1	Fügt erfasste Standardausgaben und Fehler an, um Spannen zu testen. Auf 0 setzen, wenn die Ausgabe Geheimnisse enthalten könnte.
TESTINGPLATFORM_OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT	8192	Legt die maximale Anzahl von Zeichen fest, die für ein Zeichenfolgenattribut beibehalten werden.
TESTINGPLATFORM_OTEL_EMIT_LEGACY_ATTRIBUTES	1	Gibt veraltete Attribut- und Instrumentnamen zusammen mit Namen gemäß semantischer Konventionen aus.
OTEL_SDK_DISABLED	Nicht festgelegt	Legen Sie den Wert auf true fest, um das OpenTelemetry SDK zu deaktivieren.
OTEL_SERVICE_NAME	Nicht festgelegt	Setzt den Dienstnamen außer Kraft.
OTEL_EXPORTER_OTLP_ENDPOINT	Nicht festgelegt	Legt den OTLP-Endpunkt fest.
OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER	Nicht festgelegt	Wählt Trace- und Metrik-Exporter aus.