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.ingestetlogs.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.
- SaaS :
- 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/metricset/v1/logs.OTEL_EXPORTER_OTLP_HEADERS: l’espace entreApi-Tokenet 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
- 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é. - Erreurs d’export : cherchez
Failed to exportdans les logs. Un code 401 ou 403 signale un token ou un scope incorrect ; un 404 une URL d’endpoint fausse. - Mode debug ponctuel :
OTEL_JAVAAGENT_DEBUG=trueaffiche les spans dans la console. À retirer ensuite, c’est très verbeux. - 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_OPTIONSn’est pas lue par l’image (certaines images de base la redéfinissent dans leur script de démarrage). Vérifiez aveckubectl execque 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.namestable 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.