Dodawanie, modyfikowanie i filtrowanie danych OpenTelemetry

  • Artykuł

Ten artykuł zawiera wskazówki dotyczące dodawania, modyfikowania i filtrowania biblioteki OpenTelemetry dla aplikacji przy użyciu usługi Azure Monitor Application Insights.

Aby dowiedzieć się więcej na temat pojęć związanych z platformą OpenTelemetry, zobacz Temat OpenTelemetry overview (Omówienie usługi OpenTelemetry) lub OpenTelemetry FAQ (Często zadawane pytania dotyczące platformy OpenTelemetry).

Automatyczne zbieranie danych

Dystrybucje automatycznie zbierają dane przez łączenie bibliotek instrumentacji OpenTelemetry.

Uwzględnione biblioteki instrumentacji

Żądania

Zależności

Rejestrowanie

  • ILogger

Aby uzyskać więcej informacji na temat ILoggerprogramu , zobacz Rejestrowanie w językach C# i .NET oraz przykłady kodu.

Przypisy dolne

  • ¹: Obsługuje automatyczne raportowanie nieobsługiwane/nieuchwycone wyjątki
  • ²: Obsługuje metryki OpenTelemetry
  • ³: Domyślnie rejestrowanie jest zbierane tylko na poziomie INFO lub wyższym. Aby zmienić to ustawienie, zobacz opcje konfiguracji.
  • ⁴: Domyślnie rejestrowanie jest zbierane tylko wtedy, gdy rejestrowanie jest wykonywane na poziomie OSTRZEŻENIA lub wyższym.

Uwaga

Dystrybucje OpenTelemetry usługi Azure Monitor obejmują mapowanie niestandardowe i logikę, aby automatycznie emitować standardowe metryki usługi Application Insights.

Napiwek

Wszystkie metryki OpenTelemetry, niezależnie od tego, czy są automatycznie zbierane z bibliotek instrumentacji, czy ręcznie zbierane z niestandardowego kodowania, są obecnie traktowane jako "metryki niestandardowe" usługi Application Insights na potrzeby rozliczeń. Dowiedz się więcej.

Dodawanie biblioteki instrumentacji społeczności

Więcej danych można zbierać automatycznie, dołączając biblioteki instrumentacji ze społeczności OpenTelemetry.

Uwaga

Nie obsługujemy ani nie gwarantujemy jakości bibliotek instrumentacji społeczności. Aby zasugerować jeden z naszych dystrybucji, post lub up-vote w naszej społeczności opinii. Należy pamiętać, że niektóre są oparte na eksperymentalnych specyfikacjach OpenTelemetry i mogą wprowadzać przyszłe zmiany powodujące niezgodność.

Aby dodać bibliotekę społeczności, użyj ConfigureOpenTelemetryMeterProvider metod lub ConfigureOpenTelemetryTracerProvider po dodaniu pakietu NuGet dla biblioteki.

W poniższym przykładzie pokazano, jak można dodać instrumentację środowiska uruchomieniowego w celu zbierania dodatkowych metryk:

dotnet add package OpenTelemetry.Instrumentation.Runtime 

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

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

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

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

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

Zbieranie niestandardowych danych telemetrycznych

W tej sekcji opisano sposób zbierania niestandardowych danych telemetrycznych z aplikacji.

W zależności od języka i typu sygnału istnieją różne sposoby zbierania niestandardowych danych telemetrycznych, w tym:

  • OpenTelemetry API
  • Biblioteki rejestrowania/metryk specyficzne dla języka
  • Klasyczny interfejs API usługi Application Insights

W poniższej tabeli przedstawiono obecnie obsługiwane niestandardowe typy telemetrii:

Język Zdarzenia niestandardowe Metryki niestandardowe Zależności Wyjątki Widoki stron Żądania Ślady
ASP.NET Core
   OpenTelemetry API Tak Tak Tak Tak
   ILogger API Tak
   Klasyczny interfejs API sztucznej inteligencji
Java
   OpenTelemetry API Tak Tak Tak Tak
   Logback, Log4j, JUL Tak Tak
   Metryki mikrometryczne Tak
   Klasyczny interfejs API sztucznej inteligencji Tak Tak Tak Tak Tak Tak Tak
Node.js
   OpenTelemetry API Tak Tak Tak Tak
Python
   OpenTelemetry API Tak Tak Tak Tak
   Moduł rejestrowania języka Python Tak
   Rozszerzenie zdarzeń Tak Tak

Uwaga

Usługa Application Insights Java 3.x nasłuchuje danych telemetrycznych wysyłanych do klasycznego interfejsu API usługi Application Insights. Podobnie usługa Application Insights Node.js 3.x zbiera zdarzenia utworzone za pomocą klasycznego interfejsu API usługi Application Insights. Ułatwia to uaktualnianie i wypełnia lukę w naszej niestandardowej obsłudze telemetrii, dopóki wszystkie niestandardowe typy telemetrii nie będą obsługiwane za pośrednictwem interfejsu API OpenTelemetry.

Dodawanie metryk niestandardowych

W tym kontekście termin metryk niestandardowych odnosi się do ręcznego instrumentowania kodu w celu zbierania dodatkowych metryk poza tym, co biblioteki instrumentacji OpenTelemetry automatycznie zbierają.

Interfejs API OpenTelemetry oferuje sześć metryk "instrumentów", które obejmują różne scenariusze metryk i należy wybrać prawidłowy typ agregacji podczas wizualizacji metryk w Eksploratorze metryk. To wymaganie jest prawdziwe w przypadku używania interfejsu API metryk OpenTelemetry do wysyłania metryk i używania biblioteki instrumentacji.

W poniższej tabeli przedstawiono zalecane typy agregacji dla każdego z instrumentów metryk OpenTelemetry.

OpenTelemetry Instrument Typ agregacji usługi Azure Monitor
Licznik Sum
Licznik asynchroniczny Sum
Histogram Minimalna, Maksymalna, Średnia, Suma i Liczba
Miernik asynchroniczny Średnia
UpDownCounter Sum
Asynchroniczne upDownCounter Sum

Uwaga

Typy agregacji wykraczające poza to, co pokazano w tabeli, zwykle nie mają znaczenia.

Specyfikacja OpenTelemetry opisuje instrumenty i zawiera przykłady użycia każdego z nich.

Napiwek

Histogram jest najbardziej wszechstronny i najbardziej zbliżony do klasycznego interfejsu API getmetric usługi Application Insights. Usługa Azure Monitor obecnie spłaszcza instrument histogramu do naszych pięciu obsługiwanych typów agregacji, a obsługa percentyli jest w toku. Chociaż mniej wszechstronny, inne instrumenty OpenTelemetry mają mniejszy wpływ na wydajność aplikacji.

Przykład histogramu

Uruchamianie aplikacji musi subskrybować miernik według nazwy:

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

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

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

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

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

Element Meter musi zostać zainicjowany przy użyciu tej samej nazwy:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Przykład licznika

Uruchamianie aplikacji musi subskrybować miernik według nazwy:

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

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

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

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

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

Element Meter musi zostać zainicjowany przy użyciu tej samej nazwy:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Przykład miernika

Uruchamianie aplikacji musi subskrybować miernik według nazwy:

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

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

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

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

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

Element Meter musi zostać zainicjowany przy użyciu tej samej nazwy:

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

Dodawanie wyjątków niestandardowych

Wybierz pozycję Biblioteki instrumentacji automatycznie zgłaszają wyjątki do usługi Application Insights. Można jednak ręcznie zgłaszać wyjątki poza raportem bibliotek instrumentacji. Na przykład wyjątki przechwycone przez kod nie są zwykle zgłaszane. Możesz zgłosić je, aby zwrócić uwagę na odpowiednie środowiska, w tym sekcję błędów i kompleksowe widoki transakcji.

  • Aby zarejestrować wyjątek przy użyciu działania:

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Aby zarejestrować wyjątek przy użyciu polecenia ILogger:

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Dodawanie zakresów niestandardowych

Możesz dodać niestandardowy zakres w dwóch scenariuszach. Po pierwsze, gdy istnieje żądanie zależności, które nie jest jeszcze zbierane przez bibliotekę instrumentacji. Po drugie, jeśli chcesz modelować proces aplikacji jako zakres w widoku kompleksowej transakcji.

Uwaga

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

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

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

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

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

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

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

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

StartActivity wartość domyślna to ActivityKind.Internal, ale można podać dowolną inną ActivityKindwartość . ActivityKind.Client, ActivityKind.Produceri ActivityKind.Internal są mapowane na usługę Application Insights dependencies. ActivityKind.Server i ActivityKind.Consumer są mapowane na usługę Application Insights requests.

Wysyłanie niestandardowych danych telemetrycznych przy użyciu klasycznego interfejsu API usługi Application Insights

Zalecamy korzystanie z interfejsów API OpenTelemetry, jeśli jest to możliwe, ale w przypadku konieczności korzystania z klasycznego interfejsu API usługi Application Insights może wystąpić kilka scenariuszy.

Wydarzenia

  1. Dodaj Microsoft.ApplicationInsights do aplikacji.

  2. Utwórz TelemetryClient wystąpienie:

    Uwaga

    Ważne jest, aby utworzyć tylko raz wystąpienie klasy TelemetryClient dla aplikacji.

    var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };
var telemetryClient = new TelemetryClient(telemetryConfiguration);

  3. Użyj klienta do wysyłania niestandardowych danych telemetrycznych:

    telemetryClient.TrackEvent("testEvent");

Modyfikowanie telemetrii

W tej sekcji opisano sposób modyfikowania danych telemetrycznych.

Dodawanie atrybutów zakresu

Te atrybuty mogą obejmować dodawanie właściwości niestandardowej do telemetrii. Atrybuty mogą również służyć do ustawiania pól opcjonalnych w schemacie usługi Application Insights, takich jak adres IP klienta.

Dodawanie właściwości niestandardowej do zakresu

Wszystkie atrybuty dodawane do zakresów są eksportowane jako właściwości niestandardowe. Wypełniają one pole customDimensions w tabeli żądań, zależności, śladów lub wyjątków.

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

  • Użyj opcji udostępnianych przez biblioteki instrumentacji.
  • Dodaj niestandardowy procesor span.

Napiwek

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 httpRequestMessage i samego httpResponseMessage . Mogą wybrać dowolne elementy i zapisać je jako atrybut.

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

  2. Użyj niestandardowego procesora:

    Napiwek

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

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

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

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

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

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

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

    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

Pole client_IP dla żądań można wypełnić, ustawiając atrybut w zakresie. Usługa Application Insights używa adresu IP do generowania atrybutów lokalizacji użytkownika, a następnie domyślnie go odrzuca.

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

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

Ustawianie identyfikatora użytkownika lub uwierzytelnioowanego identyfikatora użytkownika

Możesz wypełnić pole user_Id lub user_AuthenticatedId dla żądań, korzystając z poniższych wskazówek. Identyfikator użytkownika to anonimowy identyfikator użytkownika. Uwierzytelniony identyfikator użytkownika jest znanym identyfikatorem użytkownika.

Ważne

Zanim ustawisz uwierzytelniony identyfikator użytkownika, zapoznaj się z obowiązującymi przepisami dotyczącymi ochrony prywatności.

Użyj przykładu właściwości niestandardowej:

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

Dodawanie atrybutów dziennika

Funkcja OpenTelemetry używa elementu . Net's ILogger. Dołączanie wymiarów niestandardowych do dzienników można wykonać przy użyciu szablonu komunikatu.

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:

    Napiwek

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

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

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityFilteringProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityFilteringProcessor()));
// Configure the OpenTelemetry tracer provider to add a new source named "ActivitySourceName".
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));
// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

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

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

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

    public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
    // The OnStart method is called when an activity is started. This is the ideal place to filter activities.
    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 zostaną wyeksportowane.

Pobieranie identyfikatora śledzenia lub identyfikatora zakresu

Aby uzyskać Trace ID elementy i Span ID aktualnie aktywnego zakresu, wykonaj następujące kroki.

Uwaga

Klasy Activity i ActivitySource z System.Diagnostics przestrzeni nazw reprezentują odpowiednio pojęcia OpenTelemetry i Span Tracer. Wynika to z faktu, że części interfejsu API śledzenia OpenTelemetry są dołączane bezpośrednio do środowiska uruchomieniowego platformy .NET. Aby dowiedzieć się więcej, zobacz Wprowadzenie do interfejsu API śledzenia platformy .NET openTelemetry.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Następne kroki