Udostępnij za pośrednictwem

Migrowanie z zestawów SDK usługi Application Insights platformy .NET do usługi Azure Monitor OpenTelemetry

  • Artykuł

Ten przewodnik zawiera instrukcje krok po kroku dotyczące migrowania różnych aplikacji platformy .NET z używania zestawów SDK (Software Development Kit) usługi Application Insights do usługi Azure Monitor OpenTelemetry.

Oczekiwano podobnego środowiska instrumentacji OpenTelemetry usługi Azure Monitor, tak jak w przypadku zestawów SDK usługi Application Insights. Aby uzyskać więcej informacji i porównanie funkcji według funkcji, zobacz stan wydania funkcji.

  • ASP.NET Migracja core do dystrybucji OpenTelemetry usługi Azure Monitor. (Azure.Monitor.OpenTelemetry.AspNetCore Pakiet NuGet)
  • ASP.NET, konsola i migracja usługi WorkerService do eksportera OpenTelemetry usługi Azure Monitor. (Azure.Monitor.OpenTelemetry.Exporter Pakiet NuGet)

Jeśli rozpoczynasz pracę z usługą Application Insights i nie musisz migrować z klasycznego interfejsu API, zobacz Włączanie usługi Azure Monitor OpenTelemetry.

Wymagania wstępne

  • Aplikacja internetowa ASP.NET Core już instrumentowana za pomocą usługi Application Insights bez żadnych dostosowań
  • Aktywnie obsługiwana wersja platformy .NET

Napiwek

Nasza grupa produktów aktywnie szuka opinii na temat tej dokumentacji. Prześlij opinię lub otel@microsoft.com zobacz sekcję Pomoc techniczna .

Usuwanie zestawu SDK usługi Application Insights

Uwaga

Przed wykonaniem tych kroków upewnij się, że masz bieżącą kopię zapasową aplikacji.

  1. Usuwanie pakietów NuGet

    Microsoft.ApplicationInsights.AspNetCore Usuń pakiet z pliku csproj.

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. Usuwanie kodu inicjowania i dostosowań

    Usuń wszelkie odwołania do typów usługi Application Insights w bazie kodu.

    Napiwek

    Po usunięciu pakietu usługi Application Insights możesz ponownie skompilować aplikację, aby uzyskać listę odwołań, które należy usunąć.

    • Usuń usługę Application Insights z usługi ServiceCollection , usuwając następujący wiersz:

      builder.Services.AddApplicationInsightsTelemetry();

    • Usuń sekcję ApplicationInsights z pliku appsettings.json.

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

  3. Czyszczenie i kompilowanie

    Sprawdź katalog bin, aby sprawdzić, czy wszystkie odwołania do Microsoft.ApplicationInsights.* zostały usunięte.

  4. Testowanie aplikacji

    Sprawdź, czy aplikacja nie ma nieoczekiwanych konsekwencji.

Napiwek

Nasza grupa produktów aktywnie szuka opinii na temat tej dokumentacji. Prześlij opinię lub otel@microsoft.com zobacz sekcję Pomoc techniczna .

Włączanie funkcji OpenTelemetry

Zalecamy utworzenie zasobu programistycznego i użycie jego parametry połączenia podczas wykonywania tych instrukcji.

Zrzut ekranu przedstawiający przegląd usługi Application Insights i parametry połączenia.

Zaplanuj zaktualizowanie parametry połączenia w celu wysłania danych telemetrycznych do oryginalnego zasobu po potwierdzeniu pomyślnej migracji.

  1. Instalowanie dystrybucji usługi Azure Monitor

    Nasza dystrybucja usługi Azure Monitor umożliwia automatyczne telemetrię, włączając biblioteki instrumentacji OpenTelemetry do zbierania śladów, metryk, dzienników i wyjątków oraz umożliwia zbieranie niestandardowych danych telemetrycznych.

    Zainstalowanie dystrybucji usługi Azure Monitor powoduje, że zestaw OPENTelemetry SDK jest zależnością.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Dodawanie i konfigurowanie zarówno biblioteki OpenTelemetry, jak i usługi Azure Monitor

    Zestaw OpenTelemery SDK należy skonfigurować podczas uruchamiania aplikacji w ramach ServiceCollectionelementu , zazwyczaj w elemencie Program.cs.

    OpenTelemetry ma pojęcie trzech sygnałów; Ślady, metryki i dzienniki. Dystrybucja usługi Azure Monitor konfiguruje każdy z tych sygnałów.

Program.cs

W poniższym przykładzie kodu przedstawiono podstawy.

using Azure.Monitor.OpenTelemetry.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // Call AddOpenTelemetry() to add OpenTelemetry to your ServiceCollection.
        // Call UseAzureMonitor() to fully configure OpenTelemetry.
        builder.Services.AddOpenTelemetry().UseAzureMonitor();

        var app = builder.Build();
        app.MapGet("/", () => "Hello World!");
        app.Run();
    }
}

Zalecamy ustawienie parametrów połączenia w zmiennej środowiskowej:

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Więcej opcji konfigurowania parametrów połączenia można znaleźć tutaj: Konfigurowanie parametrów połączenia usługi Application Insights.

Napiwek

Nasza grupa produktów aktywnie szuka opinii na temat tej dokumentacji. Prześlij opinię lub otel@microsoft.com zobacz sekcję Pomoc techniczna .

Instalowanie i konfigurowanie bibliotek instrumentacji

Biblioteki instrumentacji można dodać do projektu, aby automatycznie zbierać dane telemetryczne dotyczące określonych składników lub zależności.

Następujące biblioteki znajdują się w dystrybucji.

Dostosowywanie bibliotek instrumentacji

Dystrybucja usługi Azure Monitor obejmuje instrumentację platformy .NET OpenTelemetry dla platformy ASP.NET Core, HttpClient i SQLClient. Możesz dostosować te dołączone instrumentacje lub ręcznie dodać dodatkową instrumentację samodzielnie przy użyciu interfejsu API OpenTelemetry.

Oto kilka przykładów dostosowywania instrumentacji:

Dostosowywanie elementu AspNetCoreTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<AspNetCoreTraceInstrumentationOptions>(options =>
{
    options.RecordException = true;
    options.Filter = (httpContext) =>
    {
        // only collect telemetry about HTTP GET requests
        return HttpMethods.IsGet(httpContext.Request.Method);
    };
});
Dostosowywanie elementu HttpClientTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<HttpClientTraceInstrumentationOptions>(options =>
{
    options.RecordException = true;
    options.FilterHttpRequestMessage = (httpRequestMessage) =>
    {
        // only collect telemetry about HTTP GET requests
        return HttpMethods.IsGet(httpRequestMessage.Method.Method);
    };
});
Dostosowywanie obiektów SqlClientInstrumentationOptions

Dostawca instrumentacji SQLClient w pakiecie jest nadal w wersji beta. Gdy osiągnie stabilną wersję, dołączymy ją jako standardowe odwołanie do pakietu. Do tego czasu, aby dostosować instrumentację SQLClient, dodaj OpenTelemetry.Instrumentation.SqlClient odwołanie do pakietu do projektu i użyj jego publicznego interfejsu API.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

builder.Services.AddOpenTelemetry().UseAzureMonitor().WithTracing(builder =>
{
    builder.AddSqlClientInstrumentation(options =>
    {
        options.SetDbStatementForStoredProcedure = false;
    });
});

Konfigurowanie usługi Azure Monitor

Usługa Application Insights oferuje wiele innych opcji konfiguracji za pośrednictwem programu ApplicationInsightsServiceOptions.

Ustawienie usługi Application Insights Alternatywa openTelemetry
AddAutoCollectedMetricExtractor Nie dotyczy
ApplicationVersion Ustaw wartość "service.version" w obszarze Zasób
ConnectionString Zobacz instrukcje dotyczące konfigurowania parametrów połączenia.
DependencyCollectionOptions Nie dotyczy. Aby dostosować zależności, zapoznaj się z dostępnymi opcjami konfiguracji dla odpowiednich bibliotek instrumentacji.
DeveloperMode Nie dotyczy
EnableActiveTelemetryConfigurationSetup Nie dotyczy
EnableAdaptiveSampling Nie dotyczy. Obsługiwane jest tylko próbkowanie o stałej szybkości.
EnableAppServicesHeartbeatTelemetryModule Nie dotyczy
EnableAuthenticationTrackingJavaScript Nie dotyczy
WłączAzureInstanceMetadataTelemetryModule Nie dotyczy
EnableDependencyTrackingTelemetryModule Zobacz instrukcje dotyczące filtrowania śladów.
EnableDiagnosticsTelemetryModule Nie dotyczy
EnableEventCounterCollectionModule Nie dotyczy
WłączHeartbeat Nie dotyczy
EnablePerformanceCounterCollectionModule Nie dotyczy
EnableQuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule Zobacz instrukcje dotyczące filtrowania śladów.
EndpointAddress Użyj parametru ConnectionString.
InstrumentationKey Użyj parametru ConnectionString.
RequestCollectionOptions Nie dotyczy. Zobacz Opcje OpenTelemetry.Instrumentation.AspNetCore.

Usuwanie konfiguracji niestandardowych

Poniższe scenariusze są opcjonalne i mają zastosowanie tylko do użytkowników zaawansowanych.

  • Jeśli masz więcej odwołań do obiektu , którego można użyć do ręcznego TelemetryClientrejestrowania danych telemetrycznych, należy je usunąć.

  • Jeśli dodano jakiekolwiek niestandardowe filtrowanie lub wzbogacanie w postaci niestandardowej TelemetryProcessor lub TelemetryInitializer, należy je usunąć. Można je znaleźć w pliku ServiceCollection.

    builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • Usuwanie fragmentu kodu JavaScript

    Jeśli użyto fragmentu kodu dostarczonego przez zestaw SDK platformy .NET usługi Application Insights, należy go również usunąć. Aby uzyskać pełne przykłady kodu, które należy usunąć, zapoznaj się z przewodnikiem dotyczącym włączania telemetrii po stronie klienta dla aplikacji internetowych.

    Jeśli zestaw SDK języka JavaScript został dodany do zbierania danych telemetrycznych po stronie klienta, można go również usunąć, mimo że nadal działa bez zestawu SDK platformy .NET. Aby uzyskać pełne przykłady kodu, które należy usunąć, zapoznaj się z przewodnikiem dołączania dla zestawu SDK języka JavaScript.

  • Usuwanie wszystkich artefaktów programu Visual Studio

    Jeśli do dołączenia do usługi Application Insights użyto programu Visual Studio, w projekcie może być pozostawionych więcej plików.

    • Properties/ServiceDependencies katalog może mieć odwołanie do zasobu usługi Application Insights.

Napiwek

Nasza grupa produktów aktywnie szuka opinii na temat tej dokumentacji. Prześlij opinię lub otel@microsoft.com zobacz sekcję Pomoc techniczna .

Często zadawane pytania

Ta sekcja dotyczy klientów korzystających z inicjatorów lub procesorów telemetrii albo pisania niestandardowego kodu względem klasycznego interfejsu API usługi Application Insights w celu utworzenia niestandardowej telemetrii.

Jak mapowanie interfejsu API zestawu SDK na pojęcia openTelemetry?

OpenTelemetry to neutralna platforma obserwacji dostawcy. W zestawie OPENTelemetry SDK ani bibliotekach nie ma interfejsów API usługi Application Insights. Przed migracją ważne jest zrozumienie niektórych pojęć związanych z platformą OpenTelemetry.

  • W usłudze Application Insights wszystkie dane telemetryczne były zarządzane za pomocą jednego TelemetryClient elementu i TelemetryConfiguration. W usłudze OpenTelemetry każda z trzech sygnałów telemetrii (ślady, metryki i dzienniki) ma własną konfigurację. Dane telemetryczne można tworzyć ręcznie za pośrednictwem środowiska uruchomieniowego platformy .NET bez bibliotek zewnętrznych. Aby uzyskać więcej informacji, zobacz przewodniki platformy .NET dotyczące śledzenia rozproszonego, metryk i rejestrowania.

  • Usługa Application Insights używana TelemetryModules do automatycznego zbierania danych telemetrycznych dla aplikacji. Zamiast tego funkcja OpenTelemetry używa bibliotek instrumentacji do zbierania danych telemetrycznych z określonych składników (takich jak AspNetCore dla żądań i httpClient dla zależności).

  • Usługa Application Insights służy TelemetryInitializers do wzbogacania danych telemetrycznych dodatkowymi informacjami lub zastępowania właściwości. Za pomocą funkcji OpenTelemetry można napisać procesor w celu dostosowania określonego sygnału. Ponadto wiele bibliotek instrumentacji OpenTelemetry oferuje metodę Enrich dostosowywania telemetrii wygenerowanej przez ten konkretny składnik.

  • Usługa Application Insights służy TelemetryProcessors do filtrowania danych telemetrycznych. Procesor OpenTelemetry może również służyć do stosowania reguł filtrowania na określonym sygnałie.

Jak typy telemetrii usługi Application Insights mapują się na metryę OpenTelemetry?

Ta tabela mapuje typy danych usługi Application Insights na pojęcia openTelemetry i ich implementacje platformy .NET.

Tabela usługi Azure Monitor Typ danych usługi Application Insights Typ danych OpenTelemetry Implementacja platformy .NET
customEvents EventTelemetry Brak Brak
customMetrics MetrykaTelemetria Metryki System.Diagnostics.Metrics.Meter
zależności DependencyTelemetry Zakresy (klient, wewnętrzny, konsument) System.Diagnostics.Activity
wyjątki WyjątekTelemetria Wyjątki System.Exception
żądania RequestTelemetry Zakresy (serwer, producent) System.Diagnostics.Activity
traces TraceTelemetry Dzienniki Microsoft.Extensions.Logging.ILogger

Poniższe dokumenty zawierają więcej informacji.

Jak pojęcia dotyczące próbkowania usługi Application Insights są mapowanie na metryę OpenTelemetry?

Chociaż usługa Application Insights oferuje wiele opcji konfigurowania próbkowania, eksporter usługi Azure Monitor lub dystrybucja usługi Azure Monitor oferuje tylko próbkowanie o stałej szybkości. Można próbkować tylko żądania i zależności (ślady OpenTelemetry).

Aby uzyskać przykłady kodu zawierające szczegółowe informacje na temat konfigurowania próbkowania, zobacz nasz przewodnik Włączanie próbkowania

Jak procesory telemetryczne i inicjatory mapują na bibliotekę OpenTelemetry?

W zestawie SDK platformy .NET usługi Application Insights użyj procesorów telemetrycznych, aby filtrować i modyfikować lub odrzucać dane telemetryczne. Użyj inicjatorów telemetrii, aby dodać lub zmodyfikować właściwości niestandardowe. Aby uzyskać więcej informacji, zobacz dokumentację usługi Azure Monitor. Funkcja OpenTelemetry zastępuje te pojęcia procesorami aktywności lub dzienników, które wzbogacają i filtrują dane telemetryczne.

Filtrowanie śladów

Aby filtrować dane telemetryczne w usłudze OpenTelemetry, można zaimplementować procesor działań. Ten przykład jest odpowiednikiem przykładu usługi Application Insights na potrzeby filtrowania danych telemetrycznych zgodnie z opisem w dokumentacji usługi Azure Monitor. W przykładzie pokazano, gdzie są filtrowane nieudane wywołania zależności.

using System.Diagnostics;
using OpenTelemetry;

internal sealed class SuccessfulDependencyFilterProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        if (!OKtoSend(activity))
        {
            activity.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded;
        }
    }

    private bool OKtoSend(Activity activity)
    {
        return activity.Kind == ActivityKind.Client && activity.Status == ActivityStatusCode.Ok;
    }
}

Aby użyć tego procesora, należy utworzyć TracerProvider procesor i dodać go przed AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

public static void Main()
{
    var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddProcessor(new SuccessfulDependencyFilterProcessor())
        .AddAzureMonitorTraceExporter()
        .Build();
}

Filtrowanie dzienników

ILogger implementacje mają wbudowany mechanizm stosowania filtrowania dzienników. Dzięki temu filtrowaniu można kontrolować dzienniki wysyłane do każdego zarejestrowanego dostawcy, w tym .OpenTelemetryLoggerProvider "OpenTelemetry" to alias dla OpenTelemetryLoggerProviderelementu , używany podczas konfigurowania reguł filtrowania.

W poniższym przykładzie zdefiniowano wartość domyślną LogLevel "Błąd", a także zdefiniowano "Ostrzeżenie" jako minimum LogLevel dla kategorii zdefiniowanej przez użytkownika. Te reguły zgodnie z definicją dotyczą tylko elementu OpenTelemetryLoggerProvider.

builder.AddFilter<OpenTelemetryLoggerProvider>("*", LogLevel.Error);
builder.AddFilter<OpenTelemetryLoggerProvider>("MyProduct.MyLibrary.MyClass", LogLevel.Warning);

Aby uzyskać więcej informacji, przeczytaj dokumentację platformy .NET openTelemetry dotyczącą dzienników.

Dodawanie właściwości niestandardowych do śladów

W usłudze OpenTelemetry można użyć procesorów działań, aby wzbogacić dane telemetryczne o więcej właściwości. Jest on podobny do używania inicjatorów telemetrii w usłudze Application Insights, gdzie można modyfikować właściwości telemetrii.

Domyślnie eksporter usługi Azure Monitor flaguje każde żądanie HTTP z kodem odpowiedzi 400 lub większym, jak niepowodzenie. Jeśli jednak chcesz traktować wartość 400 jako sukces, możesz dodać wzbogacający procesor działań, który ustawia powodzenie działania i dodaje tag w celu uwzględnienia większej liczby właściwości telemetrii. Podobnie jak dodawanie lub modyfikowanie właściwości za pomocą inicjatora w usłudze Application Insights zgodnie z opisem w dokumentacji usługi Azure Monitor.

Oto przykład dodawania właściwości niestandardowych i zastępowania domyślnego zachowania niektórych kodów odpowiedzi:

using System.Diagnostics;
using OpenTelemetry;

/// <summary>
/// Custom Processor that overrides the default behavior of treating response codes >= 400 as failed requests.
/// </summary>
internal class MyEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        if (activity.Kind == ActivityKind.Server)
        {
            int responseCode = GetResponseCode(activity);

            if (responseCode >= 400 && responseCode < 500)
            {
                // If we set the Success property, the SDK won't change it
                activity.SetStatus(ActivityStatusCode.Ok);

                // Allow to filter these requests in the portal
                activity.SetTag("Overridden400s", "true");
            }

            // else leave the SDK to set the Success property
        }
    }

    private int GetResponseCode(Activity activity)
    {
        foreach (ref readonly var tag in activity.EnumerateTagObjects())
        {
            if (tag.Key == "http.response.status_code" && tag.Value is int value)
            {
                return value;
            }
        }

        return 0;
    }
}

Aby użyć tego procesora, należy utworzyć TracerProvider procesor i dodać go przed AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

public static void Main()
{
    var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddSource("Company.Product.Name")
        .AddProcessor(new MyEnrichingProcessor())
        .AddAzureMonitorTraceExporter()
        .Build();
}

Jak mogę ręcznie śledzić dane telemetryczne przy użyciu biblioteki OpenTelemetry?

Wysyłanie śladów — ręczne

Ślady w usłudze Application Insights są przechowywane jako RequestTelemetry i DependencyTelemetry. W usłudze OpenTelemetry ślady są modelowane jako Span przy użyciu Activity klasy .

Platforma .NET OpenTelemetry wykorzystuje ActivitySource klasy i Activity do śledzenia, które są częścią środowiska uruchomieniowego platformy .NET. Takie podejście jest charakterystyczne, ponieważ implementacja platformy .NET integruje interfejs API śledzenia bezpośrednio z samym środowiskiem uruchomieniowym. Pakiet System.Diagnostics.DiagnosticSource umożliwia deweloperom ActivitySource tworzenie wystąpień i zarządzanie nimi Activity . Ta metoda zapewnia bezproblemowy sposób dodawania śledzenia do aplikacji platformy .NET bez polegania na bibliotekach zewnętrznych, stosując wbudowane możliwości ekosystemu platformy .NET. Aby uzyskać bardziej szczegółowe informacje, zapoznaj się z przewodnikami instrumentacji śledzenia rozproszonego.

Oto jak przeprowadzić migrację śledzenia ręcznego:

Uwaga

W usłudze Application Insights można ustawić nazwę roli i wystąpienie roli na poziomie telemetrii. Jednak w przypadku eksportera usługi Azure Monitor nie możemy dostosować się na poziomie telemetrii. Nazwa roli i wystąpienie roli są wyodrębniane z zasobu OpenTelemetry i stosowane we wszystkich telemetrii. Przeczytaj ten dokument, aby uzyskać więcej informacji: Ustawianie nazwy roli chmury i wystąpienia roli w chmurze.

DependencyTelemetry

Usługa Application Insights DependencyTelemetry służy do modelowania żądań wychodzących. Oto jak przekonwertować go na metryę OpenTelemetry:

Przykład usługi Application Insights:

DependencyTelemetry dep = new DependencyTelemetry
{
   Name = "DependencyName",
   Data = "https://www.example.com/",
   Type = "Http",
   Target = "www.example.com",
   Duration = TimeSpan.FromSeconds(10),
   ResultCode = "500",
   Success = false
};

dep.Context.Cloud.RoleName = "MyRole";
dep.Context.Cloud.RoleInstance = "MyRoleInstance";
dep.Properties["customprop1"] = "custom value1";
client.TrackDependency(dep);

Przykład openTelemetry:

var activitySource = new ActivitySource("Company.Product.Name");
var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .SetResourceBuilder(resourceBuilder)
  .AddSource(activitySource.Name)
  .AddAzureMonitorTraceExporter()
  .Build();

// Emit traces
using (var activity = activitySource.StartActivity("DependencyName", ActivityKind.Client))
{
  activity?.SetTag("url.full", "https://www.example.com/");
  activity?.SetTag("server.address", "www.example.com");
  activity?.SetTag("http.request.method", "GET");
  activity?.SetTag("http.response.status_code", "500");
  activity?.SetTag("customprop1", "custom value1");
  activity?.SetStatus(ActivityStatusCode.Error);
  activity?.SetEndTime(activity.StartTimeUtc.AddSeconds(10));
}

RequestTelemetry

Usługa Application Insights RequestTelemetry modeluje żądania przychodzące. Oto jak przeprowadzić migrację do biblioteki OpenTelemetry:

Przykład usługi Application Insights:

RequestTelemetry req = new RequestTelemetry
{
   Name = "RequestName",
   Url = new Uri("http://example.com"),
   Duration = TimeSpan.FromSeconds(10),
   ResponseCode = "200",
   Success = true,
   Properties = { ["customprop1"] = "custom value1" }
};

req.Context.Cloud.RoleName = "MyRole";
req.Context.Cloud.RoleInstance = "MyRoleInstance";
client.TrackRequest(req);

Przykład openTelemetry:

var activitySource = new ActivitySource("Company.Product.Name");
var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .SetResourceBuilder(resourceBuilder)
  .AddSource(activitySource.Name)
  .AddAzureMonitorTraceExporter()
  .Build();

// Emit traces
using (var activity = activitySource.StartActivity("RequestName", ActivityKind.Server))
{
  activity?.SetTag("url.scheme", "https");
  activity?.SetTag("server.address", "www.example.com");
  activity?.SetTag("url.path", "/");
  activity?.SetTag("http.response.status_code", "200");
  activity?.SetTag("customprop1", "custom value1");
  activity?.SetStatus(ActivityStatusCode.Ok);
}

Niestandardowe śledzenie operacji

W usłudze Application Insights śledź operacje niestandardowe przy użyciu metod StartOperation i .StopOperation Osiągnij go przy użyciu platformy ActivitySource .NET i Activity w programie OpenTelemetry. W przypadku operacji za pomocą ActivityKind.Server poleceń i ActivityKind.Consumereksporter usługi Azure Monitor generuje RequestTelemetrywartość . W przypadku parametrów ActivityKind.ClientDependencyTelemetry, ActivityKind.Produceri ActivityKind.Internalgeneruje wartość . Aby uzyskać więcej informacji na temat śledzenia operacji niestandardowych, zobacz dokumentację usługi Azure Monitor. Aby uzyskać więcej informacji na temat korzystania z platformy ActivitySource .NET i Activity na platformie .NET, zobacz przewodniki dotyczące instrumentacji śledzenia rozproszonego platformy .NET.

Oto przykład uruchamiania i zatrzymywania działania dla operacji niestandardowych:

using System.Diagnostics;
using OpenTelemetry;

var activitySource = new ActivitySource("Company.Product.Name");

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(activitySource.Name)
    .AddAzureMonitorTraceExporter()
    .Build();

// Start a new activity
using (var activity = activitySource.StartActivity("CustomOperation", ActivityKind.Server))
{
    activity?.SetTag("customTag", "customValue");

    // Perform your custom operation logic here

    // No need to explicitly call Activity.Stop() because the using block automatically disposes the Activity object, which stops it.
}

Wysyłanie dzienników

Dzienniki w usłudze Application Insights są przechowywane jako TraceTelemetry i ExceptionTelemetry.

TraceTelemetry

W programie OpenTelemetry rejestrowanie jest zintegrowane za pośrednictwem interfejsu ILogger . Oto jak przeprowadzić migrację TraceTelemetry:

Przykład usługi Application Insights:

TraceTelemetry traceTelemetry = new TraceTelemetry
{
   Message = "hello from tomato 2.99",
   SeverityLevel = SeverityLevel.Warning,
};

traceTelemetry.Context.Cloud.RoleName = "MyRole";
traceTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";
client.TrackTrace(traceTelemetry);

Przykład openTelemetry:

var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var loggerFactory = LoggerFactory.Create(builder => builder
   .AddOpenTelemetry(logging =>
   {
       logging.SetResourceBuilder(resourceBuilder);
       logging.AddAzureMonitorLogExporter();
   }));

// Create a new instance `ILogger` from the above LoggerFactory
var logger = loggerFactory.CreateLogger<Program>();

// Use the logger instance to write a new log
logger.FoodPrice("tomato", 2.99);

internal static partial class LoggerExtensions
{
    [LoggerMessage(LogLevel.Warning, "Hello from `{name}` `{price}`.")]
    public static partial void FoodPrice(this ILogger logger, string name, double price);
}
WyjątekTelemetria

Usługa Application Insights używa ExceptionTelemetry do rejestrowania wyjątków. Oto jak przeprowadzić migrację do biblioteki OpenTelemetry:

Przykład usługi Application Insights:

ExceptionTelemetry exceptionTelemetry = new ExceptionTelemetry(new Exception("Test exception"))
{
    SeverityLevel = SeverityLevel.Error
};

exceptionTelemetry.Context.Cloud.RoleName = "MyRole";
exceptionTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";
exceptionTelemetry.Properties["customprop1"] = "custom value1";
client.TrackException(exceptionTelemetry);

Przykład openTelemetry:

var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var loggerFactory = LoggerFactory.Create(builder => builder
   .AddOpenTelemetry(logging =>
   {
       logging.SetResourceBuilder(resourceBuilder);
       logging.AddAzureMonitorLogExporter();
   }));

// Create a new instance `ILogger` from the above LoggerFactory.
var logger = loggerFactory.CreateLogger<Program>();

try
{
    // Simulate exception
    throw new Exception("Test exception");
}
catch (Exception ex)
{
    logger?.LogError(ex, "An error occurred");
}

Wysyłanie metryk

Metryki w usłudze Application Insights są przechowywane jako MetricTelemetry. W usłudze OpenTelemetry metryki są modelowane zgodnie Meter z pakietem System.Diagnostics.DiagnosticSource .

Usługa Application Insights ma interfejsy API metrykTrackMetric() inne niż wstępne () i wstępne agregowanie (GetMetric().TrackValue()). W przeciwieństwie do platformy OpenTelemetry usługa Application Insights nie ma pojęcia instrumentacja. Usługa Application Insights ma ten sam interfejs API dla wszystkich scenariuszy metryk.

Z drugiej strony funkcja OpenTelemetry wymaga od użytkowników uprzedniego wybrania odpowiedniego instrumentu metryki na podstawie rzeczywistej semantyki metryki. Jeśli na przykład intencją jest zliczenie czegoś (na przykład liczba odebranych żądań serwera itp.), należy użyć licznika OpenTelemetry. Jeśli intencją jest obliczenie różnych percentyli (takich jak wartość P99 opóźnienia serwera), należy użyć instrumentu Histogramu OpenTelemetry. Ze względu na tę podstawową różnicę między usługą Application Insights i usługą OpenTelemetry nie dokonano bezpośredniego porównania między nimi.

W przeciwieństwie do usługi Application Insights funkcja OpenTelemetry nie udostępnia wbudowanych mechanizmów wzbogacania ani filtrowania metryk. W usłudze Application Insights procesory telemetryczne i inicjatory mogą służyć do modyfikowania lub odrzucania metryk, ale ta funkcja nie jest dostępna w usłudze OpenTelemetry.

Ponadto funkcja OpenTelemetry nie obsługuje bezpośredniego wysyłania nieprzetworzonych metryk, ponieważ nie ma odpowiednika TrackMetric() funkcji znalezionych w usłudze Application Insights.

Migracja z usługi Application Insights do usługi OpenTelemetry obejmuje zastąpienie wszystkich użycia interfejsu API metryk usługi Application Insights interfejsem API OpenTelemetry. Wymaga to zrozumienia różnych instrumentów OpenTelemetry i ich semantyki.

Napiwek

Histogram jest najbardziej wszechstronny i najbliżej interfejsu API usługi Application Insights GetMetric().TrackValue() . Możesz zastąpić interfejsy API metryk usługi Application Insights histogramem, aby osiągnąć ten sam cel.

Inne typy telemetrii

CustomEvents

Nieobsługiwane w usłudze OpenTelemetry.

Przykład usługi Application Insights:

TelemetryClient.TrackEvent()
AvailabilityTelemetry

Nieobsługiwane w usłudze OpenTelemetry.

Przykład usługi Application Insights:

TelemetryClient.TrackAvailability()
PageViewTelemetry

Nieobsługiwane w usłudze OpenTelemetry.

Przykład usługi Application Insights:

TelemetryClient.TrackPageView()

Czy mogę uzyskać metryki na żywo dla aplikacji konsoli i usługi procesu roboczego?

Zalecamy eksportera OpenTelemetry usługi Azure Monitor dla aplikacji konsoli i usługi procesów roboczych, które nie zawierają metryk na żywo.

Następne kroki

Napiwek

Nasza grupa produktów aktywnie szuka opinii na temat tej dokumentacji. Prześlij opinię lub otel@microsoft.com zobacz sekcję Pomoc techniczna .

Pomoc techniczna

  • 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.