Une équipe ajoute l’agent Java OpenTelemetry à un service déjà surveillé par OneAgent. Résultat : chaque requête apparaît deux fois, une trace s’arrête net au milieu de la chaîne d’appels, et personne ne sait plus quel temps de réponse croire. Ce cas de OneAgent OpenTelemetry doublons (spans en double, contexte cassé) est fréquent, et il se règle par une décision d’architecture simple : un seul propriétaire de l’instrumentation par processus.
Objectif de ce tutoriel : identifier la cause des spans en double ou du contexte cassé, choisir le bon mode de cohabitation, puis vérifier que chaque requête produit une seule trace complète. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed ; les écrans d’analyse de traces diffèrent, la logique est la même.
Pour la vue d’ensemble d’une chaîne instrumentée de bout en bout, lisez aussi OpenTelemetry de bout en bout avec Dynatrace.
OneAgent OpenTelemetry doublons : les trois causes
Trois causes reviennent presque toujours :
- Deux auto-instrumentations dans le même processus. OneAgent instrumente la JVM (ou le runtime .NET, Node.js…) et l’agent OpenTelemetry instrumente les mêmes bibliothèques HTTP et JDBC. Chaque appel produit deux spans, envoyés par deux chemins différents.
- Les spans OpenTelemetry captés deux fois. OneAgent sait capter les spans créés avec l’API OpenTelemetry dans un processus qu’il surveille. Si l’application exporte en plus ces spans en OTLP vers Dynatrace, ils arrivent une fois par OneAgent et une fois par OTLP.
- La propagation de contexte rompue. Le service A envoie un en-tête
traceparent(W3C Trace Context) que le service B ignore, ou un proxy supprime les en-têtes. B démarre une nouvelle trace : la chaîne est coupée en deux.
Prérequis
- Un environnement Dynatrace SaaS ou Managed avec OneAgent en mode full-stack sur les hôtes ou via Dynatrace Operator.
- Un accès en lecture aux réglages de l’environnement (OneAgent features, surveillance des processus).
- Pour les services OpenTelemetry : un token API avec le scope
openTelemetryTrace.ingestet un endpoint OTLP, direct ou via le Collector OpenTelemetry. - Un accès shell ou
kubectlaux processus concernés.
Étapes pour supprimer les doublons OneAgent OpenTelemetry
Étape 1 — Inventorier qui instrumente quoi
Sur un hôte, listez les agents chargés dans les JVM :
# Agents Java chargés au démarrage
ps -eo pid,args | grep -E 'javaagent|JAVA_TOOL_OPTIONS' | grep -v grep
# Variables OpenTelemetry d'un processus (remplacer 1234 par le PID)
tr '\0' '\n' < /proc/1234/environ | grep -E '^OTEL_|JAVA_TOOL_OPTIONS'
Sur Kubernetes, cherchez les deux injections possibles dans les pods :
kubectl get pod checkout-7d9f -n shop -o yaml \
| grep -E 'instrumentation.opentelemetry.io|oneagent.dynatrace.com|JAVA_TOOL_OPTIONS'
Si vous voyez à la fois une injection OneAgent et l’annotation instrumentation.opentelemetry.io/inject-java: "true" de l’opérateur OpenTelemetry, le processus a deux propriétaires.
Étape 2 — Choisir un propriétaire par processus
| Mode | Qui instrumente | Quand le choisir |
|---|---|---|
| A. OneAgent propriétaire | OneAgent ; l’API OpenTelemetry sert seulement aux spans métier manuels | Services déjà surveillés par OneAgent, équipe qui veut PurePath et profilage |
| B. OpenTelemetry propriétaire | SDK ou agent OpenTelemetry ; OneAgent reste sur l’hôte sans instrumenter ce processus | Équipe qui standardise sur OpenTelemetry, portabilité multi-outils |
| C. Mixte par service | A pour certains services, B pour d’autres | Migration progressive ; exige une propagation W3C de bout en bout |
Ce qu’il ne faut jamais faire : deux auto-instrumentations actives dans la même JVM.
Étape 3a — Mode A : OneAgent propriétaire
Retirez l’agent OpenTelemetry du démarrage et coupez l’export OTLP des traces. Gardez l’API OpenTelemetry dans le code si vous créez des spans métier :
# Retirer -javaagent:opentelemetry-javaagent.jar de JAVA_TOOL_OPTIONS
# Si un SDK OpenTelemetry reste initialisé dans le code :
export OTEL_TRACES_EXPORTER=none
Vérifiez ensuite dans les réglages OneAgent features que l’OpenTelemetry Span Sensor du code module OneAgent est activé pour votre technologie (disponible pour Java, Go, Node.js, PHP et .NET). Le nom exact de l’option varie selon le langage et la version ; cherchez « OpenTelemetry » dans la liste et confirmez dans la documentation OpenTelemetry de Dynatrace. Un redémarrage du processus est en général nécessaire.
Étape 3b — Mode B : OpenTelemetry propriétaire
Empêchez OneAgent d’instrumenter le processus, sans le retirer de l’hôte. Sur Kubernetes avec Dynatrace Operator, désactivez l’injection au niveau du pod :
apiVersion: apps/v1
kind: Deployment
metadata:
name: checkout
spec:
template:
metadata:
annotations:
oneagent.dynatrace.com/inject: "false"
instrumentation.opentelemetry.io/inject-java: "true"
Sur un hôte classique, créez une règle de surveillance des processus qui exclut ce processus de la surveillance approfondie (Settings → Processes and containers, selon votre version). La métrique hôte reste collectée par OneAgent. Le détail de l’Operator est dans Dynatrace Operator sur Kubernetes.
Étape 4 — Réparer la propagation de contexte
Pour les chaînes mixtes, les deux mondes doivent parler W3C Trace Context. Côté OpenTelemetry, fixez les propagateurs explicitement :
export OTEL_PROPAGATORS=tracecontext,baggage
Côté OneAgent, vérifiez dans les réglages de traçage distribué que l’envoi des en-têtes W3C Trace Context est activé (c’est le cas par défaut sur les versions récentes, à confirmer sur la vôtre). Contrôlez aussi les proxys, API gateways et service meshes : ils doivent transmettre traceparent et tracestate sans les réécrire.
Comment vérifier que ça fonctionne
Envoyez une requête de test avec un traceparent connu :
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
https://checkout.example.internal/api/cart
En SaaS, cherchez cette trace dans Grail :
fetch spans, from: now() - 15m
| filter trace.id == "4bf92f3577b34da6a3ce929d0e0e4736"
| summarize spans = count(), by: { dt.entity.service, span.name }
| sort spans desc
Attendu : chaque couple service/opération apparaît une fois par appel réel. Deux services différents pour le même processus (par exemple un nommé par OneAgent et un nommé par service.name) signalent une double instrumentation. Les noms de champs peuvent varier : vérifiez-les avec fetch spans | limit 1. En Managed, ouvrez la vue des traces distribuées, filtrez sur le service et contrôlez que la trace contient tous les services attendus, sans nœud dupliqué.
Bonnes pratiques
- Écrivez la règle dans vos standards de plateforme : un processus, un propriétaire d’instrumentation.
- Utilisez le même
service.nameque le nom de service vu par OneAgent pendant une migration, pour garder la continuité des SLO. - Après chaque changement, comparez le nombre de requêtes avant/après : un volume divisé par deux signale la fin d’un doublon, pas une baisse de trafic.
- Les doublons gonflent aussi la consommation de licence et faussent les SLI : surveillez-les comme un risque de fiabilité, voir les alertes burn rate SLO.
Questions fréquentes
Puis-je garder OneAgent et l’API OpenTelemetry dans le même service ?
Oui, c’est le mode A. L’API OpenTelemetry sert à créer des spans métier ; OneAgent les capte. Le doublon apparaît seulement si un exporteur OTLP envoie aussi ces spans.
Les métriques OpenTelemetry sont-elles aussi dupliquées ?
Elles ne sont pas captées par le même mécanisme que les spans. Le risque principal est d’exporter deux fois la même métrique par deux chemins (SDK et Collector, par exemple). Contrôlez vos pipelines d’export.
Le mode mixte dégrade-t-il l’analyse ?
Il fonctionne si la propagation W3C est complète. Certaines analyses propres à OneAgent, comme le profilage de code, restent absentes des services instrumentés uniquement avec OpenTelemetry.
Conclusion
Les doublons OneAgent OpenTelemetry ne sont pas un bug à contourner, mais le symptôme de deux instrumentations concurrentes. Inventoriez, choisissez un propriétaire par processus, imposez W3C Trace Context, puis vérifiez trace par trace. Vos SLI redeviennent fiables, et l’analyse d’incident aussi.
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.