Instrumentation OpenTelemetry pour Java : un agent qui s'attache à la JVM

Un agent Java qui injecte la télémétrie au niveau du bytecode

Le livrable principal du dépôt est un JAR d'agent Java qui peut être attaché à toute application Java 8+. Une fois attaché, l'agent injecte dynamiquement du bytecode pour capturer la télémétrie d'un certain nombre de bibliothèques et frameworks populaires. Le README indique que le résultat net est la capacité de recueillir des données de télémétrie d'une application Java sans modification de code. L'export est pris en charge dans une variété de formats, et l'agent comme l'exportateur peuvent être configurés par arguments de ligne de commande ou variables d'environnement. Les métadonnées du dépôt décrivent le projet comme de l'auto-instrumentation et des bibliothèques d'instrumentation pour Java. L'attachement de l'agent ne nécessite aucune modification du code applicatif ni recompilation, ce qui est la principale différence avec l'instrumentation manuelle. Le même dépôt publie aussi une instrumentation autonome pour plusieurs bibliothèques, pour les utilisateurs qui préfèrent cela à l'agent ; le README renvoie ces utilisateurs à la colonne d'instrumentation autonome du document sur les bibliothèques prises en charge.

Attacher l'agent et où vont les données par défaut

Le parcours de démarrage du README consiste à télécharger la dernière opentelemetry-javaagent.jar depuis la page des versions GitHub. Le paquet contient l'agent d'instrumentation ainsi que les instrumentations pour toutes les bibliothèques prises en charge et tous les exportateurs de données disponibles. L'agent s'active avec l'option JVM -javaagent ; l'exemple du README est `java -javaagent:path/to/opentelemetry-javaagent.jar -jar myapp.jar`. Par défaut, l'agent utilise l'exportateur OTLP configuré pour envoyer les données à un collecteur OpenTelemetry à http://localhost:4318. Le README ne décrit pas comment déployer ce collecteur ni comment modifier les paramètres de connexion au-delà du point de terminaison par défaut ; il renvoie au dépôt du collecteur et au répertoire source de l'exportateur.

Surface de configuration et sa volatilité

Les paramètres de configuration sont passés comme propriétés système Java (options -D) ou variables d'environnement. L'exemple du README définit `-Dotel.resource.attributes=service.name=your-service-name` et bascule l'exportateur de traces vers Zipkin avec `-Dotel.traces.exporter=zipkin`. L'agent est décrit comme hautement configurable, couvrant le choix de l'exportateur, les réglages de l'exportateur comme la destination des données et les en-têtes de propagation du contexte de trace. Deux pages de documentation sont liées : une pour la configuration de l'agent et une pour la configuration du SDK. Le README avertit que les noms des paramètres de configuration sont très susceptibles de changer avec le temps et demande aux utilisateurs de revenir vérifier lors d'une nouvelle version et de signaler les bogues ou comportements inattendus. Toute liste concrète d'éléments de configuration doit donc être vérifiée contre la documentation de la version courante et ne doit pas être traitée comme une interface stable.

Bibliothèques, frameworks et serveurs d'applications pris en charge

Le README affirme prendre en charge un nombre énorme de bibliothèques et frameworks et une majorité des serveurs d'applications les plus populaires, et décrit cette prise en charge comme fonctionnant immédiatement. Cela signifie que l'agent reconnaît les appels à ces bibliothèques sans configuration supplémentaire une fois attaché. Il renvoie à docs/supported-libraries.md pour la liste complète, et ce document couvre aussi les instrumentations désactivées et la façon de supprimer une instrumentation non souhaitée. Le README lui-même ne nomme aucune bibliothèque, version ou quantité spécifique, donc toute liste concrète doit être vérifiée contre le document lié. Le README ne quantifie pas non plus ce que signifient « énorme » ou « majorité », donc la couverture réelle n'est vérifiable qu'à travers ce document.

Extensions et distributions

Les extensions d'agent ajoutent des fonctionnalités à l'agent sans créer de distribution séparée ni forker le dépôt. Le README donne comme exemples des samplers personnalisés, des exportateurs de spans et de nouvelles valeurs par défaut, le tout intégré à l'agent pour produire un seul fichier JAR. Une page séparée couvre la création d'une distribution d'agent, qui sert de collection d'exemples pour reconditionner l'agent avec des fonctionnalités personnalisées. Le README recommande les extensions pour la plupart des utilisateurs parce qu'elles sont plus simples et ne nécessitent pas de reconstruire à chaque version de l'agent OpenTelemetry Java. Le rôle de la page de distribution est plus étroit : elle montre comment reconditionner l'agent avec des fonctionnalités personnalisées, ce qui est un processus plus lourd que d'écrire une extension.

Instrumentation manuelle et corrélation des journaux

Pour la plupart des utilisateurs, l'instrumentation prête à l'emploi suffit, mais le README décrit des cas où les utilisateurs veulent ajouter des attributs aux spans automatiques ou créer manuellement des spans pour leur propre code, et renvoie à la documentation d'instrumentation manuelle. Séparément, l'auto-instrumentation MDC du logger injecte des informations de trace comme les ID de trace et les ID de span dans les journaux d'application personnalisés ; les détails sont dans un document dédié. Ces deux chemins s'appuient sur l'agent plutôt que de le remplacer, donc un utilisateur qui dépend de l'instrumentation automatique peut toujours ajouter des spans et attributs personnalisés si nécessaire.

Débogage, contribution et état du projet

Le débogage s'active avec `-Dotel.javaagent.debug=true` ; le README note que ces journaux sont extrêmement verbeux et que le débogage affecte négativement les performances de l'application. Les consignes de contribution sont dans CONTRIBUTING.md. Deux mainteneurs sont listés (Lauri Tulmin chez Splunk, Trask Stalnaker chez Microsoft), plus huit approbateurs de Grafana Labs, Splunk, Elastic, Alibaba et Sublime Security, et quatre membres émérites avec leurs anciens rôles. Les métadonnées du dépôt listent 2 601 étoiles, 1 125 forks et 277 problèmes ouverts ; le dépôt n'est pas archivé, sa branche par défaut est main et sa page d'accueil est opentelemetry.io. La licence est Apache-2.0. La licence accorde une licence de droit d'auteur perpétuelle, mondiale, non exclusive, gratuite, sans redevance et irrévocable, ainsi qu'une licence de brevet similaire qui se termine dans des conditions énoncées, et inclut des conditions de redistribution. Le texte de la licence ne dit rien sur le support, la garantie ou la posture de sécurité, et le README ne les couvre pas non plus.

Conclusion éditoriale

Le README présente l'agent comme le chemin par défaut et l'instrumentation autonome comme l'alternative, et renvoie à des documents séparés pour la liste complète des bibliothèques prises en charge, les options de configuration et les mécanismes de suppression. Les détails dont dépendent la plupart des questions de déploiement se trouvent dans ces documents liés, pas dans le README lui-même.

Sources officielles

1. Official documentation
2. Official README
3. Project repository
4. Release notes