Udostępnij za pośrednictwem

Konfigurowanie usługi Azure Monitor OpenTelemetry

W tym przewodniku wyjaśniono, jak skonfigurować bibliotekę OpenTelemetry (OTel) w usłudze Azure Monitor Application Insights przy użyciu dystrybucji OpenTelemetry usługi Azure Monitor. Właściwa konfiguracja zapewnia spójne zbieranie danych telemetrycznych w aplikacjach .NET, Java, Node.jsi Python, co zapewnia bardziej niezawodne monitorowanie i diagnostykę.

Uwaga

W przypadku aplikacji funkcji platformy Azure zobacz Use OpenTelemetry with Azure Functions (Używanie funkcji OpenTelemetry z usługą Azure Functions).

Ciąg połączenia

Parametry połączenia w usłudze Application Insights definiuje lokalizację docelową wysyłania danych telemetrycznych.

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

  • Dodaj UseAzureMonitor() do program.cs pliku:

    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>";
});

var app = builder.Build();

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

Ustaw nazwę roli chmurowej i instancję roli chmurowej

W przypadku obsługiwanych języków dystrybucja OpenTelemetry Azure Monitor automatycznie wykrywa kontekst zasobu i ustawia wartości domyślne dla właściwości Nazwa roli chmury i Właściwość wystąpienia roli chmury składnika. Możesz jednak zastąpić wartości domyślne na wartości, które będą sensowne 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 instancję roli chmury za pomocą atrybutów Resource. Nazwa roli chmury używa atrybutów service.namespace i service.name, ale przechodzi na service.name jeśli service.namespace nie jest ustawiony. 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 ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .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óbnik o stałej stopy, który wypełnia zdarzenia współczynnikiem próbkowania, a usługa Application Insights konwertuje ten współczynnik na wartość ItemCount. Próbkator o stałej wartości zapewnia dokładne doświadczenia i liczbę zdarzeń. Próbnik został zaprojektowany tak, aby zachować ślady pomiędzy usługami i jest zgodny ze starszymi zestawami SDK (Software Development Kits) usługi Application Insights. Aby uzyskać więcej informacji, zobacz Dowiedz się więcej o próbkowaniu.

Uwaga

Metryki i dzienniki są niezależne od próbkowania. Jeśli widzisz nieoczekiwane opłaty lub wysokie koszty w usłudze Application Insights, ten przewodnik może pomóc. Obejmuje ona typowe przyczyny, takie jak duża ilość danych telemetrycznych, skoki pozyskiwania danych i błędnie skonfigurowane próbkowanie. Jest to szczególnie przydatne, jeśli rozwiązujesz problemy związane ze wzrostem kosztów, ilością danych telemetrycznych, niedziałającym próbkowaniem, limitami danych, wysokim pozyskiwaniem lub nieoczekiwanymi rozliczeniami. Aby rozpocząć, zobacz Rozwiązywanie problemów z wysokim poziomem pobierania danych w usłudze Application Insights.

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(options =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.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 stawce lub procentowej, jeśli nie jesteś pewien, jaką ustawić częstotliwość próbkowania, zacznij od 5%. (Współczynnik próbkowania 0,05) Dostosuj szybkość na podstawie dokładności operacji wyświetlanych w okienkach błędów i wydajności. Wyższa stawka zwykle skutkuje wyższą dokładnością. Jednak każde próbkowanie ma wpływ na dokładność, dlatego zalecamy zgłaszanie alertów dotyczących metryk OpenTelemetry, które nie mają wpływu na próbkowanie.

Metryki na żywo

Metryki na żywo udostępnia pulpit nawigacyjny analizy w czasie rzeczywistym umożliwiający wgląd w aktywność aplikacji i wydajność.

Ważne

Zapoznaj się z dodatkowymi warunkami użytkowania dla wersji zapoznawczych platformy Microsoft Azure , aby zapoznać się z postanowieniami prawnymi dotyczącymi funkcji platformy Azure, które są w wersji beta, wersji zapoznawczej lub w inny sposób nie zostały jeszcze wydane w wersji ogólnodostępnej.

Ten funkcjonalność jest włączona domyślnie.

Użytkownicy mogą wyłączyć Live Metrics podczas konfigurowania dystrybucji.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

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

Możesz włączyć uwierzytelnianie Entra firmy Microsoft, aby uzyskać bezpieczniejsze połączenie z platformą Azure, co zapobiega przetwarzaniu nieautoryzowanych danych telemetrycznych w Twojej subskrypcji.

Aby uzyskać więcej informacji, zobacz dedykowaną stronę uwierzytelniania Entra firmy Microsoft, połączoną z każdą obsługiwaną wersją językową.

Aby uzyskać informacje na temat konfigurowania uwierzytelniania entra ID, zobacz Microsoft Entra authentication for Application Insights (Uwierzytelnianie entra firmy Microsoft dla usługi Application Insights)

Przechowywanie w trybie offline i automatyczne ponawianie prób

Usługi Azure Monitor oparte na OpenTelemetry buforują dane telemetryczne, gdy aplikacja rozłącza się z usługą Application Insights i przez maksymalnie 48 godzin ponawiają próby ich wysłania. Aby uzyskać zalecenia dotyczące obsługi danych, zobacz Eksportowanie i usuwanie danych prywatnych. Aplikacje o dużym obciążeniu od czasu do czasu upuszczają dane telemetryczne z dwóch powodów: przekroczenie dozwolonego czasu lub przekroczenie maksymalnego rozmiaru pliku. W razie potrzeby produkt określa priorytety ostatnich zdarzeń nad starymi.

Pakiet Distro zawiera eksporter AzureMonitorExporter, który domyślnie używa jednej z następujących lokalizacji do przechowywania offline (wymienionych w kolejności pierwszeństwa):

  • Windows
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • Nie-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 wspieramy oficjalnie eksportera OTLP ani żadnych jego składników, ani doświadczeń innych firm, które na nim bazują.

  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 usługi Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Aby zrezygnować z wewnętrznego zbierania metryk, ustaw to na true.
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 jest również podany w OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME ma pierwszeństwo.

Redaguj ciągi zapytań URL

Aby zredagować ciągi zapytania adresu URL, wyłącz zbieranie ciągów zapytania. Zalecamy to ustawienie, jeśli wywołasz usługę Azure Storage przy użyciu tokenu SAS.

W przypadku korzystania z pakietu dystrybucyjnego Azure.Monitor.OpenTelemetry.AspNetCore zawiera zarówno biblioteki ASP.NET Core, jak i HttpClient Instrumentation. Nasz pakiet dystrybucyjny domyślnie wyłącza anonimizację ciągów zapytań.

Aby zmienić to zachowanie, należy ustawić zmienną środowiskową na wartość true lub false.

  • ASP.NET Instrumentacja podstawowa: OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION redakcja ciągu zapytania jest domyślnie wyłączona. Aby włączyć, ustaw tę zmienną środowiskową na falsewartość .
  • Instrumentacja klienta HTTP: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION redakcja ciągu zapytania jest domyślnie wyłączona. Aby włączyć, ustaw tę zmienną środowiskową na falsewartość .