Agent OpenTelemetry Java : instrumenter une application et l’envoyer à Dynatrace

Agent OpenTelemetry Java : téléchargez-le, configurez l’export OTLP vers Dynatrace, déployez sur VM ou Kubernetes et vérifiez traces, métriques et logs.
Agent OpenTelemetry Java : instrumenter une application et l'envoyer à Dynatrace

Votre équipe veut une instrumentation standard, portable et sans modifier le code d’une application Spring Boot. Elle n’a pas OneAgent sur ces conteneurs, ou elle a choisi OpenTelemetry comme norme de plateforme. L’agent OpenTelemetry Java répond à ce besoin : un fichier JAR ajouté au démarrage de la JVM, et les traces, métriques et logs partent en OTLP vers Dynatrace.

Objectif de ce tutoriel : télécharger l’agent, le configurer par variables d’environnement pour envoyer les trois signaux à Dynatrace, le déployer sur une VM puis sur Kubernetes, et vérifier l’arrivée des données. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed ; seule l’URL de l’endpoint change.

Si le même processus est déjà surveillé par OneAgent, lisez d’abord OneAgent et OpenTelemetry : éviter les doublons. Deux auto-instrumentations dans une même JVM produisent des spans en double.

Prérequis

  • Java 8 ou plus récent (vérifiez la matrice de compatibilité de la version d’agent choisie).
  • Un token API Dynatrace avec les scopes openTelemetryTrace.ingest, metrics.ingest et logs.ingest.
  • L’URL de l’endpoint OTLP :
    • SaaS : https://<env-id>.live.dynatrace.com/api/v2/otlp ;
    • Managed : https://<votre-domaine>/e/<env-id>/api/v2/otlp ;
    • via un ActiveGate : https://<activegate>:9999/e/<env-id>/api/v2/otlp.
  • Un accès sortant HTTPS depuis l’application, ou un Collector intermédiaire.

Étapes pour configurer l’agent OpenTelemetry Java

Étape 1 — Télécharger l’agent

mkdir -p /opt/otel
curl -fsSL -o /opt/otel/opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

En production, remplacez latest par une version figée (par exemple download/v2.x.y/) pour que chaque build soit reproductible, et testez les montées de version comme une dépendance.

Étape 2 — Configurer l’export vers Dynatrace

Créez un fichier d’environnement /etc/checkout/otel.env :

OTEL_SERVICE_NAME=checkout
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=production
OTEL_EXPORTER_OTLP_ENDPOINT=https://abc12345.live.dynatrace.com/api/v2/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Api-Token%20dt0c01.XXXX.YYYY
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
OTEL_PROPAGATORS=tracecontext,baggage

Lignes critiques :

  • OTEL_EXPORTER_OTLP_ENDPOINT : l’URL de base, sans /v1/traces. L’agent ajoute lui-même /v1/traces, /v1/metrics et /v1/logs.
  • OTEL_EXPORTER_OTLP_HEADERS : l’espace entre Api-Token et le token est encodé %20, comme le prévoit la spécification des variables OpenTelemetry.
  • http/protobuf : l’API OTLP de Dynatrace attend HTTP avec protobuf. Pour du gRPC, passez par un Collector.
  • delta : Dynatrace attend des métriques en temporalité delta. Sans cette ligne, des compteurs peuvent être rejetés : tout est expliqué dans la temporalité des métriques OTLP.

Ne versionnez jamais ce fichier avec le token : injectez-le depuis votre gestionnaire de secrets.

Étape 3 — Démarrer la JVM avec l’agent (VM ou bare metal)

Unité systemd minimale :

[Unit]
Description=Checkout service
After=network-online.target

[Service]
EnvironmentFile=/etc/checkout/otel.env
ExecStart=/usr/bin/java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar /opt/checkout/checkout.jar
Restart=on-failure

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl restart checkout

L’option -javaagent doit précéder -jar, sinon elle est passée comme argument à l’application et ignorée.

Étape 4 — Variante Kubernetes

Copiez l’agent dans un volume partagé avec un init container, puis chargez-le avec JAVA_TOOL_OPTIONS :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
spec:
  replicas: 2
  selector:
    matchLabels: { app: checkout }
  template:
    metadata:
      labels: { app: checkout }
    spec:
      volumes:
        - name: otel
          emptyDir: {}
      initContainers:
        - name: otel-agent
          image: curlimages/curl:8.10.1
          command: ["curl", "-fsSL", "-o", "/otel/opentelemetry-javaagent.jar",
                    "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.10.0/opentelemetry-javaagent.jar"]
          volumeMounts: [{ name: otel, mountPath: /otel }]
      containers:
        - name: app
          image: registry.example.com/checkout:1.4.2
          envFrom:
            - secretRef: { name: checkout-otel }
          env:
            - name: JAVA_TOOL_OPTIONS
              value: "-javaagent:/otel/opentelemetry-javaagent.jar"
          volumeMounts: [{ name: otel, mountPath: /otel }]

Le secret checkout-otel contient les variables de l’étape 2. La version de l’agent et l’image curl sont des exemples : prenez une version publiée et validée chez vous. Avec l’opérateur OpenTelemetry, la ressource Instrumentation automatise cette injection. Pour un export centralisé, pointez plutôt l’endpoint vers un Collector OpenTelemetry qui détient le token.

Comment vérifier que ça fonctionne

  1. Logs de démarrage : la JVM affiche une ligne du type opentelemetry-javaagent - version: 2.x.y. Si elle manque, l’agent n’est pas chargé.
  2. Erreurs d’export : cherchez Failed to export dans les logs. Un code 401 ou 403 signale un token ou un scope incorrect ; un 404 une URL d’endpoint fausse.
  3. Mode debug ponctuel : OTEL_JAVAAGENT_DEBUG=true affiche les spans dans la console. À retirer ensuite, c’est très verbeux.
  4. Dans Dynatrace SaaS, exécutez dans un Notebook :
fetch spans, from: now() - 15m
| filter service.name == "checkout"
| summarize requetes = count(), by: { span.name }
| sort requetes desc
| limit 20

Vous devez voir les routes HTTP de l’application. Pour les logs : fetch logs | filter service.name == "checkout" | limit 20. En Managed, le service apparaît dans la liste des services et les traces dans la vue des traces distribuées ; les métriques sont visibles dans l’explorateur de données. Les écrans exacts dépendent de votre version : consultez la documentation OpenTelemetry de Dynatrace.

Dépannage

  • Aucune donnée, aucune erreur : la variable JAVA_TOOL_OPTIONS n’est pas lue par l’image (certaines images de base la redéfinissent dans leur script de démarrage). Vérifiez avec kubectl exec que la JVM affiche « Picked up JAVA_TOOL_OPTIONS ».
  • Traces présentes, métriques absentes : la temporalité est restée cumulative, ou le token n’a pas le scope metrics.ingest.
  • Logs dupliqués : l’application écrit déjà sur la sortie standard, collectée par un autre agent. Choisissez un seul chemin pour les logs.
  • Démarrage plus lent : l’agent ajoute un coût au démarrage de la JVM. Ajustez les sondes de disponibilité (readiness) si elles échouent après l’ajout de l’agent.
  • Erreurs TLS : derrière un proxy d’entreprise, la JVM doit faire confiance au certificat du proxy (truststore Java), sinon l’export échoue en silence côté application.

Bonnes pratiques

  • Un service.name stable par service : il porte les SLO et les alertes, voir les alertes burn rate SLO.
  • Renseignez service.version à chaque déploiement : comparer deux versions devient immédiat.
  • Désactivez les instrumentations inutiles plutôt que de filtrer après coup (OTEL_INSTRUMENTATION_<NOM>_ENABLED=false).
  • Échantillonnez avec prudence : un échantillonnage côté client trop agressif fausse les SLI calculés sur les spans.
  • Jamais d’agent OpenTelemetry dans une JVM déjà instrumentée par OneAgent.

Questions fréquentes

Faut-il modifier le code de l’application ?

Non pour l’instrumentation de base : l’agent instrumente automatiquement les frameworks courants (HTTP, JDBC, messagerie). Ajoutez l’API OpenTelemetry seulement pour des spans ou attributs métier.

Envoi direct ou via un Collector ?

L’envoi direct convient pour un test ou quelques services. Au-delà, un Collector centralise le token, le filtrage et les retries.

Les logs applicatifs sont-ils capturés ?

L’agent capte les appenders des bibliothèques de logs courantes (Logback, Log4j) quand l’export de logs est actif, avec l’identifiant de trace associé. Vérifiez votre bibliothèque dans la liste des instrumentations supportées.

Conclusion

Avec un JAR et une dizaine de variables, l’agent OpenTelemetry Java envoie traces, métriques et logs à Dynatrace sans toucher au code. Fixez la version, imposez la temporalité delta, gardez un seul propriétaire d’instrumentation par processus et vérifiez dans Grail. Vos SLO reposent alors sur des données standard et portables.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les fonctionnalités évoluent vite : vérifiez leur disponibilité dans votre environnement et dans la documentation officielle.

Total
0
Shares
Laisser un commentaire

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

Previous Post
OneAgent OpenTelemetry doublons : éviter les spans en double et le contexte cassé

OneAgent OpenTelemetry doublons : éviter les spans en double et le contexte cassé

Next Post
Temporalité métriques OTLP vers Dynatrace : delta ou cumulative, l'erreur qui fait disparaître vos compteurs

Temporalité métriques OTLP vers Dynatrace : delta ou cumulative, l’erreur qui fait disparaître vos compteurs

Related Posts