Migrieren von .NET Application Insights SDKs zu Azure Monitor OpenTelemetry

  • Artikel

Dieser Leitfaden enthält eine Schritt-für-Schritt Anleitung für die Migration verschiedener .NET-Anwendungen von der Verwendung von Application Insights Software Development Kits (SDKs) zu Azure Monitor OpenTelemetry.

Die Azure Monitor OpenTelemetry-Instrumentierung bietet eine ähnliche Erfahrung wie die Application Insights SDKs. Weitere Informationen und einen featurespezifischen Vergleich finden Sie unter Wie lautet der aktuelle Releasestatus der Features in der OpenTelemetry-Distribution von Azure Monitor?.

Wenn Sie mit der Verwendung von Application Insights beginnen und nicht von der Classic API migrieren müssen, lesen Sie Aktivieren von Azure Monitor OpenTelemetry für .NET-, Node.js-, Python und Java-Anwendungen.

Voraussetzungen

  • Eine bereits mit Application Insights instrumentierte ASP.NET Core-Webanwendung ohne Anpassungen
  • Eine aktiv unterstützte Version von .NET

Tipp

Unsere Produktgruppe freut sich über Feedback zu dieser Dokumentation. Senden Sie Feedback an otel@microsoft.com, oder sehen Sie den Abschnitt Support an.

Entfernen des Application Insights SDK

Hinweis

Vergewissern Sie sich, dass Sie über eine aktuelle Sicherung Ihrer Anwendung verfügen, bevor Sie mit den hier beschriebenen Schritten fortfahren.

  1. Entfernen von NuGet-Paketen

    Entfernen Sie das Paket Microsoft.ApplicationInsights.AspNetCore aus csproj.

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. Entfernen von Initialisierungscode und Anpassungen

    Entfernen Sie alle Verweise auf Application Insights-Typen aus Ihrer Codebasis.

    Tipp

    Nachdem Sie das Application Insights-Paket entfernt haben, können Sie Ihre Anwendung neu erstellen, um eine Liste von Verweisen abzurufen, die entfernt werden müssen.

    • Entfernen Sie Application Insights aus ServiceCollection, indem Sie die folgende Zeile löschen:

      builder.Services.AddApplicationInsightsTelemetry();

    • Entfernen Sie den Abschnitt ApplicationInsights aus appsettings.json.

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

  3. Bereinigen und Erstellen

    Überprüfen Sie ihr Bin-Verzeichnis, um sich zu vergewissern, dass alle Verweise auf Microsoft.ApplicationInsights.* entfernt wurden.

  4. Testen Ihrer Anwendung

    Vergewissern Sie sich, dass Ihre Anwendung keine unerwarteten Auswirkungen hat.

Tipp

Unsere Produktgruppe freut sich über Feedback zu dieser Dokumentation. Senden Sie Feedback an otel@microsoft.com, oder sehen Sie den Abschnitt Support an.

Aktivieren von OpenTelemetry

Es wird empfohlen, eine Ressource für die Entwicklung zu erstellen und deren Verbindungszeichenfolge zu verwenden, wenn Sie dieser Anleitung folgen.

Screenshot, der die Application Insights-Übersicht und die Verbindungszeichenfolge zeigt.

Planen Sie ein, die Verbindungszeichenfolge zu aktualisieren, um Telemetriedaten an die ursprüngliche Ressource zu senden, nachdem Sie sich vergewissert haben, dass die Migration erfolgreich war.

  1. Installieren der Azure Monitor-Distribution

    Unsere Azure Monitor-Distribution ermöglicht die Verwendung automatischer Telemetriedaten durch Einbeziehung von OpenTelemetry-Instrumentierungsbibliotheken zum Sammeln von Ablaufverfolgungen, Metriken, Protokollen und Ausnahmen und ermöglicht auch das Sammeln benutzerdefinierter Telemetriedaten.

    Die Installation der Azure Monitor-Distribution ist mit dem OpenTelemetry SDK als Abhängigkeit verbunden.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Hinzufügen und Konfigurieren von OpenTelemetry und Azure Monitor

    Das OpenTelemery SDK muss beim Starten der Anwendung als Teil von ServiceCollection konfiguriert werden (in der Regel in der Datei Program.cs).

    Das Konzept von OpenTelemetry umfasst drei Signale: Ablaufverfolgungen, Metriken und Protokolle. Die Azure Monitor-Distribution konfiguriert jedes dieser Signale.

Program.cs

Im folgenden Codebeispiel werden die Grundlagen veranschaulicht:

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

Es empfiehlt sich, die Verbindungszeichenfolge in einer Umgebungsvariablen festzulegen:

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Weitere Optionen zum Konfigurieren der Verbindungszeichenfolge finden Sie hier.

Tipp

Unsere Produktgruppe freut sich über Feedback zu dieser Dokumentation. Senden Sie Feedback an otel@microsoft.com, oder sehen Sie den Abschnitt Support an.

Installieren und Konfigurieren von Instrumentierungsbibliotheken

Instrumentierungsbibliotheken können Ihrem Projekt hinzugefügt werden, um automatisch Telemetriedaten zu bestimmten Komponenten oder Abhängigkeiten zu sammeln.

Folgende Bibliotheken sind in der Distribution enthalten:

Anpassen von Instrumentierungsbibliotheken

Die Azure Monitor-Distribution beinhaltet die .NET OpenTelemetry-Instrumentierung für ASP.NET Core, HttpClient und SQLClient. Sie können diese enthaltenen Instrumentierungen anpassen oder mithilfe der OpenTelemetry-API manuell eine zusätzliche Instrumentierung hinzufügen.

Hier sind einige Beispiele für die Anpassung der Instrumentierung:

Anpassen von 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);
    };
});
Anpassen von 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);
    };
});
Anpassen von SqlClientInstrumentationOptions

Wir bieten zwar die SQLClient-Instrumentierung innerhalb unseres Pakets an, diese befindet sich allerdings noch in der Betaphase. Wenn sie ein stabiles Release erreicht, fügen wir sie als Standardpaketreferenz hinzu. Fügen Sie bis dahin Ihrem Projekt den OpenTelemetry.Instrumentation.SqlClient-Paketverweis hinzu, und verwenden Sie die zugehörige öffentliche API, um die SQLClient-Instrumentierung anzupassen.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

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

Konfigurieren von Azure Monitor

Application Insights bietet über ApplicationInsightsServiceOptions viele weitere Konfigurationsoptionen.

Application Insights-Einstellung OpenTelemetry-Alternative
AddAutoCollectedMetricExtractor N/V
ApplicationVersion Legen Sie „service.version“ für die Ressource fest.
ConnectionString Sehen Sie sich die Anleitung zum Konfigurieren der Verbindungszeichenfolge an.
DependencyCollectionOptions N/V. Um Abhängigkeiten anzupassen, überprüfen Sie die verfügbaren Konfigurationsoptionen für entsprechende Instrumentierungsbibliotheken.
DeveloperMode N/V
EnableActiveTelemetryConfigurationSetup N/V
EnableAdaptiveSampling N/V. Nur die Stichprobenentnahme mit festem Prozentsatz wird unterstützt.
EnableAppServicesHeartbeatTelemetryModule N/V
EnableAuthenticationTrackingJavaScript N/V
EnableAzureInstanceMetadataTelemetryModule N/V
EnableDependencyTrackingTelemetryModule Sehen Sie sich die Anleitung zum Filtern von Ablaufverfolgungen an.
EnableDiagnosticsTelemetryModule N/V
EnableEventCounterCollectionModule N/V
EnableHeartbeat N/V
EnablePerformanceCounterCollectionModule N/V
EnableQuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule Sehen Sie sich die Anleitung zum Filtern von Ablaufverfolgungen an.
EndpointAddress Verwenden Sie „ConnectionString“.
InstrumentationKey Verwenden Sie „ConnectionString“.
RequestCollectionOptions N/V. Sehen Sie sich die Optionen für „OpenTelemetry.Instrumentation.AspNetCore“ an.

Entfernen benutzerdefinierter Konfigurationen

Die folgenden Szenarien sind optional und nur für erfahrene Benutzer bestimmt.

  • Wenn Sie über weitere Verweise auf TelemetryClient verfügen, die zur manuellen Erfassung von Telemetriedaten verwendet werden können, müssen diese entfernt werden.

  • Wenn Sie benutzerdefinierte Filter oder Anreicherungen in Form eines benutzerdefinierten Elements vom Typ TelemetryProcessor oder TelemetryInitializer hinzugefügt haben, müssen diese entfernt werden. Sie befinden sich in ServiceCollection.

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

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • Entfernen des JavaScript-Codeschnipsels

    Wenn Sie den vom Application Insights .NET SDK bereitgestellten Codeschnipsel verwendet haben, muss dieser ebenfalls entfernt werden. Vollständige Codebeispiele, die zeigen, was entfernt werden muss, finden Sie im Leitfaden Aktivieren der clientseitigen Telemetrie für Webanwendungen.

    Wenn Sie das JavaScript SDK zum Sammeln clientseitiger Telemetriedaten hinzugefügt haben, kann es ebenfalls entfernt werden, auch wenn es ohne .NET SDK weiterhin funktioniert. Vollständige Codebeispiele, die zeigen, was entfernt werden muss, finden Sie im Onboardingleitfaden für das JavaScript SDK.

  • Entfernen aller ggf. vorhandenen Visual Studio-Artefakte

    Wenn Sie Visual Studio für das Onboarding in Application Insights verwendet haben, sind in Ihrem Projekt möglicherweise noch mehr Dateien übrig.

    • Das Verzeichnis Properties/ServiceDependencies enthält unter Umständen einen Verweis auf Ihre Application Insights-Ressource.

Tipp

Unsere Produktgruppe freut sich über Feedback zu dieser Dokumentation. Senden Sie Feedback an otel@microsoft.com, oder sehen Sie den Abschnitt Support an.

Häufig gestellte Fragen

Dieser Abschnitt richtet sich an Kunden, die Telemetrieinitialisierer oder -prozessoren verwenden oder benutzerdefinierten Code für die klassische Application Insights-API schreiben, um benutzerdefinierte Telemetriedaten zu erstellen.

Wie sieht die Zuordnung zwischen SDK-APIs und OpenTelemetry-Konzepten aus?

OpenTelemetry ist ein anbieterneutrales Einblickframework. Das OpenTelemetry SDK und die Bibliotheken enthalten keine Application Insights-APIs. Vor der Migration ist es wichtig, sich mit einigen der Konzepte von OpenTelemetry vertraut zu machen.

  • In Application Insights wurden sämtliche Telemetriedaten über einen einzelnen Telemetrieclient (TelemetryClient) und über eine einzelne Telemetriekonfiguration (TelemetryConfiguration) verwaltet. In OpenTelemetry verfügt jedes der drei Telemetriesignale (Ablaufverfolgungen, Metriken und Protokolle) über eine eigene Konfiguration. Sie können Telemetriedaten manuell und ohne externe Bibliotheken über die .NET-Runtime erstellen. Weitere Informationen finden Sie in den .NET-Leitfäden zu verteilter Ablaufverfolgung, Metriken und Protokollierung.

  • Von Application Insights wurde TelemetryModules verwendet, um automatisch Telemetriedaten für Ihre Anwendung zu sammeln. OpenTelemetry verwendet stattdessen Instrumentierungsbibliotheken, um Telemetriedaten von bestimmten Komponenten zu sammeln (z. B. AspNetCore für Anforderungen und HttpClient für Abhängigkeiten).

  • Von Application Insights wurde TelemetryInitializers verwendet, um Telemetriedaten mit zusätzlichen Informationen anzureichern oder Eigenschaften außer Kraft zu setzen. Bei OpenTelemetry können Sie einen Prozessor schreiben, um ein bestimmtes Signal anzupassen. Darüber hinaus bieten viele OpenTelemetry-Instrumentierungsbibliotheken eine Enrich-Methode zum Anpassen der Telemetriedaten, die von dieser spezifischen Komponente generiert werden.

  • Von Application Insights wurde TelemetryProcessors verwendet, um Telemetriedaten zu filtern. Mit einem Prozessor von OpenTelemetry können auch Filterregeln auf ein bestimmtes Signal angewendet werden.

Wie sieht die Zuordnung zwischen Application Insights-Telemetrietypen und OpenTelemetry aus?

Diese Tabelle zeigt die Zuordnung zwischen Application Insights-Datentypen und OpenTelemetry-Konzepten sowie deren .NET-Implementierungen.

Azure Monitor-Tabelle Application Insights-Datentyp OpenTelemetry-Datentyp .NET-Implementierung
customEvents EventTelemetry – –
customMetrics MetricTelemetry Metriken System.Diagnostics.Metrics.Meter
Abhängigkeiten DependencyTelemetry Spans (Client, intern, Consumer) System.Diagnostics.Activity
Ausnahmen ExceptionTelemetry Ausnahmen System.Exception
requests RequestTelemetry Spans (Server, Producer) System.Diagnostics.Activity
traces TraceTelemetry Protokolle Microsoft.Extensions.Logging.ILogger

Weitere Informationen finden Sie in folgenden Dokumenten:

Wie sieht die Zuordnung zwischen Application Insights-Konzepten für die Stichprobenentnahme und OpenTelemetry aus?

In Application Insights standen mehrere Optionen zum Konfigurieren der Stichprobenentnahme zur Verfügung. Der Azure Monitor-Exporter und die Azure Monitor-Distribution bieten dagegen nur eine Stichprobenentnahme mit festem Prozentsatz. Stichproben können nur für Anforderungen und Abhängigkeiten (OpenTelemetry-Ablaufverfolgungen) entnommen werden.

Codebeispiele zur Konfiguration der Stichprobenentnahme finden Sie in unserem Leitfaden zum Aktivieren der Stichprobenentnahme.

Wie sieht die Zuordnung zwischen Telemetrieprozessoren bzw. -initialisierern und OpenTelemetry aus?

Verwenden Sie im Application Insights .NET SDK Telemetrieprozessoren, um Telemetriedaten zu filtern und zu ändern oder zu verwerfen. Verwenden Sie Telemetrieinitialisierer, um benutzerdefinierte Eigenschaften hinzuzufügen oder zu ändern. Weitere Informationen finden Sie in der Dokumentation zu Azure Monitor. OpenTelemetry ersetzt diese Konzepte durch Aktivitäts- oder Protokollprozessoren, die Telemetriedaten anreichern und filtern.

Filtern von Ablaufverfolgungen

Wenn Sie Telemetriedaten in OpenTelemetry filtern möchten, können Sie einen Aktivitätsprozessor implementieren. Dieses Beispiel entspricht dem Application Insights-Beispiel zum Filtern von Telemetriedaten aus der Dokumentation zu Azure Monitor. Das Beispiel zeigt, wo nicht erfolgreiche Abhängigkeitsaufrufe gefiltert werden.

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

Um diesen Prozessor zu verwenden, müssen Sie ein TracerProvider-Element erstellen und den Prozessor vor AddAzureMonitorTraceExporter hinzufügen.

using OpenTelemetry.Trace;

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

Filtern von Protokollen

ILogger-Implementierungen verfügen über einen integrierten Mechanismus zum Anwenden der Protokollfilterung. Mit dieser Filterung können Sie die Protokolle steuern, die an die einzelnen registrierten Anbieter gesendet werden (einschließlich OpenTelemetryLoggerProvider). „OpenTelemetry“ ist der Alias für OpenTelemetryLoggerProvider, der beim Konfigurieren von Filterregeln verwendet wird.

Im folgenden Beispiel wird „Error“ als standardmäßiger Protokolliergrad (LogLevel) und „Warning“ als minimaler Protokolliergrad (LogLevel) für eine benutzerdefinierte Kategorie definiert. Diese Regeln gelten wie definiert nur für OpenTelemetryLoggerProvider.

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

Weitere Informationen finden Sie in der OpenTelemetry .NET-Dokumentation zu Protokollen.

Hinzufügen benutzerdefinierter Eigenschaften zu Ablaufverfolgungen

In OpenTelemetry können Sie Aktivitätsprozessoren verwenden, um Telemetriedaten mit weiteren Eigenschaften anzureichern. Dies funktioniert ähnlich wie die Verwendung von Telemetrieinitialisierern in Application Insights zum Ändern von Telemetrieeigenschaften.

Standardmäßig kennzeichnet der Azure Monitor-Exporter jede HTTP-Anforderung mit einem Antwortcode ab 400 als nicht erfolgreich. Wenn Sie 400 jedoch als Erfolg behandeln möchten, können Sie einen anreichernden Aktivitätsprozessor hinzufügen, der den Erfolg für die Aktivität festlegt und ein Tag hinzufügt, um weitere Telemetrieeigenschaften einzuschließen. Dies ist vergleichbar mit dem Hinzufügen oder Ändern von Eigenschaften mithilfe eines Initialisierers in Application Insights, wie in der Dokumentation zu Azure Monitor beschrieben.

Hier ist ein Beispiel für das Hinzufügen von benutzerdefinierten Eigenschaften und die Außerkraftsetzung des Standardverhaltens für bestimmte Antwortcodes:

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

Um diesen Prozessor zu verwenden, müssen Sie ein TracerProvider-Element erstellen und den Prozessor vor AddAzureMonitorTraceExporter hinzufügen.

using OpenTelemetry.Trace;

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

Wie kann ich Telemetriedaten mit OpenTelemetry manuell nachverfolgen?

Senden von Ablaufverfolgungen: Manuell

Ablaufverfolgungen in Application Insights werden als RequestTelemetry und DependencyTelemetry gespeichert. In OpenTelemetry werden Ablaufverfolgungen mithilfe der Activity-Klasse als Span modelliert.

OpenTelemetry .NET verwendet die Klassen ActivitySource und Activity für die Ablaufverfolgung. Diese sind Teil der .NET-Runtime. Dieser Ansatz ist unterscheidend, da die .NET-Implementierung die Ablaufverfolgungs-API direkt in die Runtime selbst integriert. Mit dem Paket System.Diagnostics.DiagnosticSource können Entwickler ActivitySource verwenden, um Activity-Instanzen zu erstellen und zu verwalten. Mithilfe dieser Methode können Sie .NET-Anwendungen nahtlos Ablaufverfolgung hinzufügen, ohne sich auf externe Bibliotheken zu verlassen, und dabei die integrierten Funktionen des .NET-Ökosystems nutzen. Ausführlichere Informationen finden Sie in den exemplarischen Vorgehensweisen zur verteilten Ablaufverfolgungsinstrumentierung.

So migrieren Sie die manuelle Ablaufverfolgung:

Hinweis

In Application Insights können der Rollenname und die Rolleninstanz auf Telemetrieebene festgelegt werden. Mit dem Azure Monitor-Exporter ist jedoch keine Anpassung auf Telemetrieebene möglich. Der Rollenname und die Rolleninstanz werden aus der OpenTelemetry-Ressource extrahiert und auf alle Telemetriedaten angewendet. Weitere Informationen zum Festlegen des Cloudrollennamens und der Cloudrolleninstanz finden Sie hier.

DependencyTelemetry

DependencyTelemetry von Application Insights wird verwendet, um ausgehende Anforderungen zu modellieren. So konvertieren Sie sie in OpenTelemetry:

Application Insights-Beispiel:

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

OpenTelemetry-Beispiel:

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

RequestTelemetry von Application Insights modelliert eingehende Anforderungen. So migrieren Sie sie zu OpenTelemetry:

Application Insights-Beispiel:

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

OpenTelemetry-Beispiel:

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

Nachverfolgung benutzerdefinierter Vorgänge

In Application Insights können benutzerdefinierte Vorgänge mithilfe von StartOperation- und StopOperation-Methoden nachverfolgt werden. Verwenden Sie dazu ActivitySource und Activity in OpenTelemetry .NET. Für Vorgänge mit ActivityKind.Server und ActivityKind.Consumer generiert der Azure Monitor-Exporter RequestTelemetry. Für ActivityKind.Client, ActivityKind.Producer und ActivityKind.Internal wird DependencyTelemetry generiert. Weitere Informationen zur Nachverfolgung benutzerdefinierter Vorgänge finden Sie in der Dokumentation zu Azure Monitor. Weitere Informationen zur Verwendung von ActivitySource und Activity in .NET finden Sie in den exemplarischen Vorgehensweisen zur verteilten Ablaufverfolgungsinstrumentierung von .NET.

Hier ist ein Beispiel für das Starten und Beenden einer Aktivität für benutzerdefinierte Vorgänge:

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

Senden von Protokollen

Protokolle in Application Insights werden als TraceTelemetry und ExceptionTelemetry gespeichert.

TraceTelemetry

In OpenTelemetry ist die Protokollierung über die ILogger-Schnittstelle integriert. So migrieren Sie TraceTelemetry:

Application Insights-Beispiel:

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

OpenTelemetry-Beispiel:

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

Application Insights verwendet ExceptionTelemetry, um Ausnahmen zu protokollieren. So führen Sie die Migration zu OpenTelemetry durch:

Application Insights-Beispiel:

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

OpenTelemetry-Beispiel:

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

Senden von Metriken

Metriken in Application Insights werden als MetricTelemetry gespeichert. In OpenTelemetry werden Metriken als Meter aus dem Paket System.Diagnostics.DiagnosticSource modelliert.

Application Insights verfügt sowohl über Metrik-APIs ohne Vorabaggregation (TrackMetric()) als auch über Metrik-APIs mit Vorabaggregation (GetMetric().TrackValue()). Im Gegensatz zu OpenTelemetry gibt es in Application Insights kein Konzept für Instrumente. Application Insights verwendet die gleiche API für alle Metrikszenarien.

Bei OpenTelemetry müssen Benutzer dagegen zuerst das richtige Metrikinstrument auswählen (basierend auf der tatsächlichen Semantik der Metrik). Wenn beispielsweise etwas gezählt werden soll (z. B. die Anzahl empfangener Serveranforderungen oder Ähnliches), muss der OpenTelemetry-Zähler verwendet werden. Wenn verschiedene Quantile berechnet werden sollen (z. B. den P99-Wert der Serverwartezeit), muss das Instrument OpenTelemetry-Histogramm verwendet werden. Aufgrund dieses grundlegenden Unterschieds zwischen Application Insights und OpenTelemetry gibt es keinen direkten Vergleich zwischen ihnen.

Im Gegensatz zu Application Insights bietet OpenTelemetry keine integrierten Mechanismen zum Anreichern oder Filtern von Metriken. In Application Insights können Telemetrieprozessoren und -initialisierer verwendet werden, um Metriken zu ändern oder zu verwerfen. Diese Funktion ist in OpenTelemetry jedoch nicht verfügbar.

Darüber hinaus unterstützt OpenTelemetry das direkte Senden von Rohmetriken nicht, da es dort keine Entsprechung für die in Application Insights enthaltene TrackMetric()-Funktion gibt.

Im Zuge der Migration von Application Insights zu OpenTelemetry müssen alle Verwendungen der Metrik-APIs von Application Insights durch die OpenTelemetry-API ersetzt werden. Dies erfordert Vertrautheit mit den verschiedenen OpenTelemetry-Instrumenten und deren Semantik.

Tipp

Das Histogramm ist am vielseitigsten und entspricht am ehesten der GetMetric().TrackValue()-API von Application Insights. Sie können Metrik-APIs von Application Insights durch das Histogramm ersetzen, um das gleiche Ergebnis zu erzielen.

Weitere Telemetrietypen

CustomEvents

Wird in OpenTelemetry nicht unterstützt.

Application Insights-Beispiel:

TelemetryClient.TrackEvent()
AvailabilityTelemetry

Wird in OpenTelemetry nicht unterstützt.

Application Insights-Beispiel:

TelemetryClient.TrackAvailability()
PageViewTelemetry

Wird in OpenTelemetry nicht unterstützt.

Application Insights-Beispiel:

TelemetryClient.TrackPageView()

Kann ich Livemetriken für Konsolen- und Workerdienstanwendungen abrufen?

Wir empfehlen den Azure Monitor OpenTelemetry Exporter für Konsolen- und Workerdienstanwendungen, die keine Livemetriken enthalten.

Nächste Schritte

Tipp

Unsere Produktgruppe freut sich über Feedback zu dieser Dokumentation. Senden Sie Feedback an otel@microsoft.com, oder sehen Sie den Abschnitt Support an.

Unterstützung