Compartir vía


Migración de los SDK de Classic API de Application Insights a OpenTelemetry de Azure Monitor

En esta guía se proporcionan instrucciones paso a paso para migrar aplicaciones del uso de SDK de Application Insights (API clásica) 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 obtener más información y una comparación de características por característica, consulte estado de versión de las características.

Usa el kit de desarrollo de software (SDK) de Application Insights 3.x para actualizarse del SDK 2.x a una implementación basada en OpenTelemetry (OTel). El SDK 3.x mantiene la mayoría de las TelemetryClientTelemetryConfiguration interfaces de programación de aplicaciones (APIs) y usa el OpenTelemetry Exporter de Azure Monitor para enviar telemetría a Application Insights.

La mayoría de las llamadas Track* clásicas siguen funcionando después de la actualización, pero se enrutan a través de una capa de asignación interna que emite señales de OpenTelemetry.

Si compila una nueva aplicación o ya usa la distribución openTelemetry de Azure Monitor, use la distribución openTelemetry de Azure Monitor en su lugar. No use el SDK de .NET de Application Insights 3.x y la distribución openTelemetry de Azure Monitor en la misma aplicación.

Introducción al SDK de .NET de Application Insights 3.x

Application Insights SDK 3.x proporciona estos paquetes NuGet:

  • Microsoft.ApplicationInsights para TelemetryClient y TelemetryConfiguration
  • Microsoft.ApplicationInsights.AspNetCore para aplicaciones web de ASP.NET (Active Server Pages .NET) Core
  • Microsoft.ApplicationInsights.WorkerService para aplicaciones de servicio de trabajo y consola
  • Microsoft.ApplicationInsights.Web para aplicaciones de ASP.NET en .NET Framework
  • Microsoft.ApplicationInsights.NLogTarget para integrar NLog (beta)

Use la documentación del repositorio para ver ejemplos de código y detalles de integración de OpenTelemetry:

Actualización a la versión 3.x

Paso 1: Quitar referencias a paquetes incompatibles

Quite estos paquetes porque no son compatibles con SDK 3.x:

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel
  • Microsoft.ApplicationInsights.DependencyCollector
  • Microsoft.ApplicationInsights.EventCounterCollector
  • Microsoft.ApplicationInsights.PerfCounterCollector
  • Microsoft.ApplicationInsights.WindowsServer
  • Microsoft.Extensions.Logging.ApplicationInsights
  • Microsoft.ApplicationInsights.Log4NetAppender
  • Microsoft.ApplicationInsights.TraceListener
  • Microsoft.ApplicationInsights.DiagnosticSourceListener
  • Microsoft.ApplicationInsights.EtwCollector
  • Microsoft.ApplicationInsights.EventSourceListener

SDK 3.x no publica versiones 3.x de estos paquetes. En su lugar, use los paquetes 3.x admitidos que se enumeran en descripción general del SDK de .NET de Application Insights 3.x.

Nota:

Esta lista incluye solo paquetes de Microsoft. Si usa paquetes de terceros que dependen de Microsoft.ApplicationInsights 2.x (por ejemplo, Serilog.Sinks.ApplicationInsights), compruebe que esos paquetes admiten SDK 3.x antes de actualizar. Siga las instrucciones de los mantenedores de paquetes.

Paso 2: Actualizar las versiones del paquete a la versión 3.x

Actualice los paquetes de Application Insights compatibles restantes a la versión 3.x más reciente.

Importante

No combine paquetes de Application Insights 2.x y 3.x en la misma aplicación. Actualice todas las referencias del paquete de Application Insights juntas.

Paso 3: Actualizar el código y la configuración para cambios importantes

Revise la referencia de cambios importantes y quite o reemplace las API y la configuración que ya no son compatibles.

Entre los cambios más comunes se incluyen los siguientes:

  • ** Eliminar las llamadas TrackPageView.
  • Actualice las llamadas Track* para quitar el parámetro de métricas personalizadas.
  • Reemplace la configuración de la clave de instrumentación por una cadena de conexión completa mediante TelemetryConfiguration.ConnectionString.
  • Reemplace las personalizaciones TelemetryModule, TelemetryInitializer y TelemetryProcessor por procesadores OpenTelemetry, bibliotecas de instrumentación y detectores de recursos. La ApplicationInsightsServiceOptions clase incluye EnableQuickPulseMetricStream, EnablePerformanceCounterCollectionModule, EnableDependencyTrackingTelemetryModuley EnableRequestTrackingTelemetryModule. Estas ApplicationInsightsServiceOptions opciones configuran el comportamiento del exportador y no usan TelemetryModule implementaciones.
  • Reemplace el muestreo adaptable (EnableAdaptiveSampling) por TracesPerSecond o SamplingRatio.
  • Destinar .NET Framework 4.6.2 o posterior para aplicaciones ASP.NET que usen Microsoft.ApplicationInsights.Web.

Reemplazar puntos de extensibilidad eliminados

El SDK de .NET de Application Insights 2.x proporciona tipos de extensibilidad específicos de Application Insights, como módulos de telemetría, inicializadores y procesadores. El SDK de .NET de Application Insights 3.x usa la extensibilidad de OpenTelemetry en su lugar.

  • Use opciones de configuración e instrumentación de OpenTelemetry para controlar la recopilación automática.
  • Use procesadores OpenTelemetry para enriquecer o filtrar la telemetría.

SDK 3.x mantiene solo un subconjunto de TelemetryContext propiedades. Puede establecer estas propiedades en elementos de telemetría individuales:

Context Propiedades
User Id, , AuthenticatedUserId, UserAgent
Operation Name
Location Ip
GlobalProperties (diccionario)

Configurar el muestreo

El SDK de .NET de Application Insights 3.x admite dos modos de muestreo para seguimientos (solicitudes y dependencias):

  • Establezca SamplingRatio (0,0 en 1,0) para el muestreo basado en porcentajes.
  • Se establece TracesPerSecond para el muestreo limitado por velocidad (valor predeterminado: Cinco seguimientos por segundo).

SDK 3.x aplica la misma configuración de muestreo a las solicitudes y dependencias. SDK 3.x no admite configuraciones de muestreo independientes para solicitudes y dependencias.

Cuando se incluye una solicitud o dependencia en el muestreo, SDK 3.x aplica la decisión de muestreo del seguimiento principal a los registros relacionados de forma predeterminada. Para deshabilitar ese comportamiento, establezca EnableTraceBasedLogsSampler a false.

Puede establecer SamplingRatio, TracesPerSecondy EnableTraceBasedLogsSampler en TelemetryConfiguration, appsettings.jsono applicationinsights.config.

Solución de problemas de una actualización

Siga estos pasos para validar la telemetría durante una actualización a SDK 3.x:

  • Recopile registros de autodiagnóstico de Application Insights para identificar errores de configuración y errores de exportador.
  • Agregue el exportador de consola de OpenTelemetry para verificar que los seguimientos trazas, métricas y registros se emiten correctamente antes de depender de la ingesta de Azure Monitor.
  • Si ha probado previamente la telemetría simulando ITelemetryChannel, cambie a validación compatible con OpenTelemetry (por ejemplo: exportadores en memoria o un exportador de pruebas adicional en entornos que no son de producción).
  • Confirme que la configuración de muestreo se comporta según lo previsto validando las decisiones de seguimiento de relaciones principal-secundario.
  • Valide los atributos de recursos, como el nombre de servicio, el nombre del rol y el entorno para garantizar la atribución correcta en Application Insights.

Para obtener instrucciones y ejemplos detallados de solución de problemas, use los siguientes recursos: