Włączanie eksportera OpenTelemetry usługi Azure Monitor dla aplikacji .NET, Node.js i Python (wersja zapoznawcza)

W tym artykule opisano sposób włączania i konfigurowania oferty usługi Azure Monitor opartej na usłudze OpenTelemetry w wersji zapoznawczej. Po zakończeniu instrukcji opisanych w tym artykule będziesz mieć możliwość wysyłania śladów biblioteki OpenTelemetry do Szczegółowe informacje aplikacji usługi Azure Monitor. Aby dowiedzieć się więcej o usłudze OpenTelemetry, zobacz Często zadawane pytania dotyczące platformy OpenTelemetry lub OpenTelemetry.

Ważne

Eksporter OpenTelemetry usługi Azure Monitor dla platformy .NET, Node.js i aplikacji języka Python jest obecnie w wersji zapoznawczej. Zobacz Dodatkowe warunki użytkowania wersji zapoznawczych platformy Microsoft Azure, aby zapoznać się z postanowieniami prawnymi dotyczącymi funkcji platformy Azure, które są w wersji beta lub wersji zapoznawczej albo w inny sposób nie zostały jeszcze wydane jako ogólnie dostępne.

Ograniczenia wersji zapoznawczej

Dokładnie zastanów się, czy ta wersja zapoznawcza jest odpowiednia dla Ciebie. Umożliwia tylko śledzenie rozproszone i wyklucza:

Jeśli potrzebujesz pełnego środowiska funkcji, użyj istniejącej usługi Application Szczegółowe informacje ASP.NET lub ASP.NET Core SDK do czasu dojrzałej oferty opartej na protokole OpenTelemetry.

Rozpoczęcie pracy

Wykonaj kroki opisane w tej sekcji, aby instrumentować aplikację przy użyciu usługi OpenTelemetry.

Wymagania wstępne

Instalowanie bibliotek klienckich

Zainstaluj najnowszy pakiet NuGet Azure.Monitor.OpenTelemetry.Exporter:

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter 

Jeśli wystąpi błąd, taki jak "Brak dostępnych wersji dla pakietu Azure.Monitor.OpenTelemetry.Exporter", prawdopodobnie brakuje ustawienia źródeł pakietów NuGet. Spróbuj określić źródło przy użyciu -s opcji :

# Install the latest package with the NuGet package source specified.
dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter -s https://api.nuget.org/v3/index.json

Włączanie Szczegółowe informacje aplikacji usługi Azure Monitor

Ta sekcja zawiera wskazówki, które pokazują, jak włączyć funkcję OpenTelemetry.

Dodawanie kodu instrumentacji OpenTelemetry

Poniższy kod pokazuje, jak włączyć funkcję OpenTelemetry w aplikacji konsolowej języka C#, konfigurując element TracerProvider openTelemetry. Ten kod musi znajdować się w uruchamianiu aplikacji. W przypadku ASP.NET Core zazwyczaj odbywa się to w ConfigureServices metodzie klasy aplikacjiStartup. W przypadku ASP.NET aplikacji zazwyczaj odbywa się to w systemie Global.asax.cs.

using System.Diagnostics;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;

public class Program
{
    private static readonly ActivitySource MyActivitySource = new ActivitySource(
        "OTel.AzureMonitor.Demo");

    public static void Main()
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddAzureMonitorTraceExporter(o =>
            {
                o.ConnectionString = "<Your Connection String>";
            })
            .Build();

        using (var activity = MyActivitySource.StartActivity("TestActivity"))
        {
            activity?.SetTag("CustomTag1", "Value1");
            activity?.SetTag("CustomTag2", "Value2");
        }

        System.Console.WriteLine("Press Enter key to exit.");
        System.Console.ReadLine();
    }
}

Uwaga

Klasy Activity i ActivitySource z System.Diagnostics przestrzeni nazw reprezentują odpowiednio pojęcia openTelemetry i SpanTracer. Można utworzyć ActivitySource bezpośrednio przy użyciu konstruktora, a nie za pomocą polecenia TracerProvider. Każda ActivitySource klasa musi być jawnie połączona TracerProvider z przy użyciu polecenia AddSource(). Wynika to z faktu, że części interfejsu API śledzenia OpenTelemetry są włączone bezpośrednio do środowiska uruchomieniowego platformy .NET. Aby dowiedzieć się więcej, zobacz Wprowadzenie do interfejsu API śledzenia platformy .NET openTelemetry.

Porada

Dodaj biblioteki instrumentacji do automatycznej telemetrii w popularnych strukturach i bibliotekach.

Ustawianie parametrów połączenia Szczegółowe informacje aplikacji

Zastąp symbol zastępczy <Your Connection String> w poprzednim kodzie parametrami połączenia z zasobu Application Szczegółowe informacje.

Screenshot of the Application Insights connection string.

Potwierdzanie przepływu danych

Uruchom aplikację i otwórz kartę Zasób Szczegółowe informacje aplikacji w Azure Portal. Wyświetlenie danych w portalu może potrwać kilka minut.

Uwaga

Jeśli nie możesz uruchomić aplikacji lub nie otrzymujesz danych zgodnie z oczekiwaniami, zobacz Rozwiązywanie problemów.

Screenshot of the Application Insights Overview tab with server requests and server response time highlighted.

Ważne

Jeśli masz co najmniej dwie usługi, które emitują dane telemetryczne do tego samego zasobu aplikacji Szczegółowe informacje, musisz ustawić nazwy ról w chmurze, aby reprezentować je prawidłowo na mapie aplikacji.

W ramach korzystania z instrumentacji Szczegółowe informacje aplikacji zbieramy i wysyłamy dane diagnostyczne do firmy Microsoft. Te dane ułatwiają uruchamianie i ulepszanie Szczegółowe informacje aplikacji. Możesz wyłączyć zbieranie danych bez wpływu. Aby dowiedzieć się więcej, zobacz Statystykibeat w aplikacja systemu Azure Szczegółowe informacje.

Ustawianie nazwy roli chmury i wystąpienia roli w chmurze

Możesz ustawić nazwę roli chmury i wystąpienie roli w chmurze za pomocą atrybutów zasobu . Ten krok aktualizuje nazwę roli chmury i wystąpienie roli chmury z ich wartości domyślnych do czegoś, co ma sens dla twojego zespołu. Zostaną one wyświetlone na mapie aplikacji jako nazwę poniżej węzła. Nazwa roli w chmurze używa atrybutów service.namespace i service.name , chociaż nie service.nameservice.namespace jest ustawiona. Wystąpienie roli w chmurze używa wartości atrybutu service.instance.id .

// Setting role name and role instance
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
// Done setting role name and role instance

// Set ResourceBuilder on the provider.
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .SetResourceBuilder(resourceBuilder)
        .AddSource("OTel.AzureMonitor.Demo")
        .AddAzureMonitorTraceExporter(o =>
        {
            o.ConnectionString = "<Your Connection String>";
        })
        .Build();

Aby uzyskać informacje na temat standardowych atrybutów zasobów, zobacz Konwencje semantyczne zasobów.

Próbkowanie

Próbkowanie jest obsługiwane w programie OpenTelemetry, ale nie jest obecnie obsługiwane w eksporterze OpenTelemetry usługi Azure Monitor.

Ostrzeżenie

Włączenie próbkowania w usłudze OpenTelemetry sprawia, że standardowe i oparte na dziennikach metryki są bardzo niedokładne, co niekorzystnie wpływa na wszystkie środowiska Szczegółowe informacje aplikacji. Ponadto włączenie próbkowania obok istniejących zestawów SDK aplikacji Szczegółowe informacje powoduje uszkodzenie śladów.

Biblioteki instrumentacji

Następujące biblioteki są weryfikowane do pracy z wersją zapoznawcza.

Ostrzeżenie

Biblioteki instrumentacji są oparte na eksperymentalnych specyfikacjach OpenTelemetry. Zobowiązanie do pomocy technicznej firmy Microsoft w wersji zapoznawczej polega na upewnieniu się, że następujące biblioteki emitują dane do usługi Azure Monitor Application Szczegółowe informacje, ale istnieje możliwość, że zmiany powodujące niezgodność lub mapowanie eksperymentalne zablokują niektóre elementy danych.

HTTP

baza danych

Uwaga

Oferta w wersji zapoznawczej obejmuje tylko instrumentacje obsługujące żądania HTTP i bazy danych. Aby dowiedzieć się więcej, zobacz OpenTelemetry Semantic Conventions (Konwencje semantyczne OpenTelemetry).

Modyfikowanie danych telemetrycznych

W tej sekcji opisano sposób modyfikowania danych telemetrycznych.

Dodawanie atrybutów zakresu

Aby dodać atrybuty zakresu, użyj jednego z następujących dwóch sposobów:

Te atrybuty mogą obejmować dodawanie właściwości niestandardowej do telemetrii. Możesz również użyć atrybutów, aby ustawić pola opcjonalne w schemacie Szczegółowe informacje aplikacji, na przykład adres IP klienta.

Porada

Zaletą korzystania z opcji udostępnianych przez biblioteki instrumentacji, gdy są dostępne, jest to, że cały kontekst jest dostępny. W związku z tym użytkownicy mogą wybrać opcję dodawania lub filtrowania większej liczby atrybutów. Na przykład opcja wzbogacania w bibliotece instrumentacji HttpClient zapewnia użytkownikom dostęp do samej funkcji httpRequestMessage. Mogą wybierać dowolne elementy i przechowywać je jako atrybut.

Dodawanie właściwości niestandardowej

Wszystkie atrybuty dodawane do zakresów są eksportowane jako właściwości niestandardowe. Wypełniają one pole customDimensions w tabelach żądań lub zależności w Szczegółowe informacje aplikacji.

  1. Wiele bibliotek instrumentacji zapewnia opcję wzbogacania. Aby uzyskać wskazówki, zobacz pliki readme poszczególnych bibliotek instrumentacji:

  2. Użyj niestandardowego procesora:

Porada

Dodaj procesor pokazany tutaj przed eksporterem usługi Azure Monitor.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddSource("OTel.AzureMonitor.Demo")
        .AddProcessor(new ActivityEnrichingProcessor())
        .AddAzureMonitorTraceExporter(o =>
        {
                o.ConnectionString = "<Your Connection String>"
        })
        .Build();

Dodaj ActivityEnrichingProcessor.cs do projektu następujący kod:

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;

public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Ustawianie adresu IP użytkownika

Możesz wypełnić pole client_IP dla żądań, ustawiając http.client_ip atrybut na rozpiętości. Aplikacja Szczegółowe informacje używa adresu IP do generowania atrybutów lokalizacji użytkownika, a następnie domyślnie odrzuca je.

Użyj przykładu dodawania właściwości niestandardowej, ale zastąp następujące wiersze kodu w pliku ActivityEnrichingProcessor.cs:

// only applicable in case of activity.Kind == Server
activity.SetTag("http.client_ip", "<IP Address>");

Filtrowanie danych telemetrycznych

Aby odfiltrować dane telemetryczne przed opuszczeniem aplikacji, możesz użyć następujących sposobów.

  1. Wiele bibliotek instrumentacji udostępnia opcję filtru. Aby uzyskać wskazówki, zobacz pliki readme poszczególnych bibliotek instrumentacji:

  2. Użyj niestandardowego procesora:

    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddProcessor(new ActivityFilteringProcessor())
            .AddAzureMonitorTraceExporter(o =>
            {
                    o.ConnectionString = "<Your Connection String>"
            })
            .Build();
    

    Dodaj ActivityFilteringProcessor.cs do projektu następujący kod:

    using System.Diagnostics;
    using OpenTelemetry;
    using OpenTelemetry.Trace;
    
    public class ActivityFilteringProcessor : BaseProcessor<Activity>
    {
        public override void OnStart(Activity activity)
        {
            // prevents all exporters from exporting internal activities
            if (activity.Kind == ActivityKind.Internal)
            {
                activity.IsAllDataRequested = false;
            }
        }
    }
    
  3. Jeśli określone źródło nie zostanie jawnie dodane przy użyciu polecenia AddSource("ActivitySourceName"), żadne z działań utworzonych przy użyciu tego źródła nie zostanie wyeksportowane.

Włączanie eksportera OTLP

Możesz włączyć eksportera OpenTelemetry Protocol (OTLP) wraz z eksporterem usługi Azure Monitor w celu wysłania danych telemetrycznych do dwóch lokalizacji.

Uwaga

Eksporter OTLP jest wyświetlany tylko dla wygody. Nie obsługujemy oficjalnie eksportera OTLP ani żadnych składników ani środowisk innych firm podrzędnych. Zalecamy otwarcie problemu z problemami openTelemetry-Collector dla openTelemetry spoza granicy pomoc techniczna platformy Azure.

  1. Zainstaluj pakiet OpenTelemetry.Exporter.OpenTelemetryProtocol wraz z elementem Azure.Monitor.OpenTelemetry.Exporter w projekcie.

  2. Dodaj następujący fragment kodu. W tym przykładzie przyjęto założenie, że masz moduł zbierający OpenTelemetry z uruchomionym odbiornikiem OTLP. Aby uzyskać szczegółowe informacje, zobacz przykład dotyczący GitHub.

    // Sends data to Application Insights as well as OTLP
    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddAzureMonitorTraceExporter(o =>
            {
                o.ConnectionString = "<Your Connection String>"
            })
            .AddOtlpExporter()
            .Build();
    

Rozwiązywanie problemów

Ta sekcja zawiera pomoc dotyczącą rozwiązywania problemów.

Włączanie rejestrowania diagnostycznego

Eksporter usługi Azure Monitor używa usługi EventSource do rejestrowania wewnętrznego. Dzienniki eksportera są dostępne dla dowolnego elementu EventListener, decydując się na źródło o nazwie OpenTelemetry-AzureMonitor-Exporter. Aby uzyskać informacje na temat kroków rozwiązywania problemów, zobacz Rozwiązywanie problemów z funkcją OpenTelemetry.

Znane problemy

Znane problemy dotyczące eksporterów OpenTelemetry usługi Azure Monitor obejmują:

  • Brak nazwy operacji na telemetrii zależności, co niekorzystnie wpływa na błędy i działanie karty wydajności.
  • Brak modelu urządzenia w przypadku danych telemetrycznych żądań i zależności, które niekorzystnie wpływają na analizę kohort urządzeń.
  • Nazwa serwera bazy danych jest pominięta w nazwie zależności, która niepoprawnie agreguje tabele o tej samej nazwie na różnych serwerach.

Pomoc techniczna

Aby uzyskać pomoc techniczną:

Opinie dotyczące usługi OpenTelemetry

Aby przekazać opinię:

Następne kroki