Delen via

Migreren van .NET Application Insights SDK's naar Azure Monitor OpenTelemetry

  • Artikel

Deze handleiding bevat stapsgewijze instructies voor het migreren van verschillende .NET-toepassingen van het gebruik van Application Insights SDK's (Software Development Kits) naar Azure Monitor OpenTelemetry.

Verwacht een vergelijkbare ervaring met Azure Monitor OpenTelemetry-instrumentatie als met de Application Insights SDK's. Zie de releasestatus van functies voor meer informatie en een functie-per-functievergelijking.

Als u aan de slag gaat met Application Insights en u niet hoeft te migreren vanuit de klassieke API, raadpleegt u Azure Monitor OpenTelemetry inschakelen.

Vereisten

  • Een ASP.NET Core-webtoepassing die al is geïnstruineerd met Application Insights zonder aanpassingen
  • Een actief ondersteunde versie van .NET

Tip

Onze productgroep zoekt actief naar feedback over deze documentatie. Geef feedback voor otel@microsoft.com of zie de sectie Ondersteuning .

De Application Insights-SDK verwijderen

Notitie

Voordat u doorgaat met deze stappen, moet u bevestigen dat u een huidige back-up van uw toepassing hebt.

  1. NuGet-pakketten verwijderen

    Verwijder het Microsoft.ApplicationInsights.AspNetCore pakket uit uw csproj.

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. Initialisatiecode en aanpassingen verwijderen

    Verwijder verwijzingen naar Application Insights-typen in uw codebasis.

    Tip

    Nadat u het Application Insights-pakket hebt verwijderd, kunt u uw toepassing opnieuw bouwen om een lijst met verwijzingen op te halen die moeten worden verwijderd.

    • Verwijder Application Insights uit uw ServiceCollection door de volgende regel te verwijderen:

      builder.Services.AddApplicationInsightsTelemetry();

    • Verwijder de ApplicationInsights sectie uit uw appsettings.json.

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

  3. Opschonen en bouwen

    Inspecteer uw bin-map om te controleren of alle verwijzingen naar deze Microsoft.ApplicationInsights.* map zijn verwijderd.

  4. Uw toepassing testen

    Controleer of uw toepassing geen onverwachte gevolgen heeft.

Tip

Onze productgroep zoekt actief naar feedback over deze documentatie. Geef feedback voor otel@microsoft.com of zie de sectie Ondersteuning .

OpenTelemetry inschakelen

We raden u aan een ontwikkelingsresource te maken en de bijbehorende verbindingsreeks te gebruiken bij het volgen van deze instructies.

Schermopname van het Application Insights-overzicht en verbindingsreeks.

Plan het verbindingsreeks bij te werken om telemetrie naar de oorspronkelijke resource te verzenden nadat de migratie is voltooid.

  1. De Azure Monitor-distributie installeren

    Onze Azure Monitor Distro maakt automatische telemetrie mogelijk door openTelemetry-instrumentatiebibliotheken op te halen voor het verzamelen van traceringen, metrische gegevens, logboeken en uitzonderingen en het verzamelen van aangepaste telemetrie.

    Als u de Azure Monitor-distributie installeert, wordt de OpenTelemetry SDK als een afhankelijkheid gebruikt.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Zowel OpenTelemetry als Azure Monitor toevoegen en configureren

    De OpenTelemery SDK moet worden geconfigureerd bij het opstarten van de toepassing als onderdeel van uw ServiceCollection, meestal in de Program.cs.

    OpenTelemetry heeft een concept van drie signalen; Traceringen, metrische gegevens en logboeken. De Azure Monitor-distributie configureert elk van deze signalen.

Program.cs

In het volgende codevoorbeeld ziet u de basisbeginselen.

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

U wordt aangeraden uw verbindingsreeks in te stellen in een omgevingsvariabele:

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Meer opties voor het configureren van de verbindingsreeks worden hier beschreven: De Application Insights-verbindingsreeks configureren.

Tip

Onze productgroep zoekt actief naar feedback over deze documentatie. Geef feedback voor otel@microsoft.com of zie de sectie Ondersteuning .

Instrumentatiebibliotheken installeren en configureren

Instrumentatiebibliotheken kunnen aan uw project worden toegevoegd om automatisch telemetrie over specifieke onderdelen of afhankelijkheden te verzamelen.

De volgende bibliotheken zijn opgenomen in de distributie.

Instrumentatiebibliotheken aanpassen

De Azure Monitor-distributie bevat .NET OpenTelemetry-instrumentatie voor ASP.NET Core, HttpClient en SQLClient. U kunt deze opgenomen instrumentaties aanpassen of handmatig extra instrumentatie toevoegen met behulp van de OpenTelemetry-API.

Hier volgen enkele voorbeelden van het aanpassen van de instrumentatie:

AspNetCoreTraceInstrumentationOptions aanpassen
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);
    };
});
HttpClientTraceInstrumentationOptions aanpassen
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);
    };
});
SqlClientInstrumentationOptions aanpassen

We leveren de SQLClient-instrumentatie in ons pakket terwijl het nog in bèta is. Wanneer deze een stabiele release bereikt, nemen we deze op als standaardpakketreferentie. Tot die tijd voegt u de pakketreferentie toe aan uw project en gebruikt u de openbare API om de OpenTelemetry.Instrumentation.SqlClient SQLClient-instrumentatie aan te passen.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

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

Azure Monitor configureren

Application Insights bood veel meer configuratieopties via ApplicationInsightsServiceOptions.

Application Insights-instelling Alternatief voor OpenTelemetry
AddAutoCollectedMetricExtractor N.v.t.
ApplicationVersion Service.version instellen voor resource
ConnectionString Zie de instructies voor het configureren van de verbindingsreeks.
DependencyCollectionOptions N.v.t. Als u afhankelijkheden wilt aanpassen, bekijkt u de beschikbare configuratieopties voor toepasselijke instrumentatiebibliotheken.
DeveloperMode N.v.t.
EnableActiveTelemetryConfigurationSetup N.v.t.
EnableAdaptiveSampling N.v.t. Alleen steekproeven met vaste frequentie worden ondersteund.
EnableAppServicesHeartbeatTelemetryModule N.v.t.
EnableAuthenticationTrackingJavaScript N.v.t.
EnableAzureInstanceMetadataTelemetryModule N.v.t.
EnableDependencyTrackingTelemetryModule Zie de instructies voor het filteren van traceringen.
EnableDiagnosticsTelemetryModule N.v.t.
EnableEventCounterCollectionModule N.v.t.
EnableHeartbeat N.v.t.
EnablePerformanceCounterCollectionModule N.v.t.
EnableQuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule Zie de instructies voor het filteren van traceringen.
EndpointAddress Gebruik ConnectionString.
InstrumentationKey Gebruik ConnectionString.
RequestCollectionOptions N.v.t. Zie opties voor OpenTelemetry.Instrumentation.AspNetCore.

Aangepaste configuraties verwijderen

De volgende scenario's zijn optioneel en zijn alleen van toepassing op geavanceerde gebruikers.

  • Als u nog verwijzingen hebt naar de TelemetryClient, die kunnen worden gebruikt om telemetrie handmatig vast te leggen, moeten ze worden verwijderd.

  • Als u aangepaste filters of verrijking hebt toegevoegd in de vorm van een aangepaste TelemetryProcessor of TelemetryInitializer, moeten ze worden verwijderd. Ze zijn te vinden in je ServiceCollection.

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

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • JavaScript-fragment verwijderen

    Als u het fragment van de .NET SDK van Application Insights hebt gebruikt, moet dit ook worden verwijderd. Raadpleeg de handleiding voor het inschakelen van telemetrie aan de clientzijde voor webtoepassingen voor volledige codevoorbeelden.

    Als u de JavaScript SDK hebt toegevoegd voor het verzamelen van telemetrie aan de clientzijde, kan deze ook worden verwijderd, hoewel deze blijft werken zonder de .NET SDK. Raadpleeg de onboardinghandleiding voor de JavaScript-SDK voor volledige codevoorbeelden van wat u wilt verwijderen.

  • Visual Studio-artefacten verwijderen

    Als u Visual Studio hebt gebruikt om onboarding uit te voeren voor Application Insights, hebt u mogelijk meer bestanden over in uw project.

    • Properties/ServiceDependencies directory heeft mogelijk een verwijzing naar uw Application Insights-resource.

Tip

Onze productgroep zoekt actief naar feedback over deze documentatie. Geef feedback voor otel@microsoft.com of zie de sectie Ondersteuning .

Veelgestelde vragen

Deze sectie is bedoeld voor klanten die telemetrie-initialisatiefuncties of -processors gebruiken of aangepaste code schrijven op basis van de klassieke Application Insights-API om aangepaste telemetrie te maken.

Hoe worden de SDK-API's toegewezen aan OpenTelemetry-concepten?

OpenTelemetry is een leverancierneutraal waarneembaarheidsframework. Er zijn geen Application Insights-API's in de OpenTelemetry SDK of bibliotheken. Voordat u migreert, is het belangrijk om een aantal concepten van OpenTelemetry te begrijpen.

  • In Application Insights werd alle telemetrie beheerd via één TelemetryClient en TelemetryConfiguration. In OpenTelemetry heeft elk van de drie telemetriesignalen (Traces, Metrics en Logs) een eigen configuratie. U kunt handmatig telemetrie maken via de .NET-runtime zonder externe bibliotheken. Zie de .NET-handleidingen voor gedistribueerde tracering, metrische gegevens en logboekregistratie voor meer informatie.

  • Application Insights wordt gebruikt TelemetryModules om automatisch telemetriegegevens voor uw toepassing te verzamelen. In plaats daarvan gebruikt OpenTelemetry Instrumentation-bibliotheken om telemetrie van specifieke onderdelen te verzamelen (zoals AspNetCore voor aanvragen en HttpClient voor afhankelijkheden).

  • Application Insights wordt gebruikt TelemetryInitializers om telemetrie te verrijken met aanvullende informatie of om eigenschappen te overschrijven. Met OpenTelemetry kunt u een processor schrijven om een specifiek signaal aan te passen. Daarnaast bieden veel OpenTelemetry Instrumentation-bibliotheken een Enrich methode om de telemetrie die door dat specifieke onderdeel wordt gegenereerd, aan te passen.

  • Application Insights wordt gebruikt TelemetryProcessors om telemetrie te filteren. Een OpenTelemetry Processor kan ook worden gebruikt om filterregels toe te passen op een specifiek signaal.

Hoe worden telemetrietypen van Application Insights toegewezen aan OpenTelemetry?

In deze tabel worden Application Insights-gegevenstypen toegewezen aan OpenTelemetry-concepten en hun .NET-implementaties.

Azure Monitor-tabel Application Insights DataType OpenTelemetry DataType .NET-implementatie
customEvents EventTelemetry N.v.t. N.v.t.
customMetrics MetricTelemetry Metrische gegevens voor System.Diagnostics.Metrics.Meter
afhankelijkheden DependencyTelemetry Spans (client, intern, consument) System.Diagnostics.Activity
uitzonderingen ExceptionTelemetry Uitzonderingen System.Exception
requests RequestTelemetry Spans (Server, Producer) System.Diagnostics.Activity
traces TraceTelemetry Logboeken Microsoft.Extensions.Logging.ILogger

De volgende documenten bevatten meer informatie.

Hoe worden concepten voor het nemen van steekproeven van Application Insights toegewezen aan OpenTelemetry?

Hoewel Application Insights meerdere opties biedt voor het configureren van steekproeven, biedt Azure Monitor Exporter of Azure Monitor Distro alleen steekproeven met vaste frequenties. Alleen aanvragen en afhankelijkheden (OpenTelemetry Traces) kunnen worden bemonsterd.

Zie onze handleiding Sampling inschakelen voor codevoorbeelden over het configureren van steekproeven

Hoe worden telemetrieprocessors en initializers toegewezen aan OpenTelemetry?

Gebruik in de .NET SDK van Application Insights telemetrieprocessors om telemetriegegevens te filteren en te wijzigen of te verwijderen. Gebruik telemetrie-initialisatiefuncties om aangepaste eigenschappen toe te voegen of te wijzigen. Zie de Documentatie van Azure Monitor voor meer informatie. OpenTelemetry vervangt deze concepten door activiteiten- of logboekprocessors, die telemetrie verrijken en filteren.

Traceringen filteren

Als u telemetriegegevens in OpenTelemetry wilt filteren, kunt u een activiteitsprocessor implementeren. Dit voorbeeld is gelijk aan het Application Insights-voorbeeld voor het filteren van telemetriegegevens, zoals beschreven in de Documentatie van Azure Monitor. In het voorbeeld ziet u waar mislukte afhankelijkheidsaanroepen worden gefilterd.

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

Als u deze processor wilt gebruiken, moet u eerst een TracerProvider processor AddAzureMonitorTraceExportermaken en deze toevoegen.

using OpenTelemetry.Trace;

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

Logboeken filteren

ILoggerimplementaties hebben een ingebouwd mechanisme om logboekfiltering toe te passen. Met deze filtering kunt u de logboeken beheren die naar elke geregistreerde provider worden verzonden, inclusief de OpenTelemetryLoggerProvider. 'OpenTelemetry' is de alias voor OpenTelemetryLoggerProvider, die wordt gebruikt bij het configureren van filterregels.

In het volgende voorbeeld wordt 'Fout' gedefinieerd als de standaardinstelling LogLevel en wordt ook 'Waarschuwing' gedefinieerd als het minimum LogLevel voor een door de gebruiker gedefinieerde categorie. Deze regels zoals gedefinieerd, zijn alleen van toepassing op de OpenTelemetryLoggerProvider.

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

Lees de OpenTelemetry .NET-documentatie over logboeken voor meer informatie.

Aangepaste eigenschappen toevoegen aan traceringen

In OpenTelemetry kunt u activiteitsprocessors gebruiken om telemetriegegevens te verrijken met meer eigenschappen. Het is vergelijkbaar met het gebruik van telemetrie-initialisatiefuncties in Application Insights, waar u telemetrie-eigenschappen kunt wijzigen.

Standaard markeert Azure Monitor Exporter elke HTTP-aanvraag met een antwoordcode van 400 of hoger als mislukt. Als u echter 400 als een succes wilt behandelen, kunt u een verrijkingsactiviteitsprocessor toevoegen waarmee het succes voor de activiteit wordt ingesteld en een tag wordt toegevoegd om meer telemetrie-eigenschappen op te nemen. Het is vergelijkbaar met het toevoegen of wijzigen van eigenschappen met behulp van een initializer in Application Insights, zoals beschreven in de Documentatie van Azure Monitor.

Hier volgt een voorbeeld van hoe u aangepaste eigenschappen toevoegt en het standaardgedrag voor bepaalde antwoordcodes overschrijft:

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

Als u deze processor wilt gebruiken, moet u eerst een TracerProvider processor AddAzureMonitorTraceExportermaken en deze toevoegen.

using OpenTelemetry.Trace;

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

Hoe kan ik telemetrie handmatig bijhouden met behulp van OpenTelemetry?

Traceringen verzenden - Handmatig

Traceringen in Application Insights worden opgeslagen als RequestTelemetry en DependencyTelemetry. In OpenTelemetry worden traceringen gemodelleerd als Span het gebruik van de Activity klasse.

OpenTelemetry .NET maakt gebruik van de ActivitySource en Activity klassen voor tracering, die deel uitmaken van de .NET-runtime. Deze benadering is onderscheidend omdat de .NET-implementatie de tracerings-API rechtstreeks in de runtime zelf integreert. Met het System.Diagnostics.DiagnosticSource pakket kunnen ontwikkelaars ActivitySource exemplaren maken en beheren Activity . Deze methode biedt een naadloze manier om tracering toe te voegen aan .NET-toepassingen zonder gebruik te maken van externe bibliotheken, waarbij de ingebouwde mogelijkheden van het .NET-ecosysteem worden toegepast. Raadpleeg de walkthroughs voor gedistribueerde traceringsinstrumenten voor meer gedetailleerde informatie.

U kunt als volgt handmatige tracering migreren:

Notitie

In Application Insights kan de rolnaam en het rolexemplaren worden ingesteld op telemetrieniveau. Met de Azure Monitor-exporteur kunnen we echter niet op telemetrieniveau aanpassen. De rolnaam en het rolexemplaren worden geëxtraheerd uit de OpenTelemetry-resource en toegepast op alle telemetriegegevens. Lees dit document voor meer informatie: Stel de naam van de cloudrol en het exemplaar van de cloudrol in.

DependencyTelemetry

Application Insights DependencyTelemetry wordt gebruikt om uitgaande aanvragen te modelleren. U kunt het als volgt converteren naar OpenTelemetry:

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

Voorbeeld van 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

Application Insights RequestTelemetry modellen inkomende aanvragen. U kunt deze als volgt migreren naar OpenTelemetry:

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

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

Aangepaste bewerkingen bijhouden

In Application Insights kunt u aangepaste bewerkingen bijhouden met behulp van StartOperation en StopOperation methoden. Behalen met behulp van ActivitySource en Activity in OpenTelemetry .NET. Voor bewerkingen met ActivityKind.Server en ActivityKind.Consumergenereert RequestTelemetryAzure Monitor Exporter . Voor ActivityKind.Client, ActivityKind.Produceren , en ActivityKind.Internal, wordt gegenereerd DependencyTelemetry. Zie de Documentatie van Azure Monitor voor meer informatie over het bijhouden van aangepaste bewerkingen. Zie voor meer informatie over het gebruik ActivitySource en Activity in .NET de walkthroughs voor gedistribueerde tracering van .NET.

Hier volgt een voorbeeld van het starten en stoppen van een activiteit voor aangepaste bewerkingen:

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

Logboeken verzenden

Logboeken in Application Insights worden opgeslagen als TraceTelemetry en ExceptionTelemetry.

TraceTelemetry

In OpenTelemetry wordt logboekregistratie geïntegreerd via de ILogger interface. U kunt als volgt migreren TraceTelemetry:

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

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

Application Insights gebruikt ExceptionTelemetry voor het vastleggen van uitzonderingen. U kunt als volgt migreren naar OpenTelemetry:

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

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

Metrische gegevens verzenden

Metrische gegevens in Application Insights worden opgeslagen als MetricTelemetry. In OpenTelemetry worden metrische gegevens gemodelleerd op basis Meter van het System.Diagnostics.DiagnosticSource pakket.

Application Insights heeft zowel niet-vooraf geaggregeerde (TrackMetric()) als vooraf geaggregeerde (GetMetric().TrackValue()) metrische API's. In tegenstelling tot OpenTelemetry heeft Application Insights geen idee van Instruments. Application Insights heeft dezelfde API voor alle metrische scenario's.

OpenTelemetry vereist daarentegen dat gebruikers eerst het juiste metrische instrument kiezen op basis van de werkelijke semantiek van de metrische waarde. Als het bijvoorbeeld de bedoeling is om iets te tellen (zoals het aantal ontvangen serveraanvragen, enzovoort), moet openTelemetry Counter worden gebruikt. Als het de bedoeling is om verschillende percentielen te berekenen (zoals de P99-waarde van serverlatentie), moet het OpenTelemetry Histogram-instrument worden gebruikt. Vanwege dit fundamentele verschil tussen Application Insights en OpenTelemetry wordt er geen directe vergelijking gemaakt.

In tegenstelling tot Application Insights biedt OpenTelemetry geen ingebouwde mechanismen voor het verrijken of filteren van metrische gegevens. In Application Insights kunnen telemetrieprocessors en initializers worden gebruikt om metrische gegevens te wijzigen of te verwijderen, maar deze mogelijkheid is niet beschikbaar in OpenTelemetry.

Daarnaast biedt OpenTelemetry geen ondersteuning voor het rechtstreeks verzenden van onbewerkte metrische gegevens, omdat er geen equivalent is aan de TrackMetric() functionaliteit in Application Insights.

Migreren van Application Insights naar OpenTelemetry omvat het vervangen van alle Metrische API-gebruik van Application Insights door de OpenTelemetry-API. Het vereist inzicht in de verschillende OpenTelemetry-instrumenten en hun semantiek.

Tip

Het histogram is het meest veelzijdige en het dichtstbijzijnde equivalent van de Application Insights-API GetMetric().TrackValue() . U kunt Metrische API's van Application Insights vervangen door Histogram om hetzelfde doel te bereiken.

Andere telemetrietypen

CustomEvents

Niet ondersteund in OpenTelemetry.

Voorbeeld van Application Insights:

TelemetryClient.TrackEvent()
AvailabilityTelemetry

Niet ondersteund in OpenTelemetry.

Voorbeeld van Application Insights:

TelemetryClient.TrackAvailability()
PageViewTelemetry

Niet ondersteund in OpenTelemetry.

Voorbeeld van Application Insights:

TelemetryClient.TrackPageView()

Kan ik live metrische gegevens ophalen voor console- en werkservicetoepassingen?

We raden de Azure Monitor OpenTelemetry Exporter aan voor console- en werkservicetoepassingen, die geen live metrische gegevens bevatten.

Volgende stappen

Tip

Onze productgroep zoekt actief naar feedback over deze documentatie. Geef feedback voor otel@microsoft.com of zie de sectie Ondersteuning .

Ondersteuning