¿Qué hace observability-edot-dotnet-migrate?
Migra una aplicación .NET del agente clásico Elastic APM .NET al SDK EDOT .NET. Úsalo al cambiar de paquetes Elastic.Apm.* a Elastic.OpenTelemetry.
Descripción
Esta habilidad te guía a través del proceso de migración de una aplicación .NET que actualmente utiliza el agente clásico Elastic APM .NET (paquetes Elastic.Apm.*) al nuevo SDK EDOT .NET (Elastic.OpenTelemetry). La migración permite a tu aplicación aprovechar las capacidades modernas de OpenTelemetry mientras mantienes la integración con Elastic Observability.
Plataformas compatibles
- .NET 6+
- ASP.NET Core
- .NET Framework 4.6.1+
- Aplicaciones de consola, servicios y APIs
Requisitos previos
- Tener instalado el SDK de .NET correspondiente
- Acceso a NuGet para instalar paquetes
- Conocimiento básico de la estructura del proyecto .NET
Pasos de migración
1. Eliminar dependencias del agente clásico
Elimina todas las referencias a paquetes Elastic.Apm.* de tu archivo de proyecto (.csproj):
<!-- Eliminar estas líneas -->
<PackageReference Include="Elastic.Apm" Version="..." />
<PackageReference Include="Elastic.Apm.AspNetCore" Version="..." />
<PackageReference Include="Elastic.Apm.EntityFrameworkCore" Version="..." />
2. Agregar el paquete EDOT .NET SDK
Agrega el paquete Elastic.OpenTelemetry a tu proyecto:
dotnet add package Elastic.OpenTelemetry
3. Actualizar la configuración
Reemplaza la configuración del agente clásico en appsettings.json o variables de entorno con la configuración de OpenTelemetry:
{
"Elastic" : {
"OpenTelemetry": {
"ServiceName": "mi-aplicacion",
"Endpoint": "http://localhost:8200",
"ApiKey": "mi-api-key"
}
}
}
Si usas variables de entorno, cambia:
ELASTIC_APM_SERVER_URL→OTEL_EXPORTER_OTLP_ENDPOINTELASTIC_APM_API_KEY→OTEL_EXPORTER_OTLP_HEADERS(formatoAuthorization=Bearer ...)ELASTIC_APM_SERVICE_NAME→OTEL_SERVICE_NAME
4. Modificar el código de inicio
En Program.cs o Startup.cs, reemplaza la inicialización del agente:
// Antes (agente clásico)
using Elastic.Apm;
Agent.Setup(new AgentComponents());
// Después (EDOT SDK)
using OpenTelemetry;
using OpenTelemetry.Trace;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddElasticOpenTelemetry());
5. Verificar la migración
- Ejecuta la aplicación y verifica que los datos se envíen correctamente al servidor Elastic
- Revisa los logs para confirmar que no hay errores de inicialización
- Prueba funcionalidades clave como solicitudes HTTP, consultas a bases de datos, etc.
Notas importantes
- La migración es irreversible: una vez que cambies al SDK EDOT, no podrás volver al agente clásico sin deshacer los cambios manualmente
- Algunas opciones de configuración del agente clásico no tienen equivalente directo en OpenTelemetry; consulta la documentación oficial para más detalles
- Si usas funcionalidades avanzadas como filtros de transacciones o hooks personalizados, migra esos componentes a la API de procesadores OpenTelemetry
Solución de problemas
- Error "No se pudo cargar Elastic.Apm": Asegúrate de haber eliminado todas las referencias a paquetes antiguos
- No se envían datos: Verifica la configuración del endpoint y las credenciales en
appsettings.jsono variables de entorno - Problemas de rendimiento: Revisa que los instrumentos agregados no sean excesivos; usa solo los necesarios para tu aplicación