Migrar el agente Elastic APM a OpenTelemetry: pasar a EDOT Java

Migrar el agente Elastic APM a OpenTelemetry con EDOT Java: equivalencias de ajustes, un solo endpoint, javaagent y lo que no tiene equivalente.
Migrer agent Elastic APM OpenTelemetry : passer à EDOT Java

Tu parque Java envía sus trazas a APM Server con el agente Elastic APM, y Elastic recomienda ahora pasar a OpenTelemetry. Para migrar el agente Elastic APM a OpenTelemetry en Java, la documentación propone EDOT Java, la distribución de OpenTelemetry de Elastic. El riesgo para un equipo SRE: perder spans personalizados o métricas sin darse cuenta, y romper las alertas que dependen de ellos.

Este tutorial sigue la página de migración de Elastic: equiparar los ajustes, conservar un solo endpoint, sustituir el argumento -javaagent y después verificar. También enumera lo que no tiene equivalente. El objetivo: migrar un servicio cada vez, sin huecos de visibilidad, y conservar un código de instrumentación compatible con cualquier backend OTLP.

Alcance: Elastic Stack y Serverless Observability, según la documentación de Elastic consultada el 30 de octubre de 2026. La página de migración no indica un estado «preview»; indica Java 8 o superior. No figura ninguna versión concreta de EDOT Java: comprueba la versión publicada en Maven Central antes de desplegar. Esta guía no trata de Dynatrace Managed ni de SaaS, pero el resultado es OpenTelemetry estándar (consulta el final del artículo).

Migrar el agente Elastic APM a OpenTelemetry: qué cambia

El agente Elastic APM es un agente propietario. EDOT Java es una distribución del agente Java de OpenTelemetry: instrumentación automática, sin modificar el código, con las bibliotecas cubiertas por el proyecto OpenTelemetry original. Los datos se envían en OTLP y conservan las convenciones semánticas de OpenTelemetry. Para el puente de métricas de OpenTelemetry, Elastic precisa que los nombres de atributos conservan sus puntos en lugar de convertirse en campos labels.*.

Consecuencia práctica: los nombres de las métricas de la JVM cambian, algunos ajustes desaparecen y la API del agente de Elastic (spans manuales) debe sustituirse si la usabas. Para entender adónde enviar estos datos, lee primero OTLP APM Server o EDOT Collector.

Requisitos previos

  • Java 8 o superior (página de migración de EDOT Java).
  • Un punto de entrada OTLP: un EDOT Collector, un Elastic Managed OTLP endpoint (Serverless) o un endpoint de tu despliegue. Para un Collector local, la página de configuración cita http://localhost:4318 sin autenticación.
  • Una clave de API o un secret token de Elastic, si el punto de entrada exige autenticación. No los escribas nunca en un repositorio.
  • El agente co.elastic.otel:elastic-otel-javaagent, descargado desde Maven Central.
  • La lista de ajustes ELASTIC_APM_* de tus servicios actuales: es tu punto de partida.

Paso 1: migrar la instrumentación manual

Paso opcional según Elastic, pero crítico: si el código llama a la API del agente Elastic APM para crear transacciones o spans, hay que pasar a las anotaciones y a la API de OpenTelemetry. Si no, esos spans personalizados dejan de generarse. Inventaríalos antes del cambio: un span ausente puede hacer desaparecer el detalle de un SLI de latencia.

Paso 2: traducir los ajustes

La página de migración ofrece una tabla de equivalencias. Esto es lo esencial:

Extracto de la equivalencia de ajustes del agente Elastic APM Java con las variables de OpenTelemetry de EDOT Java
Agente Elastic APM EDOT Java / OpenTelemetry
server_url OTEL_EXPORTER_OTLP_ENDPOINT
secret_token OTEL_EXPORTER_OTLP_HEADERS con Authorization=Bearer …
api_key OTEL_EXPORTER_OTLP_HEADERS con Authorization=ApiKey …
service_name OTEL_SERVICE_NAME o atributo service.name
service_version atributo de recurso service.version
environment atributo de recurso deployment.environment.name
global_labels pares clave=valor en OTEL_RESOURCE_ATTRIBUTES
disable_instrumentations OTEL_INSTRUMENTATION_<nombre>_ENABLED=false
log_sending activo por defecto; otel.logs.exporter en none para cortarlo
verify_server_cert ELASTIC_OTEL_VERIFY_SERVER_CERT (por defecto true)

Existen otros ajustes (trace_methods, capture_headers, capture_jmx_metrics, service_node_name…) con sintaxis distintas: consulta la página completa. Dos matices que conviene recordar: trace_methods pasa a ser OTEL_INSTRUMENTATION_METHODS_INCLUDE con una sintaxis diferente y menos comodines, y la captura de cabeceras es estática al arrancar, mientras que antes era dinámica.

Paso 3: un solo endpoint

El ajuste server_urls (varios servidores) no tiene equivalente: EDOT Java acepta un solo endpoint. Para varios destinos, coloca un Collector delante de tus servicios y gestiona la exportación ahí. Consulta el Collector de OpenTelemetry en Kubernetes y Elastic Agent como colector de OpenTelemetry.

La configuración mínima de la documentación cabe en tres variables:

Variables de entorno mínimas de EDOT Java y arranque de la aplicación con el argumento javaagent, según la documentación de Elastic
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.ingest.us-west1.gcp.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"
export OTEL_SERVICE_NAME="my-awesome-service"

Según la página de configuración, OTEL_SERVICE_NAME es necesario para la integración con la interfaz y la correlación, y OTEL_EXPORTER_OTLP_ENDPOINT es obligatorio salvo que un Collector responda en http://localhost:4317, la dirección por defecto.

Paso 4: sustituir el javaagent

Sustituye el argumento -javaagent del agente Elastic APM por el de EDOT y reinicia:

java \
-javaagent:/path/to/agent.jar \
-jar myapp.jar

Si no puedes tocar la línea de comandos, JAVA_TOOL_OPTIONS funciona, pero Elastic advierte de que se aplica a todos los procesos JVM del mismo entorno, incluidas las herramientas de compilación. Es preferible el script de arranque del servidor: CATALINA_OPTS en bin/setenv.sh para Tomcat, por ejemplo. En Kubernetes, la documentación remite al operador de OpenTelemetry. Elimina también las variables ELASTIC_APM_* que ya no hagan falta.

Lo que no tiene equivalente

La página de migración enumera las pérdidas. Léela con tus dashboards abiertos.

Lista de funciones del agente Elastic APM Java sin equivalente en EDOT Java, según la página de migración
  • server_urls: un solo endpoint.
  • application_packages: sin filtrado de pilas por paquete.
  • Conexión remota: sustituida por la autoconexión en tiempo de ejecución, con limitaciones.
  • Compresión de spans y métricas de breakdown: no disponibles.
  • Instrumentación del cliente LDAP: no disponible.
  • Salud y sobrecarga del agente, métricas de cgroup: no admitidas; usa hostmetricsreceiver o kubeletstatsreceiver en el Collector.

En cuanto a las métricas, los nombres de la JVM siguen las convenciones de OpenTelemetry: por ejemplo, jvm.gc.time pasa a ser jvm.gc.duration, y la memoria se expone mediante jvm.memory.used con un atributo jvm.memory.type. jvm.gc.count no tiene equivalente directo. Reescribe las consultas y alertas que dependan de los nombres antiguos. Instrumentación de Micrometer: desactivada por defecto, se activa con otel.instrumentation.micrometer.enabled=true.

Cómo comprobar que funciona

  1. Cambia el nivel de log del agente a DEBUG con ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL: la documentación lo recomienda para diagnosticar y muestra los spans en JSON.
  2. Comprueba en la interfaz Observability de Elastic que el servicio aparece con el nombre correcto, con la versión y el entorno esperados.
  3. Compara el rendimiento y la latencia p95 antes y después en un servicio migrado el primero.
  4. Verifica que existen los spans manuales migrados y que las alertas se han reescrito con los nuevos nombres de métricas.

Buenas prácticas

  • Migra un servicio piloto y después por oleadas: el MTTR de un incidente es menor cuando cambia una sola variable cada vez.
  • Conserva el agente antiguo en paralelo en un entorno de pruebas para comparar los resultados.
  • Mantén los secretos fuera del repositorio, en tu gestor de secretos.
  • Desactiva ELASTIC_OTEL_VERIFY_SERVER_CERT solo para una prueba: Elastic recomienda añadir la autoridad al trust store de la JVM.
  • Estandariza sobre OTLP: para la lógica de un estándar común, consulta OpenTelemetry y Prometheus.

¿Y con Dynatrace?

EDOT Java sigue siendo un agente de OpenTelemetry: emite OTLP estándar. Dynatrace acepta OTLP, pero este artículo no ha probado esa vía y la documentación de Elastic no la menciona: no lo des por hecho. Para comparar los enfoques de los proveedores, lee Dynatrace y Datadog.

Preguntas frecuentes

¿Hay que migrar el código de instrumentación manual?

Elastic clasifica este paso como opcional, pero precisa que las transacciones y los spans creados con la API del agente de Elastic dejan de generarse mientras no se migren a la API de OpenTelemetry.

¿Puedo mantener varios servidores con server_urls?

No, la página de migración indica que no hay equivalente: un solo endpoint. Usa un Collector para repartir o duplicar los datos.

¿Seguirán funcionando mis dashboards sobre métricas de la JVM?

No tal cual. Varias métricas cambian de nombre y algunas no tienen equivalente directo. Reescríbelos según la lista de la página de migración.

Conclusión

Migrar el agente Elastic APM a OpenTelemetry con EDOT Java se resume en cuatro gestos: inventariar el código de instrumentación, traducir los ajustes, apuntar a un solo endpoint y cambiar el -javaagent. Las pérdidas reales están en la lista «sin equivalente»: léela antes del primer despliegue. Fuentes: migración de EDOT Java, instalación, configuración.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a Elastic N.V. Dynatrace es una marca de Dynatrace LLC. La información de Elastic procede de su documentación pública, consultada el 30 de octubre de 2026; compruébala para tu versión.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
OTLP vers Datadog : Agent, DDOT ou intake direct, comment choisir

OTLP a Datadog: Agent, DDOT o ingesta directa, cómo elegir

Next Post
Logsdb Elasticsearch : réduire le stockage des logs sans réindexer

Logsdb Elasticsearch: reducir el almacenamiento de logs sin reindexar

Related Posts