Migración desde los SDK de Application Insights para .NET a OpenTelemetry de Azure Monitor

  • Artículo

En esta guía se proporcionan instrucciones paso a paso para migrar varias aplicaciones .NET desde el uso de kits de desarrollo de software (SDK) de Application Insights a OpenTelemetry de Azure Monitor.

Espere una experiencia similar con la instrumentación de OpenTelemetry de Azure Monitor como con los SDK de Application Insights. Para más información y una comparación de las características individuales,vea Estado de versión de las características.

Si va a empezar a trabajar con Application Insights y no es necesario migrar desde Classic API, vea Habilitación de OpenTelemetry de Azure Monitor.

Requisitos previos

  • Una aplicación web de ASP.NET Core ya instrumentada con Application Insights sin ninguna personalización
  • Una versión admitida activamente de .NET

Sugerencia

Nuestro grupo de productos busca activamente comentarios sobre esta documentación. Proporcione comentarios sobre otel@microsoft.com o vea la sección Soporte técnico.

Eliminación del SDK de Application Insights

Nota:

Antes de continuar con estos pasos, debe confirmar que tiene una copia de seguridad actual de la aplicación.

  1. Eliminación de paquetes NuGet

    Quite el paquete Microsoft.ApplicationInsights.AspNetCore de csproj.

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. Eliminación del código de inicialización y las personalizaciones

    Quite las referencias a los tipos de Application Insights en el código base.

    Sugerencia

    Después de quitar el paquete de Application Insights, puede volver a compilar la aplicación para obtener una lista de referencias que se deben quitar.

    • Quite Application Insights de ServiceCollection mediante la eliminación de la siguiente línea:

      builder.Services.AddApplicationInsightsTelemetry();

    • Quite la sección ApplicationInsights de appsettings.json.

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

  3. Limpieza y compilación

    Inspeccione el directorio bin para validar que se han quitado todas las referencias a Microsoft.ApplicationInsights.*.

  4. Prueba de la aplicación

    Compruebe que la aplicación no tiene consecuencias inesperadas.

Sugerencia

Nuestro grupo de productos busca activamente comentarios sobre esta documentación. Proporcione comentarios sobre otel@microsoft.com o vea la sección Soporte técnico.

Habilitación de OpenTelemetry

Se recomienda crear un recurso de desarrollo y usar su cadena de conexión al seguir estas instrucciones.

Captura de pantalla que muestra una cadena de conexión de Application Insights.

Planee actualizar la cadena de conexión para enviar telemetría al recurso original después de confirmar que la migración se ha realizado correctamente.

  1. Instalación de la distribución de Azure Monitor

    La distribución de Azure Monitor habilita la telemetría automática mediante la inclusión de bibliotecas de instrumentación de OpenTelemetry para recopilar seguimientos, métricas, registros y excepciones, y permite recopilar telemetría personalizada.

    Al instalar la distribución de Azure Monitor, se agrega el SDK de OpenTelemetry como dependencia.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Incorporación y configuración de OpenTelemetry y Azure Monitor

    El SDK de OpenTelemery se debe configurar en el inicio de la instancia de ServiceCollection, normalmente en Program.cs.

    OpenTelemetry tiene un concepto de tres señales; seguimientos, métricas y registros. La distribución de Azure Monitor configura cada una de estas señales.

Program.cs

En el código de ejemplo siguiente se muestran los aspectos básicos.

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

Se recomienda establecer la cadena de conexión en una variable de entorno:

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

Aquí se detallan más opciones para configurar la cadena de conexión: Configuración de la cadena de conexión de Application Insights.

Sugerencia

Nuestro grupo de productos busca activamente comentarios sobre esta documentación. Proporcione comentarios sobre otel@microsoft.com o vea la sección Soporte técnico.

Instalación y configuración de bibliotecas de instrumentación

Se pueden agregar bibliotecas de instrumentación al proyecto para recopilar automáticamente datos de telemetría sobre componentes o dependencias específicos.

Las bibliotecas siguientes se incluyen en la distribución.

Personalización de bibliotecas de instrumentación

La distribución de Azure Monitor incluye la instrumentación OpenTelemetry de .NET para ASP.NET Core, HttpClient y SQLClient. Puede personalizar estas instrumentaciones incluidas o agregar manualmente instrumentación adicional por su cuenta mediante OpenTelemetry API.

Estos son algunos ejemplos de cómo personalizar la instrumentación:

Personalización 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);
    };
});
Personalización 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);
    };
});
Personalización de SqlClientInstrumentationOptions

Dentro del paquete se proporciona la instrumentación SQLClient, aunque todavía está en versión beta. Cuando llegue a una versión estable, se incluirá como referencia de paquete estándar. Hasta entonces, para personalizar la instrumentación SQLClient, agregue la referencia del paquete OpenTelemetry.Instrumentation.SqlClient al proyecto y use su API pública.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

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

Configuración de Azure Monitor

Application Insights ofrece muchas más opciones de configuración mediante ApplicationInsightsServiceOptions.

Valor de Application Insights Alternativa de OpenTelemetry
AddAutoCollectedMetricExtractor N/D
ApplicationVersion Establecimiento de "service.version" en el recurso
ConnectionString Vea las instrucciones sobre cómo configurar la cadena de conexión.
DependencyCollectionOptions N/D Para personalizar las dependencias, revise las opciones de configuración disponibles para las bibliotecas de instrumentación aplicables.
DeveloperMode N/D
EnableActiveTelemetryConfigurationSetup N/D
EnableAdaptiveSampling N/D Solo se admite el muestreo de frecuencia fija.
EnableAppServicesHeartbeatTelemetryModule N/D
EnableAuthenticationTrackingJavaScript N/D
EnableAzureInstanceMetadataTelemetryModule N/D
EnableDependencyTrackingTelemetryModule Vea las instrucciones sobre el filtrado de seguimientos.
EnableDiagnosticsTelemetryModule N/D
EnableEventCounterCollectionModule N/D
EnableHeartbeat N/D
EnablePerformanceCounterCollectionModule N/D
EnableQuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule Vea las instrucciones sobre el filtrado de seguimientos.
EndpointAddress Use ConnectionString.
InstrumentationKey Use ConnectionString.
RequestCollectionOptions N/D Vea Opciones de OpenTelemetry.Instrumentation.AspNetCore.

Eliminación de configuraciones personalizadas

Los siguientes escenarios son opcionales y solo se aplican a los usuarios avanzados.

  • Si tiene más referencias a TelemetryClient, que se puedan usan para registrar manualmente la telemetría, se deben quitar.

  • Si ha agregado algún filtrado personalizado o enriquecimiento en forma de instancia personalizada de TelemetryProcessor o TelemetryInitializer, se deben quitar. Se pueden encontrar en la instancia de ServiceCollection.

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

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • Eliminación del fragmento de código de JavaScript

    Si ha usado el fragmento de código proporcionado por el SDK de .NET de Application Insights, también se debe quitar. Para obtener ejemplos de código completos de lo que se va a quitar, revise la guía Habilitación de la telemetría del lado cliente para aplicaciones web.

    Si ha agregado el SDK de JavaScript para recopilar telemetría del lado cliente, también se puede quitar aunque sigue funcionando sin el SDK de .NET. Para obtener ejemplos de código completos de lo que se va a quitar, revise la guía de incorporación de para el SDK de JavaScript.

  • Eliminación de cualquier artefacto de Visual Studio

    Si ha usado Visual Studio para la incorporación a Application Insights, podría tener más archivos en el proyecto.

    • Es posible que el directorio Properties/ServiceDependencies tenga una referencia al recurso de Application Insights.

Sugerencia

Nuestro grupo de productos busca activamente comentarios sobre esta documentación. Proporcione comentarios sobre otel@microsoft.com o vea la sección Soporte técnico.

Preguntas más frecuentes

Esta sección es para los clientes que usan inicializadores de telemetría o procesadores, o bien que escriben código personalizado en la API clásica de Application Insights para crear telemetría personalizada.

¿Cómo se asigna la API del SDK a los conceptos de OpenTelemetry?

OpenTelemetry es un marco de observabilidad independiente del proveedor. No hay ninguna API de Application Insights en el SDK ni las bibliotecas de OpenTelemetry. Antes de realizar la migración, es importante comprender algunos de los conceptos de OpenTelemetry.

  • En Application Insights, toda la telemetría se administra mediante una sola instancia de TelemetryClient y TelemetryConfiguration. En OpenTelemetry, cada una de las tres señales de telemetría (seguimientos, métricas y registros) tiene su propia configuración. Puede crear manualmente la telemetría desde el runtime de .NET sin bibliotecas externas. Para más información, vea las guías de .NET sobre seguimiento distribuido, métricas y registro.

  • En Application Insights se usaba TelemetryModules para recopilar datos de telemetría automáticamente para la aplicación. En su lugar, OpenTelemetry usa bibliotecas de instrumentación para recopilar datos de telemetría de componentes específicos (como AspNetCore para las solicitudes y HttpClient para las dependencias).

  • En Application Insights se usaba TelemetryInitializers para enriquecer la telemetría con información adicional o para invalidar las propiedades. Con OpenTelemetry, puede escribir un procesador para personalizar una señal específica. Además, muchas bibliotecas de instrumentación de OpenTelemetry ofrecen un método Enrich para personalizar la telemetría generada por ese componente específico.

  • En Application Insights se usaba TelemetryProcessors para filtrar la telemetría. También se puede usar un procesador de OpenTelemetry para aplicar reglas de filtrado a una señal específica.

¿Cómo se asignan los tipos de telemetría de Application Insights a OpenTelemetry?

En esta tabla se asignan los tipos de datos de Application Insights a los conceptos de OpenTelemetry y sus implementaciones de .NET.

Tabla de Azure Monitor Tipo de datos de Application Insights Tipo de datos de OpenTelemetry Implementación de .NET
customEvents EventTelemetry N/D N/D
customMetrics MetricTelemetry Métricas System.Diagnostics.Metrics.Meter
dependencies DependencyTelemetry Spans (Client, Internal, Consumer) System.Diagnostics.Activity
exceptions ExceptionTelemetry Excepciones System.Exception
requests RequestTelemetry Spans (Server, Producer) System.Diagnostics.Activity
traces TraceTelemetry Registros Microsoft.Extensions.Logging.ILogger

En los documentos siguientes se proporciona más información.

¿Cómo se asignan los conceptos de muestreo de Application Insights a OpenTelemetry?

Aunque Application Insights ofrecía muchas opciones para configurar el muestreo, el exportador de Azure Monitor o la distribución de Azure Monitor solo ofrece muestreo de frecuencia fija. Solo se pueden muestrear las solicitudes y las dependencias (seguimientos de OpenTelemetry).

Para obtener ejemplos de código en los que se detalla cómo configurar el muestreo, vea nuestra guía Habilitación del muestreo

¿Cómo se asignan los procesadores de telemetría y los inicializadores a OpenTelemetry?

En el SDK de .NET de Application Insights, se usan procesadores de telemetría para filtrar y modificar o descartar la telemetría. Use inicializadores de telemetría para agregar o modificar propiedades personalizadas. Para más información, vea la documentación de Azure Monitor. OpenTelemetry reemplaza estos conceptos por procesadores de actividad o registro, que enriquecen y filtran la telemetría.

Filtrado de seguimientos

Para filtrar los datos de telemetría en OpenTelemetry, puede implementar un procesador de actividad. Este ejemplo es equivalente al de Application Insights para filtrar los datos de telemetría, como se describe en la documentación de Azure Monitor. En el ejemplo se muestra dónde se filtran las llamadas de dependencia incorrectas.

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

Para usar este procesador, debe crear una instancia de TracerProvider y agregar el procesador antes de AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

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

Filtrado de registros

Las implementaciones de ILogger tienen un mecanismo integrado para aplicar el filtrado de registros. Este filtrado le permite controlar los registros que se envían a cada proveedor registrado, incluido OpenTelemetryLoggerProvider. "OpenTelemetry" es el alias de OpenTelemetryLoggerProvider, que se usa para configurar reglas de filtrado.

En el ejemplo siguiente se define "Error" como la instancia de LogLevel predeterminada y también se define "Warning" como la instancia de LogLevel mínima para una categoría definida por el usuario. Estas reglas, tal y como se definen, solo se aplican a OpenTelemetryLoggerProvider.

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

Para más información, lea la documentación de .NET de OpenTelemetry sobre registros.

Adición de propiedades personalizadas a seguimientos

En OpenTelemetry, puede usar procesadores de actividad para enriquecer los datos de telemetría con más propiedades. Es similar al uso de inicializadores de telemetría en Application Insights, donde puede modificar las propiedades de telemetría.

De manera predeterminada, el exportador de Azure Monitor marca cualquier solicitud HTTP con un código de respuesta de 400 o superior como error. Pero si quiere tratar 400 como correcto, puede agregar un procesador de actividad enriquecedor que establezca la actividad como correcta y agregue una etiqueta para incluir más propiedades de telemetría. Es similar a agregar o modificar propiedades mediante un inicializador en Application Insights, como se describe en la documentación de Azure Monitor.

Este es un ejemplo de cómo agregar propiedades personalizadas e invalidar el comportamiento predeterminado para determinados códigos de respuesta:

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

Para usar este procesador, debe crear una instancia de TracerProvider y agregar el procesador antes de AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

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

¿Cómo se realiza el seguimiento manual de la telemetría mediante OpenTelemetry?

Envío de seguimientos: manual

Los seguimientos de Application Insights se almacenan como RequestTelemetry y DependencyTelemetry. En OpenTelemetry, los seguimientos se modelan como Span mediante la clase Activity.

OpenTelemetry .NET usa las clases ActivitySource y Activity para el seguimiento, que forman parte del runtime de .NET. Este enfoque es único porque la implementación de .NET integra la API de seguimiento directamente en el propio runtime. El paquete System.Diagnostics.DiagnosticSource permite a los desarrolladores usar ActivitySource para crear y administrar instancias de Activity. Este método proporciona una manera perfecta de agregar seguimiento a aplicaciones de .NET sin depender de bibliotecas externas, mediante la aplicación de las funcionalidades integradas del ecosistema de .NET. Para obtener información detallada, consulte los tutoriales de instrumentación de seguimiento distribuido.

A continuación se muestra cómo migrar el seguimiento manual:

Nota:

En Application Insights, el nombre del rol y la instancia del rol se pueden establecer en un nivel de telemetría individual. Pero con el exportador de Azure Monitor no se puede personalizar en un nivel de telemetría individual. El nombre y la instancia de rol se extraen del recurso de OpenTelemetry y se aplican en todos los datos de telemetría. Lea este documento para más información: Establecimiento del nombre y la instancia de rol en la nube.

DependencyTelemetry

Application Insights DependencyTelemetry se usa para modelar las solicitudes salientes. Aquí se muestra cómo convertirlo en OpenTelemetry:

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

Ejemplo 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 modela las solicitudes entrantes. Aquí se muestra cómo migrarlo a OpenTelemetry:

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

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

Seguimiento de operaciones personalizadas

En Application Insights, el seguimiento de las operaciones personalizadas se realiza mediante los métodos StartOperation y StopOperation. En OpenTelemetry .NET se logra mediante ActivitySource y Activity. Para las operaciones con ActivityKind.Server y ActivityKind.Consumer, el exportador de Azure Monitor genera RequestTelemetry. Para ActivityKind.Client, ActivityKind.Producer y ActivityKind.Internal, genera DependencyTelemetry. Para más información sobre el seguimiento de operaciones personalizadas, vea la documentación de Azure Monitor. Para más información sobre el uso de ActivitySource y Activity en .NET, vea los tutoriales de instrumentación de seguimiento distribuido de .NET.

Este es un ejemplo de cómo iniciar y detener una actividad para las operaciones personalizadas:

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

Envío de registros

En Application Insights, los registros se almacenan como TraceTelemetry y ExceptionTelemetry.

TraceTelemetry

En OpenTelemetry, el registro se integra mediante la interfaz ILogger. Aquí se muestra cómo migrar TraceTelemetry:

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

Ejemplo 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(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

En Application Insights se usa ExceptionTelemetry para registrar excepciones. Aquí se muestra cómo realizar la migración a OpenTelemetry:

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

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

Envío de métricas

En Application Insights, las métricas se almacenan como MetricTelemetry. En OpenTelemetry, las métricas se modelan como Meter desde el paquete System.Diagnostics.DiagnosticSource.

Application Insights tiene API de métricas sin agregación previa (TrackMetric()) y con agregación previa (GetMetric().TrackValue()). A diferencia de OpenTelemetry, Application Insights no tiene ninguna noción de instrumentos. Application Insights tiene la misma API para todos los escenarios de métricas.

En OpenTelemetry, por otro lado, es necesario que los usuarios primero elijan el instrumento de métrica correcto en función de la semántica real de la métrica. Por ejemplo, si la intención es contar algo (como el número de solicitudes de servidor totales recibidas, etc.), se debe usar el Contador de OpenTelemetry. Si la intención es calcular varios percentiles (como el valor P99 de latencia del servidor), se debe usar el instrumento Histograma de OpenTelemetry. Debido a esta diferencia fundamental entre Application Insights y OpenTelemetry, no se realiza ninguna comparación directa entre los dos.

A diferencia de Application Insights, OpenTelemetry no proporciona mecanismos integrados para enriquecer o filtrar métricas. En Application Insights, se pueden usar procesadores de telemetría e inicializadores para modificar o descartar métricas, pero esta funcionalidad no está disponible en OpenTelemetry.

Además, OpenTelemetry no admite el envío de métricas sin procesar directamente, ya que no hay ningún equivalente a la funcionalidad de TrackMetric() que se encuentra en Application Insights.

La migración de Application Insights a OpenTelemetry implica reemplazar todos los usos de la API de métricas de Application Insights por la API de OpenTelemetry. Es necesario comprender los distintos instrumentos de OpenTelemetry y su semántica.

Sugerencia

El histograma es el equivalente más versátil y más cercano a la API GetMetric().TrackValue() de Application Insights. Puede reemplazar las API de métricas de Application Insights por el Histograma para lograr el mismo propósito.

Otros tipos de telemetría

CustomEvents

No se admite en OpenTelemetry.

Ejemplo de Application Insights:

TelemetryClient.TrackEvent()
AvailabilityTelemetry

No se admite en OpenTelemetry.

Ejemplo de Application Insights:

TelemetryClient.TrackAvailability()
PageViewTelemetry

No se admite en OpenTelemetry.

Ejemplo de Application Insights:

TelemetryClient.TrackPageView()

¿Puedo obtener métricas en tiempo real de las aplicaciones de consola y de servicio de trabajo?

Se recomienda el exportador de OpenTelemetry de Azure Monitor para aplicaciones de servicio de trabajo y de consola, que no incluyen métricas dinámicas.

Pasos siguientes

Sugerencia

Nuestro grupo de productos busca activamente comentarios sobre esta documentación. Proporcione comentarios sobre otel@microsoft.com o vea la sección Soporte técnico.

Soporte técnico