Lab 2 — Instrumentation zero-code d'un micro-service Java

Rien. Le service répond, il écrit en base… mais il est invisible : aucune trace, car aucune instrumentation n’est active. C’est l’état de la plupart des applications avant OpenTelemetry.

• OTEL_SERVICE_NAME=review-service — le nom sous lequel le service apparaîtra dans Jaeger/Grafana (convention sémantique service.name) ;
• OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 — où envoyer la télémétrie : le collecteur de la démo, en OTLP ;
• OTEL_EXPORTER_OTLP_PROTOCOL=grpc — variante gRPC du protocole OTLP (port 4317 ; le port 4318 sert la variante HTTP) ;
• OTEL_RESOURCE_ATTRIBUTES=service.namespace=otel-demo — attributs de ressource additionnels attachés à toute la télémétrie. service.namespace regroupe logiquement les services : couplé à service.name, il range review-service avec les autres services de la démo dans Jaeger/Grafana.

⚠️ Pourquoi le fixer à la main, ce n’est pas déductible ? Attention à ne pas confondre service.namespace (OTel) et k8s.namespace.name (Kubernetes) :

• l’agent/SDK ne voit que le processus, pas Kubernetes — il ignore le namespace K8s du pod, donc il ne peut rien déduire seul ;
• ce qui peut être injecté automatiquement, c’est k8s.namespace.name (via le k8sattributes processor du collecteur, l’OTel Operator, ou la Downward API fieldRef: metadata.namespace). Mais c’est un attribut d’infrastructure ;
• service.namespace est un attribut logique / métier : un choix de regroupement, pas un fait de l’infra. Ici il vaut otel-demo par coïncidence (même nom que le namespace K8s), mais rien ne les oblige à coïncider.

D’où l’approche explicite d’une ligne dans le manifest — sans dépendre du collecteur ni de l’Operator.

JAVA_TOOL_OPTIONS est lue par la JVM au démarrage : c’est le moyen standard d’injecter -javaagent sans modifier ni le code ni la commande de lancement.

Typiquement deux niveaux :

• un span serveur HTTP GET /api/reviews (instrumentation de Tomcat/Spring MVC) avec les attributs http.request.method, http.route, http.response.status_code… ;
• un ou plusieurs spans SQL enfants (instrumentation JDBC) avec db.system=postgresql et la requête SELECT exécutée.

L’agent instrumente par manipulation de bytecode les bibliothèques qu’il connaît (Tomcat, Spring, JDBC, Kafka, HTTP clients… plus de 100 frameworks).

Comparez avec le service ad de la démo : lui aussi est un service Java instrumenté par l’agent — vous y verrez la même structure de spans.

La chaîne d’activation, du plus haut au plus bas niveau :

./scripts/deploy.sh -p starter
 └─ docker build --build-arg MAVEN_PROFILE=starter ...
     └─ Dockerfile : ARG MAVEN_PROFILE → RUN mvn -P ${MAVEN_PROFILE} -DskipTests package
         └─ pom.xml : le profil <id>starter</id> ajoute la dépendance
                      opentelemetry-spring-boot-starter (+ le BOM qui fixe sa version)

• pom.xml — le profil default (activeByDefault) n’ajoute rien : l’appli n’a que l’API OTel, qui reste no-op sans SDK. Le profil starter ajoute la dépendance opentelemetry-spring-boot-starter et importe le opentelemetry-instrumentation-bom (qui aligne les versions OTel). C’est cette dépendance qui embarque le SDK + les auto-configurations Spring.
• Dockerfile — ARG MAVEN_PROFILE=default déclare la variable de build, consommée à l’étape de compilation : RUN mvn -P ${MAVEN_PROFILE} -DskipTests package. Changer le profil change donc le .jar produit → rebuild obligatoire (l’agent, lui, ne touchait pas au build).
• deploy.sh — -p starter positionne PROFILE=starter, passé à Docker via docker build --build-arg MAVEN_PROFILE=starter. Cette même valeur sert de tag d’image (starter-<user>-<horodatage>), pour que Kind recharge bien la nouvelle image.

À retenir : l’agent est toujours présent dans l’image mais inactif sans JAVA_TOOL_OPTIONS ; le Starter, lui, est actif dès qu’il est compilé. D’où la règle : jamais les deux ensemble.

Les deux produisent le span serveur HTTP et les spans JDBC — mais par des mécanismes opposés, et c’est ce qui explique tout le reste :

• Agent = un programme externe attaché à la JVM (-javaagent) qui réécrit le bytecode des bibliothèques connues au chargement, sans que l’appli ni son build ne le sachent.
• Starter = une dépendance compilée dans l’appli, qui se branche sur les points d’extension de Spring (auto-configuration) — pas de manipulation de bytecode.

Sur ce lab, le cas courant (Spring MVC + JDBC) est couvert des deux côtés, d’où des traces quasi identiques. La différence n’apparaît qu’aux extrémités (libs exotiques, drivers hors Spring) et sur les propriétés opérationnelles :

GraalVM native = compilation ahead-of-time de l’appli en exécutable natif (démarrage en millisecondes, faible mémoire). Comme le binaire est figé au build, aucune réécriture de bytecode n’est possible au runtime → l’agent ne marche pas, mais le Starter (déjà compilé dedans) oui.

ℹ️ GraalVM n’est pas utilisé dans ce lab : review-service tourne sur une JVM classique (Temurin 21, un simple .jar). C’est un argument en faveur du Starter pour la prod native, pas quelque chose à activer ici.

Quand préférer le starter ? Images natives (GraalVM), maîtrise fine des dépendances, ou politique interdisant les agents JVM. Quand préférer l’agent ? Instrumenter un parc existant sans toucher aux builds.