Migrer agent Elastic APM OpenTelemetry : passer à EDOT Java

Migrer agent Elastic APM OpenTelemetry avec EDOT Java : mapping des réglages, un seul endpoint, javaagent et ce qui n’a pas d’équivalent.
Migrer agent Elastic APM OpenTelemetry : passer à EDOT Java

Votre parc Java envoie ses traces à APM Server avec l’agent Elastic APM, et Elastic recommande désormais de passer à OpenTelemetry. Pour migrer agent Elastic APM OpenTelemetry côté Java, la documentation propose EDOT Java, la distribution OpenTelemetry d’Elastic. Le risque pour une équipe SRE : perdre des spans personnalisés ou des métriques sans s’en apercevoir, et casser les alertes qui en dépendent.

Ce tutoriel suit la page de migration d’Elastic : mapper les réglages, ne garder qu’un endpoint, remplacer l’argument -javaagent, puis vérifier. Il liste aussi ce qui n’a pas d’équivalent. L’objectif : migrer un service à la fois, sans trou de visibilité, et garder un code d’instrumentation compatible avec n’importe quel backend OTLP.

Périmètre : Elastic Stack et Serverless Observability, d’après la documentation Elastic consultée le 30 octobre 2026. La page de migration ne signale pas de statut « preview » ; elle indique Java 8 ou plus. Aucune version précise d’EDOT Java n’y figure : vérifiez la version publiée sur Maven Central avant de déployer. Ce guide ne concerne pas Dynatrace Managed ni SaaS, mais le résultat est du OpenTelemetry standard (voir la fin de l’article).

Migrer agent Elastic APM OpenTelemetry : ce qui change

L’agent Elastic APM est un agent propriétaire. EDOT Java est une distribution de l’agent Java OpenTelemetry : instrumentation automatique, sans modifier le code, avec les bibliothèques couvertes par le projet OpenTelemetry amont. Les données sont envoyées en OTLP et conservent les conventions sémantiques OpenTelemetry. Pour le pont de métriques OpenTelemetry, Elastic précise que les noms d’attributs gardent leurs points au lieu de devenir des champs labels.*.

Conséquence pratique : les noms de métriques JVM changent, certains réglages disparaissent, et l’API de l’agent Elastic (spans manuels) doit être remplacée si vous l’utilisiez. Pour comprendre où envoyer ces données, lisez d’abord OTLP APM Server ou EDOT Collector.

Prérequis

  • Java 8 ou plus (page de migration EDOT Java).
  • Un point d’entrée OTLP : un EDOT Collector, un Elastic Managed OTLP endpoint (Serverless) ou un endpoint de votre déploiement. Pour un Collector local, la page de configuration cite http://localhost:4318 sans authentification.
  • Une clé d’API ou un secret token Elastic, si le point d’entrée exige une authentification. Ne les écrivez jamais dans un dépôt.
  • L’agent co.elastic.otel:elastic-otel-javaagent, téléchargé depuis Maven Central.
  • La liste des réglages ELASTIC_APM_* de vos services actuels : c’est votre point de départ.

Étape 1 : migrer l’instrumentation manuelle

Étape facultative selon Elastic, mais critique : si le code appelle l’API de l’agent Elastic APM pour créer des transactions ou des spans, il faut passer aux annotations et à l’API OpenTelemetry. Sinon, ces spans personnalisés ne sont plus générés. Recensez-les avant la bascule : un span manquant peut faire disparaître le détail d’un SLI de latence.

Étape 2 : traduire les réglages

La page de migration donne un tableau de correspondance. En voici l’essentiel :

Extrait de la correspondance des réglages de l'agent Elastic APM Java vers les variables OpenTelemetry d'EDOT Java
Agent Elastic APM EDOT Java / OpenTelemetry
server_url OTEL_EXPORTER_OTLP_ENDPOINT
secret_token OTEL_EXPORTER_OTLP_HEADERS avec Authorization=Bearer …
api_key OTEL_EXPORTER_OTLP_HEADERS avec Authorization=ApiKey …
service_name OTEL_SERVICE_NAME ou attribut service.name
service_version attribut de ressource service.version
environment attribut de ressource deployment.environment.name
global_labels paires clé=valeur dans OTEL_RESOURCE_ATTRIBUTES
disable_instrumentations OTEL_INSTRUMENTATION_<nom>_ENABLED=false
log_sending actif par défaut ; otel.logs.exporter à none pour couper
verify_server_cert ELASTIC_OTEL_VERIFY_SERVER_CERT (défaut true)

D’autres réglages existent (trace_methods, capture_headers, capture_jmx_metrics, service_node_name…) avec des syntaxes différentes : consultez la page complète. Deux nuances à retenir : trace_methods devient OTEL_INSTRUMENTATION_METHODS_INCLUDE avec une syntaxe différente et moins de jokers, et la capture d’en-têtes est statique au démarrage, alors qu’elle était dynamique.

Étape 3 : un seul endpoint

Le réglage server_urls (plusieurs serveurs) n’a pas d’équivalent : EDOT Java accepte un seul endpoint. Pour du multi-destination, placez un Collector devant vos services et gérez l’export à cet endroit. Voyez le Collector OpenTelemetry sur Kubernetes et Elastic Agent comme collecteur OpenTelemetry.

La configuration minimale de la documentation tient en trois variables :

Variables d'environnement minimales d'EDOT Java et lancement de l'application avec l'argument javaagent, d'après la documentation 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"

Selon la page de configuration, OTEL_SERVICE_NAME est requis pour l’intégration à l’interface et la corrélation, et OTEL_EXPORTER_OTLP_ENDPOINT est obligatoire sauf si un Collector répond sur http://localhost:4317, l’adresse par défaut.

Étape 4 : remplacer le javaagent

Remplacez l’argument -javaagent de l’agent Elastic APM par celui d’EDOT, puis redémarrez :

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

Si vous ne pouvez pas toucher à la ligne de commande, JAVA_TOOL_OPTIONS fonctionne, mais Elastic avertit qu’elle s’applique à tous les processus JVM du même environnement, outils de build compris. Préférez le script de démarrage du serveur : CATALINA_OPTS dans bin/setenv.sh pour Tomcat, par exemple. Sur Kubernetes, la documentation renvoie vers l’opérateur OpenTelemetry. Retirez aussi les variables ELASTIC_APM_* devenues inutiles.

Ce qui n’a pas d’équivalent

La page de migration liste les pertes. Lisez-la avec vos tableaux de bord ouverts.

Liste des fonctions de l'agent Elastic APM Java sans équivalent dans EDOT Java, d'après la page de migration
  • server_urls : un seul endpoint.
  • application_packages : pas de filtrage de piles par paquet.
  • Attache à distance : remplacée par l’auto-attache à l’exécution, avec des limites.
  • Compression de spans et métriques de breakdown : non disponibles.
  • Instrumentation du client LDAP : non disponible.
  • Santé et surcharge de l’agent, métriques cgroup : non prises en charge ; utilisez hostmetricsreceiver ou kubeletstatsreceiver dans le Collector.

Côté métriques, les noms JVM suivent les conventions OpenTelemetry : par exemple jvm.gc.time devient jvm.gc.duration, et la mémoire passe par jvm.memory.used avec un attribut jvm.memory.type. jvm.gc.count n’a pas d’équivalent direct. Réécrivez les requêtes et alertes qui s’appuient sur les anciens noms. Instrumentation Micrometer : désactivée par défaut, à activer avec otel.instrumentation.micrometer.enabled=true.

Comment vérifier que ça fonctionne

  1. Passez le niveau de log de l’agent à DEBUG avec ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL : la documentation le recommande pour diagnostiquer et il affiche les spans en JSON.
  2. Vérifiez dans l’interface Observability d’Elastic que le service apparaît sous le bon nom, avec la version et l’environnement attendus.
  3. Comparez le débit et la latence p95 avant et après sur un service migré en premier.
  4. Contrôlez que les spans manuels migrés existent et que les alertes ont été réécrites avec les nouveaux noms de métriques.

Bonnes pratiques

  • Migrez un service pilote, puis par vagues : le MTTR d’un incident est plus court quand une seule variable change à la fois.
  • Conservez l’ancien agent en parallèle sur un environnement de test pour comparer les résultats.
  • Gardez les secrets hors du dépôt, dans votre gestionnaire de secrets.
  • Ne désactivez ELASTIC_OTEL_VERIFY_SERVER_CERT que pour un essai : Elastic recommande d’ajouter l’autorité au trust store de la JVM.
  • Standardisez sur OTLP : pour la logique de standard commun, voir OpenTelemetry et Prometheus.

Et avec Dynatrace ?

EDOT Java reste un agent OpenTelemetry : il émet de l’OTLP standard. Dynatrace accepte l’OTLP, mais cet article n’a pas testé ce chemin et la documentation Elastic n’en parle pas : ne le présumez pas. Pour comparer les approches d’éditeurs, lisez Dynatrace et Datadog.

Questions fréquentes

Faut-il migrer le code d’instrumentation manuelle ?

Elastic classe cette étape comme facultative, mais précise que les transactions et spans créés avec l’API de l’agent Elastic ne sont plus générés tant qu’ils ne sont pas migrés vers l’API OpenTelemetry.

Puis-je garder plusieurs serveurs avec server_urls ?

Non, la page de migration indique qu’il n’y a pas d’équivalent : un seul endpoint. Utilisez un Collector pour répartir ou dupliquer les données.

Mes dashboards sur les métriques JVM continueront-ils à fonctionner ?

Pas tels quels. Plusieurs métriques changent de nom, et certaines n’ont pas d’équivalent direct. Réécrivez-les d’après la liste de la page de migration.

Conclusion

Migrer l’agent Elastic APM vers OpenTelemetry avec EDOT Java se résume à quatre gestes : inventorier le code d’instrumentation, traduire les réglages, viser un seul endpoint, changer le -javaagent. Les vraies pertes se trouvent dans la liste « sans équivalent » : lisez-la avant le premier déploiement. Sources : migration EDOT Java, installation, configuration.

Ce site est un blog indépendant, non affilié à Dynatrace LLC ni à Elastic N.V. Les informations d’Elastic sont celles de sa documentation publique, consultée le 30 octobre 2026 ; vérifiez-les pour votre version.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

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

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

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

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

Related Posts