OpenTelemetry

Ta funkcja wymaga pakietu NuGet Microsoft.Testing.Extensions.OpenTelemetry .

To rozszerzenie integruje OpenTelemetry z Microsoft.Testing.Platform (MTP), umożliwiając wykonaniu testów emisję śladów i metryk za pomocą standardowego zestawu SDK OpenTelemetry.

Uwaga / Notatka

To rozszerzenie jest dostępne w MTP, począwszy od wersji 2.1.0.

Ważna

Począwszy od MTP 2.4.0, rozszerzenie OpenTelemetry jest zgodne z wersją wydania MTP, a jego publiczne punkty wejścia nie są już eksperymentalne.

Wybieranie własności dostawcy

Wybierz, czy MTP, czy aplikacja jest właścicielem dostawców OpenTelemetry.

Korzystanie z dostawców należących do MTP

Wyłącz automatycznie wygenerowany punkt wejścia (<GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>) i wywołaj AddOpenTelemetryProvider w metodzie 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();

Aby skonfigurować instrumentację, atrybuty zasobów i eksporter OTLP za pomocą standardowych zmiennych środowiskowych OTEL_*, wywołaj:

builder.AddOpenTelemetryProviderFromEnvironment();

Metoda dodaje instrumentację tylko wtedy, gdy skonfigurujesz eksporter lub przekażesz funkcję zwrotną konfiguracji, dzięki czemu możesz pozostawić rejestrację w kodzie aplikacji, nawet jeśli niektóre środowiska nie eksportują danych telemetrycznych.

Korzystanie z dostawców należących do aplikacji

Począwszy od podglądowej wersji MTP 2.5, wywołaj AddTestingPlatformDiagnostics, gdy aplikacja już konfiguruje OpenTelemetry przez Aspire ServiceDefaults, Microsoft.Extensions.Hosting lub inny composition root. Ta metoda aktywuje Microsoft.Testing.Platform źródło działania i miernik bez tworzenia, opróżniania lub usuwania elementu TracerProvider lub MeterProvider.

Zarejestruj dostawcę będącego własnością aplikacji za pomocą AddTestingPlatformInstrumentation w konstruktorach śledzenia i metryk. Aplikacja zachowuje własność swoich dostawców, eksporterów, tożsamości zasobów i usuwania.

W przypadku hostowanego punktu wejścia wygenerowanego przez program MSBuild odwołaj się do Microsoft.Testing.Extensions.Hosting, ustaw TestingPlatformHostFactory na metodę fabryki hosta i ustaw:

<TestingPlatformOpenTelemetryMode>HostOwned</TestingPlatformOpenTelemetryMode>

HostOwned wywołuje tylko AddTestingPlatformDiagnostics; nie tworzy dostawców ani nie zastępuje tożsamości zasobu hosta. Aby uzyskać informacje na temat wymagań dotyczących cyklu życia hosta i fabryki, zobacz Integracja hostów.

API

AddTestingPlatformDiagnostics

Aktywuje źródło aktywności i miernik MTP dla odbiorników należących do aplikacji lub dostawców OpenTelemetry bez przenoszenia własności dostawcy do MTP.

AddOpenTelemetryProvider

Rejestruje dostawcę OpenTelemetry na ITestApplicationBuilder. Akceptuje dwa opcjonalne wywołania zwrotne:

• withTracing: konfiguruje TracerProviderBuilder na potrzeby śledzenia rozproszonego.
• withMetrics: konfiguruje MeterProviderBuilder do zbierania metryk.

AddTestingPlatformInstrumentation

Wywołaj TracerProviderBuilder lub MeterProviderBuilder subskrybuj wbudowane Microsoft.Testing.Platform źródło działania i miernik.

AddTestingPlatformResource

Użyj ResourceBuilder, aby dodać atrybuty zestawu testowego, hosta, systemu operacyjnego i środowiska uruchomieniowego. Detektor identyfikuje również dostawcę CI oraz informacje o potoku, gałęzi i commicie dla GitHub Actions, Azure Pipelines, GitLab CI i Jenkins.

Skoncentrowani pomocnicy zasobów

W przypadku dostawcy będącego własnością aplikacji wywołaj metodę AddTestingPlatformTestResource, aby dodać tożsamość specyficzną dla testów, oraz AddTestingPlatformCIResource, aby dodać informacje o pochodzeniu z CI i systemu kontroli wersji. Ci skoncentrowani pomocnicy nie zastępują atrybutów należących do service.*aplikacji , host.*, os.*ani process.* .

AddOpenTelemetryProviderFromEnvironment

Konfiguruje śledzenie, metryki, wykrywanie zasobów i eksporter OTLP na podstawie standardowych zmiennych środowiskowych OpenTelemetry. OTEL_SDK_DISABLED=true wyłącza integrację. Skonfiguruj OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTERlub OTEL_EXPORTER_OTLP_ENDPOINT , aby aktywować eksport.

Źródło i miernik aktywności

Rozszerzenie emituje dane telemetryczne w obszarze:

• Źródło działania: Microsoft.Testing.Platform
• Miernik: Microsoft.Testing.Platform

Konwencje semantyczne

MTP emituje standardowe atrybuty testów OpenTelemetry i atrybuty kodu tam, gdzie istnieje odpowiednia konwencja, w tym test.case.name, code.file.path, test.case.result.status, code.function.name, code.line.number, test.suite.name, code.stacktrace i error.type. Nieudane testy ustawiają status zakresu na Error i dodają zdarzenie exception.

MTP rozszerza konwencje o dodatkowe stany rezultatów (skipped, error, timeout, cancelled i unknown) oraz atrybuty testów dla pojęć, których OpenTelemetry nie definiuje. Aby zachować istniejące pulpity nawigacyjne, starsze nazwy atrybutów i instrumentów pozostają domyślnie włączone.

Gdy proces uruchamiający dostarcza TRACEPARENT i TRACESTATE, MTP umieszcza wykonanie testu w ramach tego śladu, zamiast rozpoczynać osobny ślad główny.

Przedziały wykonywania MSTest

Począwszy od wersji zapoznawczych MSTest 4.5 i MTP 2.5, natywne uruchomienia MSTest używają jednej kanonicznej aktywności zarządzanej przez MTP dla każdego uruchomienia testu. MSTest ustawia aktywność jako bieżącą podczas wykonywania konstruktora testu, inicjalizacji, metody testowej, czyszczenia i niestandardowego kodu TestMethodAttribute. Automatycznie instrumentowane HttpClient, SQL, Entity Framework, WCF oraz działania niestandardowe stają się działaniami podrzędnymi działania testowego.

MTP dodaje wynik końcowy, informacje o czasie, dane wyjściowe i artefakty do tej samej aktywności oraz kończy ją w czasie zakończenia wykonania zarejestrowanym przez MSTest. To zachowanie zapobiega zduplikowanym spanom frameworka i wyników oraz temu, by asynchroniczne przetwarzanie wyników zawyżało czas trwania testu.

Frameworki testowe, które nie korzystają z kanonicznego interfejsu API wykonywania testów, zachowują topologię zgodności: aktywność wykonywania frameworka i aktywność wyników MTP pozostają równorzędne, a aktywność wyników jest powiązana z aktywnością, która była bieżąca w chwili opublikowania przez framework aktualizacji w toku.

Emitowane metryki

Przyrząd	Typ	Jednostka	Opis
test.case.duration	Histogram	s	Czas trwania testów, pogrupowany według statusu wyniku i pakietu testów.
test.case.result.count	Counter	{test}	Zakończone testy, pogrupowane według statusu wyniku i pakietu.
test.case.active	UpDownCounter	{test}	Testy, które są obecnie uruchomione.
test.run.duration	Histogram	s	Czas trwania przebiegu, pogrupowany według stanu wyniku i kodu zakończenia.
test.case.retry.count	Counter	{test}	Testy zaplanowane do ponowienia przez rozszerzenie odpowiedzialne za ponawianie.

Konfiguracja środowiska

Zmienna środowiskowa	Default	Opis
TRACEPARENT, TRACESTATE	Nieustawiony	Kontekst śledzenia W3C dla przebiegu nadrzędnego.
TESTINGPLATFORM_OTEL_CAPTURE_TEST_OUTPUT	1	Dołącza przechwycone standardowe dane wyjściowe i błędy w celu testowania zakresów. Ustaw na 0, jeśli dane wyjściowe mogą zawierać tajne dane.
TESTINGPLATFORM_OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT	8192	Ustawia maksymalne znaki przechowywane dla atrybutu ciągu.
TESTINGPLATFORM_OTEL_EMIT_LEGACY_ATTRIBUTES	1	Emituje starsze nazwy atrybutów i instrumentów wraz z nazwami semantycznych konwencji.
OTEL_SDK_DISABLED	Nieustawiony	Ustaw na true, aby wyłączyć pakiet OpenTelemetry SDK.
OTEL_SERVICE_NAME	Nieustawiony	Zastępuje nazwę usługi.
OTEL_EXPORTER_OTLP_ENDPOINT	Nieustawiony	Ustawia punkt końcowy OTLP.
OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER	Nieustawiony	Wybiera eksportery śladów i metryk.