Condividi tramite

Eseguire la migrazione dagli SDK di .NET Application Insights ad OpenTelemetry di Monitoraggio di Azure

  • Articolo

Questa guida fornisce istruzioni dettagliate per eseguire la migrazione di varie applicazioni .NET dall'uso dei kit di sviluppo software (SDK) di Application Insights ad OpenTelemetry di Monitoraggio di Azure.

Con la strumentazione OpenTelemetry di Monitoraggio di Azure si può prevedere un'esperienza simile a quella con gli SDK di Application Insights. Per altre informazioni e un confronto funzionalità per funzionalità, vedere lo stato di rilascio delle funzionalità.

Se si è in fase di attività iniziali con Application Insights e non è necessario eseguire la migrazione dall'API classica, vedere Abilitare OpenTelemetry di Monitoraggio di Azure.

Prerequisiti

  • Un'applicazione Web ASP.NET Core già instrumentata con Application Insights senza alcuna personalizzazione
  • Una versione attivamente supportata di .NET

Suggerimento

Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.

Rimuovere Application Insights SDK

Nota

Prima di procedere con questi passaggi, è necessario verificare se si è in possesso di un backup corrente dell'applicazione.

  1. Rimuovere i pacchetti NuGet

    Rimuovere il pacchetto Microsoft.ApplicationInsights.AspNetCore da csproj.

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. Rimuovere il codice di inizializzazione e le personalizzazioni

    Rimuovere qualsiasi riferimento ai tipi di Application Insights nella codebase.

    Suggerimento

    Una volto rimosso il pacchetto di Application Insights, è possibile ricompilare l'applicazione per ottenere un elenco dei riferimenti che devono essere rimossi.

    • Rimuovere Application Insights da ServiceCollection eliminando la riga seguente:

      builder.Services.AddApplicationInsightsTelemetry();

    • Rimuovere la sezione ApplicationInsights da appsettings.json.

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

  3. Eseguire la pulizia e la compilazione

    Ispezionare la directory bin per verificare che tutti i riferimenti a Microsoft.ApplicationInsights.* siano stati rimossi.

  4. Testare l'applicazione

    Verificare che non vi siano conseguenze impreviste per l'applicazione.

Suggerimento

Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.

Abilitare OpenTelemetry

Quando si seguono queste istruzioni, è consigliabile creare una risorsa di sviluppo e usare la stringa di connessione.

Screenshot che mostra la panoramica di Application Insights e la stringa di connessione.

Pianificare l'aggiornamento della stringa di connessione per inviare i dati di telemetria alla risorsa originale dopo la conferma dell'esito positivo della migrazione.

  1. Installare la distribuzione di Monitoraggio di Azure

    La distribuzione di Monitoraggio di Azure abilita la telemetria automatica includendo librerie di strumentazione OpenTelemetry per raccogliere tracce, metriche, log ed eccezioni, inoltre consente di raccogliere dati di telemetria personalizzati.

    L'installazione della distribuzione di Monitoraggio di Azure introduce OpenTelemetry SDK come dipendenza.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Aggiungere e configurare OpenTelemetry e Monitoraggio di Azure

    OpenTelemery SDK deve essere configurato all'avvio dell'applicazione come parte di ServiceCollection, generalmente in Program.cs.

    Il concetto di OpenTelemetry ha tre segnali; Tracce, Metriche e Log. La distribuzione di Monitoraggio di Azure configura ciascuno di questi segnali.

Program.cs

Nell'esempio di codice riportato di seguito sono illustrati i dati principali.

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

È consigliabile impostare la stringa di connessione in una variabile di ambiente:

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Altre opzioni per configurare la stringa di connessione sono descritte in dettaglio qui: Configurare la stringa di connessione di Application Insights.

Suggerimento

Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.

Installare e configurare le librerie di strumentazione

Le librerie di strumentazione possono essere aggiunte al progetto per raccogliere automaticamente i dati di telemetria su componenti o dipendenze specifici.

Le librerie seguenti sono incluse nella distribuzione.

Personalizzazione delle librerie di strumentazione

La distribuzione di Monitoraggio di Azure include la strumentazione OpenTelemetry .NET per ASP.NET Core, HttpClient e SQLClient. È possibile personalizzare le strumentazioni incluse o aggiungere manualmente e autonomamente strumentazione aggiuntiva tramite l'API OpenTelemetry.

Di seguito sono riportati alcuni esempi di personalizzazione della strumentazione:

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

Microsoft fornisce la strumentazione SQLClient con il pacchetto finché è in versione beta. Quando la versione rilasciata è stabile, viene inclusa come riferimento al pacchetto standard. Fino ad allora, per personalizzare la strumentazione SQLClient, aggiungere il riferimento OpenTelemetry.Instrumentation.SqlClient al pacchetto del progetto e usare la relativa API pubblica.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

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

Configurare Monitoraggio di Azure

Application Insights offriva molte altre opzioni di configurazione tramite ApplicationInsightsServiceOptions.

Impostazione di Application Insights Alternativa a OpenTelemetry
AddAutoCollectedMetricExtractor N/D
ApplicationVersion Impostare "service.version" su Risorsa
ConnectionString Vedere le istruzioni sulla configurazione della stringa di connessione.
DependencyCollectionOptions N/D. Per personalizzare le dipendenze, esaminare le opzioni di configurazione disponibili per le librerie di strumentazione applicabili.
DeveloperMode N/D
EnableActiveTelemetryConfigurationSetup N/D
EnableAdaptiveSampling N/D. È supportato solo il campionamento a frequenza fissa.
EnableAppServicesHeartbeatTelemetryModule N/D
EnableAuthenticationTrackingJavaScript N/D
EnableAzureInstanceMetadataTelemetryModule N/D
EnableDependencyTrackingTelemetryModule Vedere le istruzioni per filtrare le Tracce.
EnableDiagnosticsTelemetryModule N/D
EnableEventCounterCollectionModule N/D
EnableHeartbeat N/D
EnablePerformanceCounterCollectionModule N/D
EnableQuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule Vedere le istruzioni per filtrare le Tracce.
EndpointAddress Utilizzare ConnectionString.
InstrumentationKey Utilizzare ConnectionString.
RequestCollectionOptions N/D. Vedere OpenTelemetry.Instrumentation.AspNetCore options.

Rimuovere le configurazioni personalizzate

Gli scenari seguenti sono facoltativi e si applicano solo agli utenti avanzati.

  • Se sono presenti altri riferimenti a TelemetryClient che potrebbe essere usato per registrare manualmente i dati di telemetria, dovranno essere rimossi.

  • Se sono stati aggiunti filtri o arricchimenti personalizzati sotto forma di TelemetryProcessor o TelemetryInitializer personalizzati, dovranno essere rimossi. Essi sono disponibili in ServiceCollection.

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

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • Rimuovere il frammento di codice JavaScript

    Se è stato usato il frammento di codice fornito da Application Insights .NET SDK, dovrà essere rimosso anch’esso. Per gli esempi di codice completi sugli elementi da rimuovere, vedere la guida per abilitare i dati di telemetria sul lato client per le applicazioni Web.

    Se è stato aggiunto un JavaScript SDK per raccogliere i dati di telemetria lato client, è possibile rimuoverlo sebbene continui a funzionare senza .NET SDK. Per esempi di codice completi sugli elementi da rimuovere, vedere la Guida all'onboarding per JavaScript SDK.

  • Rimuovere tutti gli artefatti di Visual Studio

    Se è stato usato Visual Studio per eseguire l'onboarding ad Application Insights, è possibile che siano rimasti altri file nel progetto.

    • Nella directory Properties/ServiceDependencies potrebbe essere presente un riferimento alla risorsa di Application Insights.

Suggerimento

Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.

Domande frequenti

Questa sezione si rivolge ai clienti che usano inizializzatori o processori di telemetria oppure scrivono codice personalizzato in base all'API classica di Application Insights per creare dati di telemetria personalizzati.

Come viene eseguito il mapping dell'API SDK per i concetti di OpenTelemetry?

OpenTelemetry è un framework di osservabilità indipendente dal fornitore. Non esistono API di Application Insights negli SDK o nelle librerie di OpenTelemetry. Prima della migrazione, è importante conoscere alcuni concetti di OpenTelemetry.

  • In Application Insights, tutti i dati di telemetria sono stati gestiti tramite un singolo TelemetryClient e TelemetryConfiguration. In OpenTelemetry ciascuno dei tre segnali di telemetria (Tracce, Metriche e Log) ha una propria configurazione. È possibile creare manualmente i dati di telemetria tramite il runtime .NET senza librerie esterne. Per altre informazioni, vedere le guide .NET su traccia distribuita, metriche e registrazione.

  • Application Insights ha usato TelemetryModules per raccogliere automaticamente i dati di telemetria per l'applicazione. Al contrario, OpenTelemetry usa le librerie di strumentazione per raccogliere i dati di telemetria da componenti specifici, ad esempio AspNetCore per le richieste e HttpClient per le dipendenze.

  • Application Insights ha utilizzato TelemetryInitializers per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà. Con OpenTelemetry è possibile scrivere un Processore per personalizzare un segnale specifico. Inoltre, molte librerie di strumentazione di OpenTelemetry offrono un metodo Enrich per personalizzare i dati di telemetria generati da tale componente specifico.

  • Application Insights ha utilizzato TelemetryProcessors per filtrare i dati di telemetria. È anche possibile utilizzare un Processore di OpenTelemetry per applicare le regole di filtro su un segnale specifico.

In che modo i tipi di dati di telemetria di Application Insights eseguono il mapping su OpenTelemetry?

Questa tabella esegue il mapping dei tipi di dati di Application Insights in base ai concetti di OpenTelemetry e alle relative implementazioni .NET.

Tabella di Monitoraggio di Azure DataType di Application Insights DataType di OpenTelemetry Implementazione di .NET
customEvents EventTelemetry N/D N/D
customMetrics MetricTelemetry Metrica System.Diagnostics.Metrics.Meter
dipendenze DependencyTelemetry Intervalli (Client, Interno, Consumer) System.Diagnostics.Activity
exceptions ExceptionTelemetry Eccezioni System.Exception
requests RequestTelemetry Intervalli (Server, Producer) System.Diagnostics.Activity
traces TraceTelemetry Registri Microsoft.Extensions.Logging.ILogger

I documenti seguenti forniscono maggiori informazioni.

In che modo viene eseguito il mapping dei concetti di campionamento di Application Insights su OpenTelemetry?

Sebbene Application Insights offrisse più opzioni per configurare il campionamento, l'utilità di esportazione di Monitoraggio di Azure o la distribuzione di Monitoraggio di Azure offre solo il campionamento a frequenza fissa. È possibile campionare solo le Richieste e le Dipendenze (Tracce OpenTelemetry).

Per gli esempi di codice che illustrano in dettaglio come configurare il campionamento, vedere la guida Abilitare il campionamento

In che modo i processori e gli inizializzatori di telemetria eseguono il mapping su OpenTelemetry?

In Application Insights .NET SDK usare i processori di telemetria per filtrare e modificare o rimuovere i dati di telemetria. Usare gli inizializzatori di telemetria per aggiungere o modificare proprietà personalizzate. Per altre informazioni, vedere la Documentazione di Monitoraggio di Azure. OpenTelemetry sostituisce questi concetti con processori di attività o log, che arricchiscono e filtrano i dati di telemetria.

Filtri per le Tracce

Per filtrare i dati di telemetria in OpenTelemetry, è possibile implementare un processore di attività. Questo esempio equivale all'esempio di Application Insights relativo al filtraggio dei dati di telemetria come descritto nella Documentazione di Monitoraggio di Azure. Nell'esempio si illustra dove vengono filtrate le chiamate di dipendenza non riuscite.

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

Per utilizzare questo processore, è necessario creare un TracerProvider e aggiungere il processore prima di AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

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

Filtri per i Log

Le implementazioni ILogger hanno un meccanismo integrato per applicare il filtro dei log. Questo filtro consente di controllare i log inviati a ogni provider registrato, incluso OpenTelemetryLoggerProvider. "OpenTelemetry" è l'alias di OpenTelemetryLoggerProvider, che viene utilizzato per la configurazione delle regole dei filtri.

L'esempio seguente definisce "Error" come LogLevel predefinito, inoltre definisce "Warning" come LogLevel minimo per una categoria definita dall'utente. Queste regole definite si applicano solo all'oggetto OpenTelemetryLoggerProvider.

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

Per altre informazioni, leggere la Documentazione di OpenTelemetry .NET sui log.

Aggiunta di proprietà personalizzate alle Tracce

In OpenTelemetry è possibile usare i processori di attività per arricchire i dati di telemetria con altre proprietà. Questa è un'operazione simile all'uso degli inizializzatori di telemetria in Application Insights, dove è possibile modificare le proprietà di telemetria.

Per impostazione predefinita, l'utilità di esportazione di Monitoraggio di Azure contrassegna qualsiasi richiesta HTTP con un codice di risposta pari o superiore a 400 come non riuscita. Tuttavia, se si vuole considerare 400 come esito della richiesta riuscito, è possibile aggiungere un processore di attività di arricchimento che imposta l'esito positivo dell'attività e aggiunge un tag per includere altre proprietà di telemetria. Questa operazione è simile all'aggiunta o alla modifica di proprietà mediante un inizializzatore in Application Insights, come descritto nella Documentazione di Monitoraggio di Azure.

Di seguito è riportato un esempio relativo all'aggiunta di proprietà personalizzate e a come eseguire l'override del comportamento predefinito per determinati codici di risposta:

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

Per utilizzare questo processore, è necessario creare un TracerProvider e aggiungere il processore prima di AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

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

Come è possibile tenere traccia manualmente dei dati di telemetria con OpenTelemetry?

Invio di Tracce - Manuale

Le tracce in Application Insights vengono archiviate come RequestTelemetry e DependencyTelemetry. In OpenTelemetry le tracce vengono modellate come Span usando la classe Activity.

OpenTelemetry .NET si avvale delle classi ActivitySource e Activity per le tracce, che fanno parte del runtime .NET. Questo approccio si distingue perché l'implementazione di .NET integra l'API di traccia direttamente nel runtime. Il pacchetto System.Diagnostics.DiagnosticSource consente agli sviluppatori di usare ActivitySource per creare e gestire le istanze di tipo Activity. Questo metodo offre un modo semplice per aggiungere le tracce alle applicazioni .NET senza affidarsi a librerie esterne e applicando le funzionalità integrate dell'ecosistema .NET. Per informazioni più dettagliate, consultare le Procedure dettagliate della strumentazione della traccia distribuita.

Di seguito si illustra come eseguire la migrazione della traccia manuale:

Nota

In Application Insights il nome del ruolo e l'istanza del ruolo possono essere impostati a livello di telemetria. Tuttavia, con l'utilità di esportazione di Monitoraggio di Azure non è possibile eseguire la personalizzazione al livello dei singoli dati di telemetria. Il nome del ruolo e l'istanza del ruolo vengono estratti dalla risorsa OpenTelemetry e applicati a tutti i dati di telemetria. Leggere questo documento per altre informazioni: Impostare il nome del ruolo cloud e l'istanza del ruolo cloud.

DependencyTelemetry

DependencyTelemetry di Application Insights consente di modellare le richieste in uscita. Di seguito si riporta il metodo per eseguire la conversione a OpenTelemetry:

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

Esempio di 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

RequestTelemetry di Application Insights esegue la modellazione delle richieste in ingresso. Ecco come eseguirne la migrazione a OpenTelemetry:

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

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

Rilevamento di operazioni personalizzate

In Application Insights, tenere traccia delle operazioni personalizzate usando i metodi StartOperation e StopOperation. Per ottenere questo risultato, usare ActivitySource e Activity in OpenTelemetry .NET. Per le operazioni con ActivityKind.Server e ActivityKind.Consumer, l'utilità di esportazione di Monitoraggio di Azure genera RequestTelemetry. Per ActivityKind.Client, ActivityKind.Producer e ActivityKind.Internal genera DependencyTelemetry. Per altre informazioni sul rilevamento di operazioni personalizzate, vedere la Documentazione di Monitoraggio di Azure. Per altre informazioni sull'uso di ActivitySource e Activity in .NET, vedere le Procedure dettagliate sulla strumentazione della traccia distribuita .NET.

Di seguito si riporta un esempio relativo all'avviamento e all'arresto di un'attività per le operazioni personalizzate:

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

Invio di Log

I Log in Application Insights vengono archiviati come TraceTelemetry e ExceptionTelemetry.

TraceTelemetry

In OpenTelemetry la registrazione viene integrata tramite l'interfaccia ILogger. Ecco come eseguire la migrazione di TraceTelemetry:

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

Esempio di 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(loggerOptions =>
   {
       loggerOptions.SetResourceBuilder(resourceBuilder);
       loggerOptions.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 usa ExceptionTelemetry per registrare le eccezioni. Ecco come eseguire la migrazione a OpenTelemetry:

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

Esempio di 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(loggerOptions =>
   {
       loggerOptions.SetResourceBuilder(resourceBuilder);
       loggerOptions.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");
}

Invio di Metriche

Le Metriche in Application Insights vengono archiviate come MetricTelemetry. In OpenTelemetry le metriche vengono modellate come Meter dal pacchetto System.Diagnostics.DiagnosticSource.

Application Insights include API metriche di preaggregazione (TrackMetric()) e non preaggregazione (GetMetric().TrackValue()). A differenza di OpenTelemetry, Application Insights non ha alcuna nozione di Strumenti. Application Insights ha la stessa API per tutti gli scenari relativi alla metrica.

D'altro canto, OpenTelemetry prima di tutto chiede agli utenti di scegliere lo strumento di metrica corretto in base alla semantica effettiva della metrica. Ad esempio, se l'obiettivo è effettuare un conteggio (ad esempio il numero totale di richieste server ricevute, ecc.), si consiglia di utilizzare il Contatore di OpenTelemetry. Se l'obiettivo è calcolare i diversi percentili (ad esempio, il valore P99 della latenza server), in questo caso si consiglia si utilizzare lo strumento Istogramma di OpenTelemetry. A causa di questa fondamentale differenza tra Application Insights e OpenTelemetry, non si opera alcun confronto diretto tra loro.

Diversamente da Application Insights, OpenTelemetry non fornisce meccanismi incorporati per arricchire o filtrare le metriche. In Application Insights i processori e gli inizializzatori dei dati telemetria possono essere usati per modificare o rimuovere le metriche, ma questa funzionalità non è disponibile in OpenTelemetry.

Inoltre, OpenTelemetry non supporta l'invio diretto di metriche non elaborate, perché non è disponibile alcun equivalente della funzionalità TrackMetric() in Application Insights.

La migrazione da Application Insights a OpenTelemetry comporta la sostituzione di tutti gli utilizzi dell'API di metrica di Application Insights con l'API di OpenTelemetry. Ciò richiede la conoscenza dei vari Strumenti OpenTelemetry e della relativa semantica.

Suggerimento

L'istogramma è l'equivalente più versatile e simile all'API GetMetric().TrackValue() di Application Insights. Per ottenere lo stesso scopo, è possibile sostituire le API di metrica di Application Insights con l'Istogramma.

Altri tipi di dati di telemetria

CustomEvents

Non supportato in OpenTelemetry.

Esempio di Application Insights:

TelemetryClient.TrackEvent()
AvailabilityTelemetry

Non supportato in OpenTelemetry.

Esempio di Application Insights:

TelemetryClient.TrackAvailability()
PageViewTelemetry

Non supportato in OpenTelemetry.

Esempio di Application Insights:

TelemetryClient.TrackPageView()

Passaggi successivi

Suggerimento

Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.

Supporto tecnico