Partager via

Migrer du Kit de développement logiciel (SDK) Application Insights .NET vers Azure Monitor OpenTelemetry

  • Article

Ce guide fournit des instructions étapes par étapes afin de migrer différentes applications .NET à l’aide de kits de développement logiciel (SDK) Application Insights vers Azure Monitor OpenTelemetry.

Attendez-vous à une expérience similaire avec l’instrumentation OpenTelemetry de Azure Monitor comme avec les kits de développement logiciel (SDK) Application Insights. Pour plus d’informations et une comparaison des fonctionnalités, consultez État de publication des fonctionnalités.

Si vous débutez dans l’utilisation de Application Insights et que vous n’avez pas besoin de migrer à partir de l’API classique, consultez Activer Azure Monitor OpenTelemetry.

Prérequis

  • Une application web ASP.NET Core déjà instrumentée avec Application Insights sans aucune personnalisation
  • Version activement prise en charge de .NET

Conseil

Notre groupe de produits recherche activement des commentaires sur cette documentation. Fournissez des commentaires sur otel@microsoft.com ou consultez la section Assistance.

Supprimez le kit de développement logiciel (SDK) Application Insights

Remarque

Avant de poursuivre ces étapes, vous devez confirmer que vous disposez d’une sauvegarde actuelle de votre application.

  1. Supprimer les packages NuGet

    Supprimer le package Microsoft.ApplicationInsights.AspNetCore de votre csproj.

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. Supprimer le code d’initialisation et les personnalisations

    Supprimez les références aux types Application Insights de votre codebase.

    Conseil

    Après avoir supprimé le package Application Insights, vous pouvez reconstruire votre application pour obtenir une liste des références qui nécessitent d’être supprimées.

    • Supprimez Application Insights de votre ServiceCollection en supprimant la ligne suivante :

      builder.Services.AddApplicationInsightsTelemetry();

    • Supprimez la section ApplicationInsights de votre appsettings.json.

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

  3. Nettoyer et construire

    Inspectez votre répertoire bin pour vérifier que toutes les références à Microsoft.ApplicationInsights.* ont été supprimées.

  4. Tester votre application

    Vérifiez que votre application n’a aucune conséquence inattendue.

Conseil

Notre groupe de produits recherche activement des commentaires sur cette documentation. Fournissez des commentaires sur otel@microsoft.com ou consultez la section Assistance.

Activer OpenTelemetry

Nous vous recommandons de créer une ressource de développement et d’utiliser sa chaîne de connexion lors de l’application de ces instructions.

Capture d’écran montrant la vue d’ensemble d’Application Insights et la chaîne de connexion.

Prévoyez de mettre à jour la chaîne de connexion pour envoyer des données de télémétrie à la ressource d’origine après la réussite de la migration.

  1. Installer la distribution Azure Monitor

    Notre distribution Azure Monitor permet une télémétrie automatique en incluant les bibliothèques d’instrumentation OpenTelemetry pour collecter des traces, des métriques, des journaux et des exceptions, et permet de collecter des données de télémétrie personnalisées.

    L’installation de la distribution Azure Monitor apporte le Kit de développement logiciel (SDK) OpenTelemetry en tant que dépendance.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Ajouter et configurer OpenTelemetry et Azure Monitor

    Le Kit de développement logiciel (SDK) OpenTelemery doit être configuré au démarrage de l’application dans le cadre de votre ServiceCollection, généralement dans le Program.cs.

    OpenTelemetry a un concept de trois signaux; traces, métriques et journaux. La distribution Azure Monitor configure chacun de ces signaux.

Program.cs

L'exemple de code suivant montre les informations de base.

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

Nous vous recommandons de définir votre chaîne de connexion au sein d’une variable d’environnement :

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

D’autres options pour configurer la chaîne de connexion sont détaillées ici : Configurer la chaîne de connexion Application Insights.

Conseil

Notre groupe de produits recherche activement des commentaires sur cette documentation. Fournissez des commentaires sur otel@microsoft.com ou consultez la section Assistance.

Installer et configurer des bibliothèques d’instrumentation

Bibliothèques d’instrumentation peuvent être ajoutées à votre projet pour collecter automatiquement des données de télémétrie sur des composants ou des dépendances spécifiques.

Les bibliothèques suivantes sont incluses dans la distribution.

Personnalisation des bibliothèques d’instrumentation

La distribution Azure Monitor inclut l’instrumentation .NET OpenTelemetry pour ASP.NET Core, HttpClientet SQLClient. Vous pouvez personnaliser ces instrumentations incluses ou ajouter manuellement une instrumentation supplémentaire à l’aide de l’API OpenTelemetry.

Voici quelques exemples de personnalisation de l’instrumentation :

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

Nous offrons l’instrumentation SQLClient dans notre package, bien qu’elle est toujours en version bêta. Lorsqu’elle atteint une version stable, nous l’incluons comme référence de package standard. Jusqu’ici, pour personnaliser l’instrumentation SQLClient, ajoutez la référence de package OpenTelemetry.Instrumentation.SqlClient à votre projet et utilisez son API publique.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

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

Configurer Azure Monitor

Application Insights offre de nombreuses options de configuration supplémentaires via ApplicationInsightsServiceOptions.

Paramètres Application Insights Alternative à OpenTelemetry
AddAutoCollectedMetricExtractor S/O
ApplicationVersion Définir « service.version » sur ressource
ConnectionString Consultez les instructions sur la configuration de la chaîne de connexion.
DependencyCollectionOptions N/A. Pour personnaliser les dépendances, passez en revue les options de configuration disponibles pour les bibliothèques d’instrumentation applicables.
DeveloperMode S/O
EnableActiveTelemetryConfigurationSetup S/O
EnableAdaptiveSampling N/A. Seul l’échantillonnage à fréquence fixe est pris en charge.
EnableAppServicesHeartbeatTelemetryModule S/O
EnableAuthenticationTrackingJavaScript S/O
EnableAzureInstanceMetadataTelemetryModule S/O
EnableDependencyTrackingTelemetryModule Consultez les instructions sur le filtrage des traces.
EnableDiagnosticsTelemetryModule S/O
EnableEventCounterCollectionModule S/O
EnableHeartbeat S/O
EnablePerformanceCounterCollectionModule S/O
EnableQuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule Consultez les instructions sur le filtrage des traces.
EndpointAddress Utiliser ConnectionString.
InstrumentationKey Utiliser ConnectionString.
RequestCollectionOptions N/A. Consultez les options OpenTelemetry.Instrumentation.AspNetCore.

Supprimer les configurations personnalisées

Les scénarios suivants sont facultatifs et s’appliquent uniquement aux utilisateurs avancés.

  • Si vous avez encore des références au TelemetryClient, qui peuvent être utilisées pour enregistrer manuellement les données de télémétrie, elles doivent être supprimées.

  • Si vous avez ajouté du tri ou de l’enrichissement personnalisé sous la forme d’un TelemetryProcessor personnalisé ou d’un TelemetryInitializer, ils doivent être supprimés. Elles peuvent être trouvées dans votre ServiceCollection.

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

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • Supprimer l’extrait de code JavaScript

    Si vous avez utilisé l’extrait de code fourni par le Kit de développement logiciel (SDK) .NET Application Insights, il doit également être supprimé. Pour obtenir des exemples de code complets sur la suppression, consultez le guide activer la télémétrie côté client pour les applications web.

    Si vous avez ajouté le Kit de développement logiciel (SDK) JavaScript pour collecter des données de télémétrie côté client, il peut également être supprimé bien qu’il continue de fonctionner sans le Kit de développement logiciel (SDK) .NET. Pour obtenir des exemples de code complets sur les éléments à supprimer, consultez le guide d’intégration pour le kit de développement logiciel (SDK) JavaScript.

  • Supprimer tous les artefacts Visual Studio

    Si vous avez utilisé Visual Studio pour intégrer Application Insights, vous pourriez avoir plus de fichiers laissés dans votre projet.

    • Le répertoire Properties/ServiceDependencies pourrait avoir une référence à votre ressource Application Insights.

Conseil

Notre groupe de produits recherche activement des commentaires sur cette documentation. Fournissez des commentaires sur otel@microsoft.com ou consultez la section Assistance.

Forum aux questions

Cette section concerne les clients qui utilisent des initialiseurs ou processeurs de télémétrie, ou qui écrivent du code personnalisé sur l’API Application Insights classique pour créer des données de télémétrie personnalisées.

Comment l’API du kit de développement logiciel (SDK) est-elle mappées aux concepts OpenTelemetry ?

OpenTelemetry est un framework d’observabilité neutre du fournisseur. Il n’existe aucune API Application Insights dans le Kit de développement logiciel (SDK) OpenTelemetry ou les bibliothèques. Avant de migrer, il est important de comprendre certains concepts d’OpenTelemetry.

  • Dans Application Insights, toutes les données de télémétrie ont été gérées via une seule TelemetryClient et TelemetryConfiguration. Dans OpenTelemetry, chacun des trois signaux de télémétrie (Traces, Métriques et Journaux) possède sa propre configuration. Vous pouvez créer manuellement des données de télémétrie via le runtime .NET sans bibliothèques externes. Pour plus d’informations, consultez les guides .NET sur le suivi distribué, les métriqueset la journalisation.

  • Application Insights a utilisé TelemetryModules pour collecter automatiquement des données de télémétrie pour votre application. Au lieu de cela, OpenTelemetry utilise des Bibliothèques d’instrumentation pour collecter des données de télémétrie à partir de composants spécifiques (par exemple, AspNetCore pour les requêtes et HttpClient pour les dépendances).

  • Application Insights a utilisé TelemetryInitializers pour enrichir les données de télémétrie avec des informations supplémentaires ou pour remplacer les propriétés. Avec OpenTelemetry, vous pouvez écrire un Processeur pour personnaliser un signal spécifique. De plus, de nombreuses bibliothèques OpenTelemetry Instrumentation offrent une méthode Enrich pour personnaliser les données de télémétrie générées par ce composant spécifique.

  • Application Insights a utilisé TelemetryProcessors pour filtrer la télémétrie. Un de Processeur OpenTelemetry peut également être utilisé pour appliquer des règles de filtrage sur un signal spécifique.

Comment les types de télémétrie Application Insights sont-ils mappés à OpenTelemetry ?

Ce tableau mappe les types de données Application Insights aux concepts OpenTelemetry et à leurs implémentations .NET.

Table Azure Monitor Application Insights DataType OpenTelemetry DataType Implémentation de .NET
customEvents EventTelemetry N/A N/A
customMetrics MetricTelemetry Métriques System.Diagnostics.Metrics.Meter
dependencies DependencyTelemetry Étendues (Client, interne, consommateur) System.Diagnostics.Activity
exceptions ExceptionTelemetry Exceptions System.Exception
requests RequestTelemetry Étendues (serveur, producteur) System.Diagnostics.Activity
traces TraceTelemetry Journaux d’activité Microsoft.Extensions.Logging.ILogger

Les documents suivants fournissent plus d’informations.

Comment les concepts d’échantillonnage Application Insights sont-ils mappés à OpenTelemetry ?

Même si Application Insights propose plusieurs options pour configurer l’échantillonnage, Azure Monitor Exporter ou Azure Monitor Distro propose uniquement un échantillonnage à taux fixe. Seules les Requêtes et les Dépendances (OpenTelemetry Traces) peuvent être échantillonnés.

Pour plus d’informations sur la configuration de l’échantillonnage, consultez notre guide Activer l’échantillonnage

Comment les processeurs de télémétrie et les initialiseurs sont-ils mappés à OpenTelemetry ?

Dans le Kit de développement logiciel (SDK) .NET Application Insights, utilisez des processeurs de télémétrie pour filtrer et modifier ou ignorer les données de télémétrie. Utilisez des initialiseurs de télémétrie pour ajouter ou modifier des propriétés personnalisées. Pour plus d’informations, consultez la Documentation Azure Monitor. OpenTelemetry remplace ces concepts par des processeurs d’activité ou de journal, qui enrichissent et filtrent les données de télémétrie.

Filtrage des traces

Pour filtrer les données de télémétrie dans OpenTelemetry, vous pouvez implémenter un processeur d’activité. Cet exemple équivaut à l’exemple Application Insights pour filtrer les données de télémétrie, comme décrit dans la Documentation Azure Monitor. L’exemple montre où les appels de dépendance infructueux sont filtrés.

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

Pour utiliser ce processeur, vous devez créer un TracerProvider et ajouter le processeur avant AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

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

Filtrage des journaux d'activité

Les implémentations ILogger disposent d’un mécanisme intégré pour appliquer le filtrage des journaux. Ce filtrage vous permet de contrôler les journaux qui sont envoyés à chaque fournisseur inscrit, y compris au OpenTelemetryLoggerProvider. « OpenTelemetry » est l’alias pour OpenTelemetryLoggerProvider, utilisé pour configurer des règles de filtrage.

L’exemple suivant définit « Erreur » comme LogLevel par défaut et définit également « Avertissement » comme LogLevel minimum pour une catégorie définie par l’utilisateur. Ces règles telles que définies s’appliquent uniquement aux OpenTelemetryLoggerProvider.

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

Pour plus d’informations, consultez la documentation OpenTelemetry .NET sur les journaux d’activité.

Ajout de propriétés personnalisées à Traces

Dans OpenTelemetry, vous pouvez utiliser des processeurs d’activité pour enrichir les données de télémétrie avec plus de propriétés. Il est similaire à l’utilisation des initialiseurs de télémétrie dans Application Insights, où vous pouvez modifier les propriétés de télémétrie.

Par défaut, l’exportateur Azure Monitor signale toute requête HTTP avec un code de réponse 400 ou supérieur en cas d’échec. Toutefois, si vous souhaitez traiter 400 comme une réussite, vous pouvez ajouter un processeur d’activité enrichi qui définit la réussite sur l’activité et ajoute une balise pour inclure davantage de propriétés de télémétrie. Il est similaire à l’ajout ou à la modification de propriétés à l’aide d’un initialiseur dans Application Insights, comme décrit dans la Documentation Azure Monitor.

Voici un exemple d’ajout de propriétés personnalisées et de remplacement du comportement par défaut pour certains codes de réponse :

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

Pour utiliser ce processeur, vous devez créer un TracerProvider et ajouter le processeur avant AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

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

Comment faire pour suivre manuellement la télémétrie à l’aide de OpenTelemetry ?

Envoi de traces : Manuel

Les traces dans Application Insights sont stockées en tant que RequestTelemetry et DependencyTelemetry. Dans OpenTelemetry, les traces sont modélisées comme Span à l’aide de la classe Activity.

OpenTelemetry .NET utilise les classes ActivitySource et Activity pour le suivi, qui font partie du runtime .NET. Cette approche est distinctive car l’implémentation .NET intègre directement l’API de suivi dans le runtime lui-même. Le package System.Diagnostics.DiagnosticSource permet aux développeurs d’utiliser ActivitySource pour créer et gérer des instances Activity. Cette méthode offre un moyen transparent d’ajouter le suivi aux applications .NET sans compter sur des bibliothèques externes, en appliquant les fonctionnalités intégrées de l’écosystème .NET. Pour plus d’informations, reportez-vous aux procédures pas à pas de l’instrumentation de suivi distribué.

Voici comment migrer le suivi manuel :

Remarque

Dans Application Insights, le nom du rôle et l’instance de rôle peuvent être définis à un niveau de télémétrie par télémétrie. Toutefois, avec l’exportateur Azure Monitor, nous ne pouvons pas personnaliser au niveau par télémétrie. Le nom du rôle et l’instance de rôle sont extraits de la ressource OpenTelemetry et appliqués à toutes les données de télémétrie. Pour plus d’informations, lisez ce document : Définir le nom du rôle cloud et l’instance de rôle cloud.

DependencyTelemetry

Application Insights DependencyTelemetry est utilisé pour modéliser les requêtes sortantes. Voici comment la convertir en OpenTelemetry :

Exemples d’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);

Exemple de 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 modélise les requêtes entrantes. Voici comment le migrer vers OpenTelemetry :

Exemples d’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);

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

Suivi des opérations personnalisées

Dans Application Insights, suivre les opérations personnalisées à l’aide des méthodes StartOperation et StopOperation. Accomplissez le à l’aide de ActivitySource et de Activity dans OpenTelemetry .NET. Pour les opérations avec ActivityKind.Server et ActivityKind.Consumer, l’exportateur Azure Monitor génère des RequestTelemetry. Pour ActivityKind.Client, ActivityKind.Producer et ActivityKind.Internal, il génère DependencyTelemetry. Pour plus d’informations sur le suivi des opérations personnalisées, consultez la documentation Azure Monitor. Pour plus d’informations sur l’utilisation de ActivitySource et de Activity dans .NET, consultez les Procédures pas à pas de l’instrumentation de suivi distribué .NET.

Voici un exemple de démarrage et d’arrêt d’une activité pour les opérations personnalisées :

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

Envoi de journaux d'activité

Les journaux d'activité dans Application Insights sont stockées en tant que TraceTelemetry et ExceptionTelemetry.

TraceTelemetry

Dans OpenTelemetry, la journalisation est intégrée via l’interface ILogger. Voici comment migrer TraceTelemetry :

Exemples d’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);

Exemple de 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 utilise ExceptionTelemetry pour rentrer les exceptions dans le journal d’activité. Voici comment migrer vers OpenTelemetry :

Exemples d’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);

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

Envoi de métriques

Les métriques dans Application Insights sont stockées en tant que MetricTelemetry. Dans OpenTelemetry, les métriques sont modélisées en tant que Meter à partir du package System.Diagnostics.DiagnosticSource.

Application Insights possède à la fois des API de métrique non pré-agrée (TrackMetric()) et pré-agrée (GetMetric().TrackValue()). Contrairement à OpenTelemetry, Application Insights n’a aucune notion de Instruments. Application Insights a la même API pour tous les scénarios de métrique.

OpenTelemetry, en revanche, exige que les utilisateurs commencent par choisir l’instrument de métrique approprié en fonction de la sémantique réelle de la métrique. Par exemple, si l’intention est de compter quelque chose (comme le nombre total de demandes de serveur reçues, etc.), le Compteur OpenTelemetry doit être utilisé. Si l’intention est de calculer différents centiles (comme la valeur P99 de la latence du serveur), l’instrument Histogramme OpenTelemetry doit être utilisé. En raison de cette différence fondamentale entre Application Insights et OpenTelemetry, aucune comparaison directe n’est effectuée entre elles.

Contrairement à Application Insights, OpenTelemetry ne fournit pas de mécanismes intégrés pour enrichir ou filtrer les métriques. Dans Application Insights, les processeurs de télémétrie et les initialiseurs peuvent être utilisés pour modifier ou ignorer les métriques, mais cette fonctionnalité n’est pas disponible dans OpenTelemetry.

En outre, OpenTelemetry ne prend pas en charge l’envoi de métriques brutes directement car il n’existe aucun équivalent à la fonctionnalité TrackMetric() trouvée dans Application Insights.

La migration d’Application Insights vers OpenTelemetry implique de remplacer toutes les utilisations de l’API de métrique Application Insights par l’API OpenTelemetry. Il faut comprendre les différents instruments OpenTelemetry et leur sémantique.

Conseil

L’histogramme est l’équivalent le plus versatile et le plus proche de l’API Application Insights GetMetric().TrackValue(). Vous pouvez remplacer les API de métrique Application Insights par histogramme afin d’atteindre le même objectif.

Autres types de télémétrie

CustomEvents

Non pris en charge dans OpenTelemetry.

Exemples d’Application Insights :

TelemetryClient.TrackEvent()
AvailabilityTelemetry

Non pris en charge dans OpenTelemetry.

Exemples d’Application Insights :

TelemetryClient.TrackAvailability()
PageViewTelemetry

Non pris en charge dans OpenTelemetry.

Exemples d’Application Insights :

TelemetryClient.TrackPageView()

Étapes suivantes

Conseil

Notre groupe de produits recherche activement des commentaires sur cette documentation. Fournissez des commentaires sur otel@microsoft.com ou consultez la section Assistance.

Support