Konfigurowanie usługi Azure Monitor OpenTelemetry

W tym artykule opisano ustawienia konfiguracji dystrybucji OpenTelemetry usługi Azure Monitor.

Connection string

Parametry połączenia w usłudze Application Szczegółowe informacje definiuje lokalizację docelową wysyłania danych telemetrycznych, zapewniając, że osiąga odpowiedni zasób do monitorowania i analizy.

Aby skonfigurować parametry połączenia, użyj jednego z następujących trzech sposobów:

  • Dodaj UseAzureMonitor() do uruchamiania aplikacji w program.cs klasie .

    // Create a new ASP.NET Core web application builder.    
    var builder = WebApplication.CreateBuilder(args);
    
    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
        options.ConnectionString = "<Your Connection String>";
    });
    
    // Build the ASP.NET Core web application.
    var app = builder.Build();
    
    // Start the ASP.NET Core web application.    
    app.Run();
    
  • Ustaw zmienną środowiskową.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
    
  • Dodaj następującą sekcję do appsettings.json pliku konfiguracji.

    {
      "AzureMonitor": {
          "ConnectionString": "<Your Connection String>"
      }
    }
    

Uwaga

Jeśli ustawisz parametry połączenia w więcej niż jednym miejscu, przestrzegamy następującego pierwszeństwa:

  1. Kod
  2. Zmienna środowiskowa
  3. Plik konfiguracji

Ustawianie nazwy roli chmury i wystąpienia roli w chmurze

W przypadku obsługiwanych języków dystrybucja OpenTelemetry usługi Azure Monitor automatycznie wykrywa kontekst zasobu i udostępnia wartości domyślne właściwości Nazwa roli chmury i Wystąpienie roli chmury składnika. Warto jednak zastąpić wartości domyślne coś, co ma sens dla twojego zespołu. Wartość nazwy roli chmury jest wyświetlana na mapie aplikacji jako nazwa poniżej węzła.

Ustaw nazwę roli chmury i wystąpienie roli chmury za pomocą atrybutów zasobów . Nazwa roli chmury używa service.namespace atrybutów i service.name , chociaż nie service.nameservice.namespace jest ustawiona. Wystąpienie roli w chmurze używa wartości atrybutu service.instance.id . Aby uzyskać informacje na temat atrybutów standardowych dla zasobów, zobacz OpenTelemetry Semantic Conventions (Konwencje semantyczne protokołu OpenTelemetry).

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Configure the OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.ConfigureResource(resourceBuilder => 
        resourceBuilder.AddAttributes(resourceAttributes)));

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Włączanie próbkowania

Możesz włączyć próbkowanie, aby zmniejszyć ilość pozyskiwania danych, co zmniejsza koszt. Usługa Azure Monitor udostępnia niestandardowy próbkator o stałej szybkości, który wypełnia zdarzenia współczynnikiem próbkowania, który aplikacja Szczegółowe informacje konwertuje na ItemCountwartość . Próbkator o stałej szybkości zapewnia dokładne środowiska i liczby zdarzeń. Przykładowy program został zaprojektowany w celu zachowania śladów między usługami i współdziała ze starszymi zestawami SDK usługi Application Szczegółowe informacje. Aby uzyskać więcej informacji, zobacz Dowiedz się więcej o próbkowaniu.

Uwaga

Metryki i dzienniki nie mają wpływu na próbkowanie.

Próbkator oczekuje częstotliwości próbkowania z zakresu od 0 do 1 włącznie. Szybkość 0,1 oznacza, że wysyłane są około 10% śladów.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Napiwek

W przypadku korzystania z próbkowania o stałej szybkości/wartości procentowej nie masz pewności, co należy ustawić częstotliwość próbkowania jako, zacznij od 5% (tj. współczynnik próbkowania 0,05) i dostosuj szybkość na podstawie dokładności operacji pokazanych w blokach błędów i wydajności. Wyższa stawka zwykle skutkuje wyższą dokładnością. Jednak każde próbkowanie będzie miało wpływ na dokładność, dlatego zalecamy alerty dotyczące metryk OpenTelemetry, które nie mają wpływu na próbkowanie.

Włączanie uwierzytelniania w usłudze Microsoft Entra ID (dawniej Azure AD)

Możesz włączyć uwierzytelnianie entra firmy Microsoft na potrzeby bezpieczniejszego połączenia z platformą Azure, co uniemożliwia pozyskiwanie nieautoryzowanych danych telemetrycznych do subskrypcji.

Obsługujemy klasy poświadczeń udostępniane przez usługę Azure Identity.

  • Zalecamy DefaultAzureCredential tworzenie aplikacji lokalnych.
  • Zalecamy ManagedIdentityCredential używanie tożsamości zarządzanych przypisanych przez system i przypisanych przez użytkownika.
    • W przypadku przypisanego przez system użyj konstruktora domyślnego bez parametrów.
    • W przypadku przypisanego przez użytkownika podaj identyfikator klienta konstruktorowi.
  • Zalecamy ClientSecretCredential korzystanie z jednostek usługi.
    • Podaj identyfikator dzierżawy, identyfikator klienta i klucz tajny klienta konstruktora.
  1. Zainstaluj najnowszy pakiet Azure.Identity :

    dotnet add package Azure.Identity
    
  2. Podaj żądaną klasę poświadczeń:

    // Create a new ASP.NET Core web application builder.    
    var builder = WebApplication.CreateBuilder(args);
    
    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
        // Set the Azure Monitor credential to the DefaultAzureCredential.
        // This credential will use the Azure identity of the current user or
        // the service principal that the application is running as to authenticate
        // to Azure Monitor.
        options.Credential = new DefaultAzureCredential();
    });
    
    // Build the ASP.NET Core web application.
    var app = builder.Build();
    
    // Start the ASP.NET Core web application.
    app.Run();
    

Magazyn w trybie offline i automatyczne ponawianie prób

Aby zwiększyć niezawodność i odporność, oferty oparte na usłudze Azure Monitor OpenTelemetry zapisują się do magazynu w trybie offline/lokalnym domyślnie, gdy aplikacja utraci połączenie z usługą Application Szczegółowe informacje. Zapisuje ona dane telemetryczne aplikacji na dysku i okresowo próbuje wysłać ją ponownie przez maksymalnie 48 godzin. W aplikacjach o dużym obciążeniu dane telemetryczne są od czasu do czasu porzucane z dwóch powodów. Po pierwsze, gdy dozwolony czas zostanie przekroczony, a po drugie, gdy maksymalny rozmiar pliku zostanie przekroczony lub zestaw SDK nie ma możliwości wyczyszczenia pliku. Jeśli musimy wybrać, produkt zapisuje najnowsze zdarzenia w porównaniu ze starymi. Dowiedz się więcej

Pakiet dystrybucji zawiera element AzureMonitorExporter, który domyślnie używa jednej z następujących lokalizacji dla magazynu offline (wymienionego w kolejności pierwszeństwa):

  • Windows:
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • System inny niż Windows
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Aby zastąpić katalog domyślny, należy ustawić wartość AzureMonitorOptions.StorageDirectory.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that cannot be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Aby wyłączyć tę funkcję, należy ustawić wartość AzureMonitorOptions.DisableOfflineStorage = true.

Włączanie eksportera OTLP

Możesz włączyć eksportera protokołu 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.

  1. Zainstaluj pakiet OpenTelemetry.Exporter.OpenTelemetryProtocol w projekcie.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
    
  2. Dodaj następujący fragment kodu. W tym przykładzie założono, że masz moduł zbierający OpenTelemetry z uruchomionym odbiornikiem OTLP. Aby uzyskać szczegółowe informacje, zobacz przykład w witrynie GitHub.

    // Create a new ASP.NET Core web application builder.
    var builder = WebApplication.CreateBuilder(args);
    
    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor();
    
    // Add the OpenTelemetry OTLP exporter to the application.
    // This exporter will send telemetry data to an OTLP receiver, such as Prometheus
    builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
    builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());
    
    // Build the ASP.NET Core web application.
    var app = builder.Build();
    
    // Start the ASP.NET Core web application.
    app.Run();
    

Konfiguracje openTelemetry

Następujące konfiguracje biblioteki OpenTelemetry można uzyskać za pośrednictwem zmiennych środowiskowych podczas korzystania z dystrybucji OpenTelemetry usługi Azure Monitor.

Zmienna środowiskowa opis
APPLICATIONINSIGHTS_CONNECTION_STRING Ustaw go na parametry połączenia dla zasobu application Szczegółowe informacje.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Ustaw ją, aby true zrezygnować z wewnętrznej kolekcji metryk.
OTEL_RESOURCE_ATTRIBUTES Pary klucz-wartość, które mają być używane jako atrybuty zasobów. Aby uzyskać więcej informacji na temat atrybutów zasobów, zobacz specyfikację zestawu Resource SDK.
OTEL_SERVICE_NAME Ustawia wartość atrybutu service.name zasobu. Jeśli service.name element jest również podany w pliku OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME ma pierwszeństwo.

Często zadawane pytania

Ta sekcja zawiera odpowiedzi na typowe pytania.

Co to jest OpenTelemetry?

Jest to nowy standard open source umożliwiający obserwowanie. Dowiedz się więcej na stronie OpenTelemetry.

Dlaczego usługa Microsoft Azure Monitor inwestuje w rozwiązanie OpenTelemetry?

Firma Microsoft jest jednym z największych współautorów usługi OpenTelemetry.

Najważniejsze propozycje dotyczące biblioteki OpenTelemetry są neutralne dla dostawcy i zapewniają spójne interfejsy API/zestawy SDK w różnych językach.

Z biegiem czasu uważamy, że platforma OpenTelemetry umożliwi klientom usługi Azure Monitor obserwowanie aplikacji napisanych w językach poza obsługiwanymi językami. Rozszerza również typy danych, które można zbierać za pomocą bogatego zestawu bibliotek instrumentacji. Ponadto zestawy SDK OpenTelemetry są bardziej wydajne na dużą skalę niż ich poprzedniki, zestawy SDK aplikacji Szczegółowe informacje.

Na koniec platforma OpenTelemetry jest zgodna ze strategią firmy Microsoft w celu przyjęcia rozwiązania open source.

Jaki jest stan funkcji OpenTelemetry?

Zobacz Stan openTelemetry.

Co to jest "Dystrybucja opentelemetrii usługi Azure Monitor"?

Można go traktować jako cienką otokę, która łączy wszystkie składniki OpenTelemetry dla środowiska pierwszej klasy na platformie Azure. Ta otoka jest również nazywana dystrybucją w usłudze OpenTelemetry.

Dlaczego należy używać dystrybucji "Azure Monitor OpenTelemetry"?

Korzystanie z dystrybucji OpenTelemetry usługi Azure Monitor za pośrednictwem natywnej biblioteki OpenTelemetry z poziomu społeczności ma kilka zalet:

W duchu OpenTelemetry zaprojektowaliśmy dystrybucję tak, aby była otwarta i rozszerzalna. Możesz na przykład dodać następujące elementy:

  • Eksporter Protokołu OTLP (OpenTelemetry Protocol) i wysyłany jednocześnie do drugiego miejsca docelowego
  • Inne biblioteki instrumentacji nieuwzględniane w dystrybucji

Ponieważ dystrybucja dystrybucji zapewnia dystrybucję OpenTelemetry, dystrybucja obsługuje wszystkie elementy obsługiwane przez bibliotekę OpenTelemetry. Na przykład można dodać więcej procesorów telemetrycznych, eksporterów lub bibliotek instrumentacji, jeśli usługa OpenTelemetry je obsługuje.

Uwaga

Dystrybucja ustawia próbkator na niestandardowy przykładowy, stały współczynnik dla Szczegółowe informacje aplikacji. Można to zmienić na inny przykład, ale może to spowodować wyłączenie niektórych dołączonych możliwości dystrybucji. Aby uzyskać więcej informacji na temat obsługiwanego przykładnika, zobacz sekcję Włączanie próbkowania w temacie Konfigurowanie usługi Azure Monitor OpenTelemetry.

W przypadku języków bez obsługiwanego autonomicznego eksportera OpenTelemetry usługa Azure Monitor OpenTelemetry Distro jest jedynym obecnie obsługiwanym sposobem korzystania z biblioteki OpenTelemetry w usłudze Azure Monitor. W przypadku języków z obsługiwanym autonomicznym eksporterem OpenTelemetry możesz użyć dystrybucji OpenTelemetry usługi Azure Monitor lub odpowiedniego autonomicznego eksportera OpenTelemetry OpenTelemetry w zależności od scenariusza telemetrii. Aby uzyskać więcej informacji, zobacz Kiedy należy używać eksportera OpenTelemetry usługi Azure Monitor?.

Jak przetestować dystrybucję opentelemetrii usługi Azure Monitor?

Zapoznaj się z naszymi dokumentami dotyczącymi włączania dla platform .NET, Java, JavaScript (Node.js) i języka Python.

Czy należy używać interfejsu OpenTelemetry lub zestawu SDK usługi Application Szczegółowe informacje?

Zalecamy korzystanie z dystrybucji OpenTelemetry, chyba że wymagana jest funkcja dostępna tylko z obsługą formalną w zestawie SDK usługi Application Szczegółowe informacje.

Wdrażanie biblioteki OpenTelemetry teraz uniemożliwia przeprowadzenie migracji w późniejszym terminie.

Kiedy należy używać eksportera OpenTelemetry usługi Azure Monitor?

W przypadku ASP.NET Core, Java, Node.js i Python zalecamy użycie dystrybucji OpenTelemetry usługi Azure Monitor. Jest to jeden wiersz kodu, aby rozpocząć pracę.

W przypadku wszystkich innych scenariuszy platformy .NET, w tym klasycznych ASP.NET, aplikacji konsolowych itp., zalecamy użycie eksportera OpenTelemetry usługi Azure Monitor platformy .NET: Azure.Monitor.OpenTelemetry.Exporter.

W przypadku bardziej złożonych scenariuszy telemetrii języka Python wymagających zaawansowanej konfiguracji zalecamy użycie eksportera OpenTelemetry usługi Azure Monitor w języku Python.

Jaki jest bieżący stan wersji funkcji w usłudze Azure Monitor OpenTelemetry Distro?

Na poniższym wykresie przedstawiono obsługę funkcji OpenTelemetry dla każdego języka.

Funkcja .NET Node.js Python Java
Śledzenie rozproszone
Metryki niestandardowe
Metryki standardowe (dokładność, na którą ma obecnie wpływ próbkowanie)
Próbkowanie o stałej częstotliwości
Magazyn w trybie offline i automatyczne ponawianie prób
Raportowanie wyjątków
Zbieranie dzienników ⚠️
Zdarzenia niestandardowe ⚠️ ⚠️ ⚠️
Uwierzytelnianie Microsoft Entra
Metryki na żywo
Wykrywanie kontekstu zasobów dla maszyn wirtualnych/zestawu skalowania maszyn wirtualnych i usługi App Service
Wykrywanie kontekstu zasobów dla usługi AKS i funkcji
Filtrowanie zakresu testowania dostępności
Autopopulacji identyfikatora użytkownika, uwierzytelnionego identyfikatora użytkownika i adresu IP użytkownika
Ręcznie przesłoń/ustaw nazwę operacji, identyfikator użytkownika lub uwierzytelniony identyfikator użytkownika
Próbkowanie adaptacyjne
Profiler ⚠️
Debuger migawek

Klawisz

Czy można używać funkcji OpenTelemetry dla przeglądarek internetowych?

Tak, ale nie zalecamy jej i platforma Azure nie obsługuje jej. Język JavaScript openTelemetry jest mocno zoptymalizowany pod kątem Node.js. Zamiast tego zalecamy użycie zestawu SDK javaScript usługi Application Szczegółowe informacje.

Kiedy można oczekiwać, że zestaw SDK OpenTelemetry będzie dostępny do użycia w przeglądarkach internetowych?

Internetowy zestaw SDK openTelemetry nie ma ustalonej osi czasu dostępności. Prawdopodobnie istnieje kilka lat od zestawu SDK przeglądarki, który jest realną alternatywą dla zestawu SDK języka JavaScript usługi Application Szczegółowe informacje.

Czy mogę przetestować metrykę OpenTelemetry w przeglądarce internetowej dzisiaj?

Piaskownica internetowa OpenTelemetry to rozwidlenie przeznaczone do działania openTelemetry w przeglądarce. Nie można jeszcze wysyłać danych telemetrycznych do usługi Application Szczegółowe informacje. Zestaw SDK nie definiuje ogólnych zdarzeń klienta.

Czy działa aplikacja Szczegółowe informacje obok agentów konkurencji, takich jak AppDynamics, DataDog i NewRelic obsługiwane?

L.p. Ta praktyka nie jest czymś, co planujemy przetestować ani obsługiwać , chociaż nasze dystrybucje umożliwiają eksportowanie do punktu końcowego OTLP wraz z usługą Azure Monitor jednocześnie.

Czy mogę używać funkcji w wersji zapoznawczej w środowiskach produkcyjnych?

Nie zalecamy tego. Zobacz Dodatkowe warunki użytkowania dla wersji zapoznawczych platformy Microsoft Azure.

Jaka jest różnica między instrumentacją ręczną i automatyczną?

Zobacz Omówienie usługi OpenTelemetry.

Czy mogę użyć modułu zbierającego OpenTelemetry?

Niektórzy klienci używają modułu zbierającego OpenTelemetry jako alternatywy dla agenta, mimo że firma Microsoft oficjalnie nie obsługuje podejścia opartego na agencie do monitorowania aplikacji. W międzyczasie społeczność open source przyczyniła się do eksportera usługi Azure Monitor modułu zbierającego openTelemetry, którego niektórzy klienci używają do wysyłania danych do usługi Azure Monitor Application Szczegółowe informacje. Nie jest to obsługiwane przez firmę Microsoft.

Jaka jest różnica między usługami OpenCensus i OpenTelemetry?

OpenCensus jest prekursorem OpenTelemetry. Firma Microsoft pomogła połączyć rozwiązania OpenTracing i OpenCensus w celu utworzenia biblioteki OpenTelemetry— jednego standardu obserwacji dla świata. Bieżący zestaw SDK języka Python zalecany w środowisku produkcyjnym dla usługi Azure Monitor jest oparty na usłudze OpenCensus. Firma Microsoft zobowiązuje się do tworzenia usługi Azure Monitor na podstawie biblioteki OpenTelemetry.

Rozwiązywanie problemów

Nie działa? Zapoznaj się ze stroną rozwiązywania problemów dla ASP.NET Core.

Pomoc techniczna

Wybierz kartę dla wybranego języka, aby odnaleźć opcje pomocy technicznej.

  • W przypadku problemów z pomoc techniczna platformy Azure otwórz bilet pomoc techniczna platformy Azure.
  • W przypadku problemów z usługą OpenTelemetry skontaktuj się bezpośrednio ze społecznością platformy .NET OpenTelemetry.
  • Aby uzyskać listę otwartych problemów związanych z eksporterem usługi Azure Monitor, zobacz stronę Problemów z usługą GitHub.

Opinie dotyczące usługi OpenTelemetry

Aby przekazać opinię: