L’agent Java d’OpenTelemetry 3.0 renomme vos métriques et sort en GA ce mois-ci

6 octobre 2026. L’équipe de l’agent Java d’OpenTelemetry publie la version 2.32.0. Octobre 2026. La version 3.0 est annoncée pour ce même mois. Deux ans. C’est le temps qu’ont duré les conventions sémantiques actuelles, et elles vont changer d’un coup. Pourquoi c’est important : l’agent Java est l’instrumentation zéro-code la plus déployée du monde Java, et la 3.0 renomme des attributs, change des unités et restructure des traces — autrement dit, elle peut casser vos tableaux de bord, vos alertes et vos pipelines sans toucher une ligne de votre application.

Ce que change la 3.0, en un paragraphe

OpenTelemetry a organisé sa 3.0 autour d’un principe simple : les conventions sémantiques deviennent enfin stables, et l’agent applique les nouvelles valeurs par défaut. Concrètement, trois domaines bougent. Les conventions base de données et code passent en défaut stable. Les conventions messagerie adoptent une version plus récente, encore expérimentale. Et certains réglages de capture ainsi que des instrumentations par défaut changent de valeur. L’article de blog qui présente la release candidate est sans ambiguïté : « 3.0 changes telemetry, configuration, and instrumentation defaults ».

Le point délicat, pour une équipe en production, c’est que ces changements ne sont pas un simple renommage cosmétique. Ils touchent des noms, des valeurs, des types et des unités. Un renommage de clé ne suffit pas : il faut aussi vérifier que la valeur n’a pas changé, et qu’un seuil exprimé en millisecondes n’a pas besoin d’être converti en secondes.

Des noms qui changent, des unités qui changent

L’exemple le plus parlant vient de JDBC. Une connexion PostgreSQL à la base orders, configurée sur le schéma public, produit aujourd’hui un span avec db.system: "postgresql", db.name: "orders" et db.statement: "SELECT * FROM orders". Avec la 3.0, ces attributs deviennent respectivement db.system.name: "postgresql", db.namespace: "orders|public" et db.query.text: "SELECT * FROM orders". Notez le piège : db.namespace fusionne la base et le schéma en orders|public, alors que db.name ne portait que orders. Vérifier les valeurs, pas seulement les clés.

La liste des changements est longue, et quelques-uns sont faciles à rater :

• db.client.connections.max devient db.client.connection.limit — remplacer « connections » par « connection » ne suffit pas ;
• db.system: "mssql" devient db.system.name: "microsoft.sql_server" ;
• les métriques de durée des pools de connexions passent de la milliseconde à la seconde ;
• code.namespace et code.function fusionnent en code.function.name ;
• enduser.id devient user.name, et enduser.role — une chaîne séparée par des virgules — devient user.roles, un tableau de chaînes ; enduser.scope, lui, disparaît sans remplaçant.

Chacun de ces points correspond à une requête dans un tableau de bord ou à une condition d’alerte quelque part. C’est précisément pour cela qu’OpenTelemetry fournit une passerelle : l’émission duale.

L’émission duale : tester avant de casser

La version 2.32.0 introduit un mécanisme de comparaison explicite. En laissant le drapeau global désactivé et en suffixant /dup, l’agent émet l’ancien et le nouveau schéma côte à côte, pour les domaines qui le supportent :

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=false \
OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup \
OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup

Vous capturez d’abord une télémétrie de référence, puis vous activez le drapeau global pour tester l’ensemble des conventions et des valeurs par défaut d’un coup :

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true

Deux limites à connaître. La première : l’émission duale ne préserve pas tous les anciens instruments ni toutes les formes de traces. Les métriques de pool de connexions basculent sur les nouveaux noms et unités même avec /dup, et un span n’a qu’un seul nom et un seul kind. La seconde : en mode preview, le support de l’exporteur Zipkin est supprimé — il faut basculer vers OTLP.

La messagerie change de structure de trace

Le domaine le plus délicat est la messagerie, qui passe des conventions sémantiques v1.24 à la v1.43. Pour Kafka, les noms de spans changent : orders publish devient send orders, orders receive devient poll orders, orders process devient process orders. L’opération passe en tête et reflète l’API du client. L’ancien attribut messaging.operation se scinde en messaging.operation.name et messaging.operation.type : pour un poll Kafka, le nom est poll et le type receive.

Ce qui peut vraiment surprendre, ce sont les relations de parenté. Dans l’ancien schéma, un span process pouvait être enfant du span d’envoi du producteur. Dans le nouveau, quand le traitement s’exécute dans un span applicatif actif (par exemple celui créé par @WithSpan), ce span devient le parent du span process, et le span process ne fait plus que lier le span du producteur. Résultat : des traces qui se regroupaient se séparent, et vos agrégations par service changent de forme. Le span poll devient un span CLIENT indépendant, au lieu d’un CONSUMER.

Les métriques suivent : messaging.publish.duration et messaging.receive.duration convergent vers messaging.client.operation.duration, et messaging.receive.messages devient messaging.client.consumed.messages. Là encore, vérifiez les valeurs autant que les noms.

Des réglages de capture et des instrumentations qui bougent aussi

La 3.0 ne se limite pas aux renommages : elle peut ajouter ou retirer de la télémétrie. Si votre application attache déjà des champs structurés à ses logs via des paires clé-valeur SLF4J, ces champs peuvent apparaître dans les logs exportés sans activer la capture séparément, une fois le drapeau global activé. La capture MDC reste, elle, configurée à part et optionnelle.

À l’inverse, certaines instrumentations passent désactivées par défaut : Hibernate, Hystrix et Twilio. Si vous en dépendez, il faut les réactiver explicitement, sinon les spans correspondants disparaissent de vos traces sans prévenir. C’est le genre de régression silencieuse que l’émission duale ne montrera pas forcément, puisqu’elle ne compare que ce qui est émis — pas ce qui cesse de l’être.

Pour la migration elle-même, OpenTelemetry met à disposition une boîte à outils. La configuration déclarative (encore expérimentale) permet de piloter l’agent par un fichier YAML via -Dotel.config.file=/path/to/otel-config.yaml, avec un convertisseur de configuration existante. Le guide de migration des conventions sémantiques base de données documente les correspondances attribut par attribut. Et l’Ecosystem Explorer expose des métadonnées d’instrumentation versionnées que l’on peut fournir à un agent IA pour qu’il propose des mises à jour de tableaux de bord et d’alertes — en lui demandant, comme le suggère l’article de blog, de signaler chaque correspondance non prouvée par un VERIFY plutôt que de supposer.

Verdict

La 3.0 de l’agent Java d’OpenTelemetry est un vrai breaking change déguisé en mise à jour mineure, et sa date — ce mois-ci — ne vous laisse pas beaucoup de marge. Si vous exécutez l’agent Java en production, n’attendez pas la GA : déployez la 2.32.0 dès maintenant sur un environnement de test, capturez une référence, activez /dup, puis passez vos tableaux de bord et vos alertes au crible des nouveaux noms, valeurs et unités. Si vous exportez encore vers Zipkin, planifiez la bascule vers OTLP avant tout le reste — le support disparaît en mode preview. Et si vous maintenez une distribution ou une extension de l’agent, testez dès à présent : l’instrumentation par invokedynamic devient la valeur par défaut, ce qui change la façon dont vos classes d’aide sont chargées. Les équipes qui feront la bascule maintenant le feront à leur rythme ; celles qui attendront la GA la feront dans l’urgence, le jour où leurs alertes cesseront de matcher.

Références

• OpenTelemetry — The OpenTelemetry Java agent 3.0 is almost here (6 octobre 2026)
• GitHub — opentelemetry-java-instrumentation v2.32.0
• OpenTelemetry — Database semantic convention stability migration guide
• OpenTelemetry — Java agent declarative configuration