Delen via

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

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, bekijkt u Azure Monitor OpenTelemetry inschakelen.

Notitie

Zie OpenTelemetry gebruiken met Azure Functions voor Azure Function-apps.

Vereisten

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

Aanbeveling

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.

    Aanbeveling

    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.

Aanbeveling

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 om de connectiestring bij te werken om telemetrie naar de oorspronkelijke bron te verzenden nadat de migratie succesvol is bevestigd.

  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.

Aanbeveling

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:

Het aanpassen van 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);
    };
});
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 bieden de SQLClient-instrumentatie binnen ons pakket terwijl het nog in de bètaversie is. Wanneer het 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
Automatisch verzamelde metriekextractor toevoegen N.v.t.
Applicatieversie Service.version instellen voor resource
ConnectionString Zie de instructies voor het configureren van de verbindingsreeks.
OptiesVoorVerzamelingVanAfhankelijkheden N.v.t. Als u afhankelijkheden wilt aanpassen, bekijkt u de beschikbare configuratieopties voor toepasselijke instrumentatiebibliotheken.
Ontwikkelaarsmodus N.v.t.
InschakelenActieveTelemetrieConfiguratieInstelling N.v.t.
AdaptieveSteekproefinvoerInschakelen N.v.t. Alleen steekproeven met vaste frequentie worden ondersteund.
InschakelenAppServicesHeartbeatTelemetryModule N.v.t.
InschakelenAuthenticatieTrackingJavaScript N.v.t.
EnableAzureInstanceMetadataTelemetryModule N.v.t.
SchakelDependencyTrackingTelemetryModuleIn Zie de instructies voor het filteren van traces.
ModuleVoorTelemetrieDiagnostiekInschakelen N.v.t.
InschakelenEventtellerVerzamelModule N.v.t.
InschakelenHeartbeat N.v.t.
ModuleVoorPrestatiecountersInschakelen N.v.t.
SchakelQuickPulseMetricStreamIn AzureMonitorOptions.EnableLiveMetrics
ModuleVoorVerzoekenMonitoringTelemetrieInschakelen Zie de instructies voor het filteren van traces.
Eindpuntadres Gebruik ConnectionString.
InstrumentatieSleutel Gebruik ConnectionString.
OptiesVoorHetVerzamelenVanVerzoeken 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. Bekijk de handleiding telemetrie aan de clientzijde inschakelen voor webapplicaties voor volledige codevoorbeelden van wat er moet worden verwijderd.

    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.

Aanbeveling

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

Volgende stappen

Aanbeveling

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

Ondersteuning