Un service répond en 4 secondes au lieu de 300 ms, le taux d’erreur grimpe et trois équipes se renvoient la balle. Les métriques disent qu’il y a un problème, pas où il se trouve. Les Distributed traces Dynatrace Managed répondent à cette question : elles suivent une requête de bout en bout, service par service, jusqu’à la méthode qui consomme le temps.
Ce guide pratique montre comment se servir de la vue Distributed traces (Distributed Traces Classic) au quotidien : filtrer des milliers de requêtes pour n’en garder que trois, lire un waterfall, descendre au code, rejoindre les logs, et connaître les limites de rétention propres à Managed. Deux sections pratiques détaillent le diagnostic d’une requête lente en cinq étapes et les pièges à connaître : échantillonnage, traces incomplètes, request attributes manquants. Chaque scénario (lenteur, erreurs, appel tiers, base de données, régression après déploiement) est relié à un gain de MTTR.
Périmètre : le contenu vaut pour Dynatrace Managed. Dynatrace SaaS propose la même vue classique, mais aussi une application Distributed Tracing fondée sur Grail et DQL, qui n’existe pas en Managed.
PurePath, trace, span : le vocabulaire utile
La documentation Managed définit une distributed trace comme une suite de spans, identifiée par un trace ID unique, qui suit le chemin d’une requête à travers les services. Un span représente une opération ; le span sans parent est le trace root span. PurePath désigne les traces capturées par OneAgent ; les traces instrumentées par d’autres bibliothèques (OpenTelemetry par exemple) apparaissent comme Ingested traces.
Le contexte passe d’un service à l’autre par en-têtes : x-dynatrace (format propriétaire), traceparent et tracestate (W3C, partagés par OneAgent et OpenTelemetry), et dtdTraceTagInfo pour certains systèmes de messagerie. Si un proxy ou une passerelle supprime ces en-têtes, la trace se coupe en deux : c’est la première cause de « trace incomplète ». Pour les files de messages, voir la propagation de contexte avec Kafka.
Prérequis
- Un environnement Dynatrace Managed avec OneAgent en full-stack sur les processus à tracer (le code-level exige OneAgent).
- Des management zones en place : la liste des traces est limitée à la zone sélectionnée (voir management zones et tagging).
- Pour l’API des request attributes : un token avec
ReadConfig(lecture) etCaptureRequestData(création). - Pour un environnement mixte OneAgent et OpenTelemetry : W3C Trace Context activé dans Settings > Preferences > OneAgent features (Send W3C Trace Context HTTP headers et Send W3C Trace Context gRPC headers).
Utiliser les Distributed traces Dynatrace Managed pas à pas
- Ouvrir la vue. Menu Distributed traces, ou depuis un service : Services > More (…) > Distributed traces, qui préfiltre sur ce service.
- Régler la période et la management zone. Le graphique Overview affiche le nombre de requêtes et le temps de réponse. Au-delà de 10 jours, activez Show data retention pour voir quelles données sont encore disponibles.
- Choisir la source. PurePaths pour OneAgent, Ingested traces pour les traces OpenTelemetry ou d’autres bibliothèques.
- Filtrer avec Filter requests (détail plus bas), puis trier la liste par Start time, Name, Response time, Processing time, HTTP method ou Response code.
- Déplier une ligne pour un aperçu (topologie, attributs, HTTP, timings), puis sélectionner le nom de la trace.
- Lire la trace : Execution breakdown pour la répartition du temps, waterfall pour l’ordre des services, puis un segment pour ouvrir les onglets de détail.
Les filtres et les combinaisons utiles
La liste affiche au plus les 3 000 traces les plus récentes de la période et de la management zone. Sur un service chargé, une fenêtre trop large noie la requête intéressante : filtrez avant de lire.
| Filtre | Usage |
|---|---|
| Période | Encadrer l’incident ou le déploiement au plus près |
| Management zone | Ne voir que l’application ou l’équipe concernée |
| Méthode d’ingestion | PurePaths (OneAgent) ou Ingested traces |
| Service name | Partir du service qui souffre |
| Response time (≥, ≤) | Isoler les requêtes lentes au-dessus d’un seuil |
| Request attributes | Cibler un client, un pays, un panier, une version |
| Recherche (trace ID) | Retrouver la trace citée dans un log ou un ticket |
Combinaisons qui servent souvent :
- Service + Response time ≥ seuil SLO : uniquement les requêtes qui consomment l’error budget de latence. Dans l’exemple de la documentation, ce filtre ramène 249 000 requêtes à 3.
- Service + tri par Response code : les 5xx remontent en tête, prêts pour l’onglet Errors.
- Request attribute + Response time : « ce client premium est-il plus lent que les autres ? ».
- Filtre du service flow : dans View service flow, sélectionnez un service appelé puis Apply filter, ajoutez un second service, et ouvrez Distributed traces sur l’appelant. Vous obtenez seulement les requêtes qui passent par cette chaîne d’appels.
Analyser une trace : waterfall, timings, code-level, logs
Le waterfall montre quels services la trace traverse et dans quel ordre. La position et la couleur des barres indiquent la séquence et le temps de réponse de chaque requête : deux barres qui se chevauchent sont exécutées en parallèle. Sélectionnez un segment pour ouvrir les onglets :
- Summary : métadonnées, en-têtes, paramètres, proxy. Cinq astérisques (
*****) masquent une donnée confidentielle, démasquable avec les bonnes permissions ; trois ou moins servent à l’agrégation et ne se démasquent pas. - Timings : View method hotspots détaille CPU, wait, sync, lock et temps d’exécution.
- Code level : l’arbre des méthodes exécutées et leurs durées, dans l’ordre réel. Le volume de détail varie selon l’importance et le coût : les parties lentes d’une requête en contiennent généralement plus. Les durées des appels distants sont vues côté client.
- Logs : les enregistrements de log dans le contexte de la transaction, si l’enrichissement des logs est actif. Strict span filter restreint au nœud sélectionné ; View logs for this trace montre tout.
- Errors, Threads, Integrations selon la technologie.
Le chemin inverse marche aussi : dans un log enrichi, la propriété trace_id est cliquable et ouvre la trace. Pour l’équivalent OpenTelemetry, voir relier logs et traces par trace ID.
Diagnostiquer une requête lente en 5 étapes
Le cas le plus fréquent reste la requête lente signalée par un utilisateur ou par un SLO de latence. Voici l’enchaînement qui fait gagner le plus de temps.
- Filtrer. Ouvrez Distributed traces depuis le service d’entrée (Services > More (…) > Distributed traces), encadrez la période de l’incident, puis Filter requests > Response time, opérateur ≥, et votre seuil (80 ms dans l’exemple de la documentation). Si le trafic passe par plusieurs chaînes d’appels, posez d’abord le filtre dans le service flow (Apply filter sur le service appelé) : la liste n’affiche plus que les requêtes qui suivent cette chaîne.
- Trier par durée. Triez la liste Most recent traces par Response time décroissant. Comparez avec Processing time : si le premier dépasse nettement le second, le temps part en attente d’un appel distant, pas dans le code du service. Si la ligne porte la mention [n] more like this, OneAgent échantillonne : la trace affichée représente des requêtes semblables non capturées.
- Ouvrir le PurePath. Sélectionnez le nom de la trace. L’en-tête donne Response time, Processing time, l’Execution breakdown (part de CPU, de Network I/O, d’« Other ») et les request attributes capturés. Une part élevée de Network I/O oriente vers les appels sortants ; un CPU élevé, vers le code du service.
- Lire la cascade et les appels base de données. Dans le waterfall, chaque barre est un appel de service placé sur l’axe de temps réel : les barres bleu foncé sont du temps serveur, les barres claires du temps client, et les traits jaunes des appels base de données. Cherchez la barre la plus longue qui n’a pas d’enfant long : c’est là que le temps est consommé. Un même appel base de données répété des dizaines de fois en séquence signe un N+1 ; une longue barre client sans équivalent serveur signe un appel externe ou un service sans OneAgent.
- Remonter au code. Sélectionnez le segment coupable, onglet Code level : l’arbre des méthodes réellement exécutées, avec leurs durées, dans l’ordre d’exécution. Pour une vue statistique (CPU, wait, sync, lock, exécution), passez par Timings > View method hotspots. Si le code-level est vide, vérifiez l’âge de la trace (10 jours) et que le processus est bien monitoré par OneAgent en full-stack.

Pour savoir d’où venaient ces requêtes lentes (quelle application, quel appelant, quelle action utilisateur), repartez du service concerné avec Analyze backtrace : le service backtrace remonte la chaîne d’appels dans l’autre sens, et son option Filter service backtrace ne garde que les transactions qui contiennent la chaîne sélectionnée.
Cinq scénarios concrets
Lenteur ressentie par les utilisateurs
Filtrez le service d’entrée sur Response time ≥ votre objectif, ouvrez la trace la plus lente, puis Execution breakdown. Si le temps est dans le service lui-même, passez par Timings > View method hotspots ; s’il est dans un appel aval, descendez dans le waterfall.
Hausse du taux d’erreur
Depuis le service, onglet Failure rate, puis Analyze backtrace pour voir d’où viennent les requêtes en échec, et More (…) > Distributed traces. L’onglet Errors donne l’exception et les paramètres qui y ont mené : souvent, toutes les traces partagent la même cause.
Appel à un service tiers
Un appel externe apparaît comme une barre longue dont le code-level n’est pas disponible côté appelé. Comparez le temps client avec le temps total : si l’essentiel est là, le problème est chez le fournisseur, et vos timeouts et retries méritent une revue.
Base de données
Les appels base de données apparaissent dans le waterfall de la trace. Cherchez un même appel répété des dizaines de fois dans une seule trace : c’est le motif N+1 classique.
Régression après un déploiement
Comparez deux fenêtres de même durée, avant et après la mise en production, sur le même service et le même seuil de latence. Un request attribute qui capture la version (en-tête ou paramètre) permet ensuite de filtrer directement les traces de la nouvelle version. Gardez en tête que le code-level non agrégé disparaît après 10 jours : analysez vite.
Request attributes : enrichir les traces par l’API
Les request attributes sont des paires clé/valeur attachées à une requête. Ils servent à filtrer, nommer les requêtes, détecter des erreurs métier et créer des calculated metrics. Créez-les dans Settings > Server-side service monitoring > Request attributes ou par l’API Configuration, ce qui permet de les versionner. Le modèle ci-dessous provient de la documentation Managed :

# lister les request attributes (scope ReadConfig)
curl -s -H "Authorization: Api-Token $DT_TOKEN" \
"https://{votre-domaine}/e/{id-environnement}/api/config/v1/service/requestAttributes"
# créer un request attribute (scope CaptureRequestData)
curl -s -X POST -H "Authorization: Api-Token $DT_TOKEN" \
-H "Content-Type: application/json" -d @request-attribute.json \
"https://{votre-domaine}/e/{id-environnement}/api/config/v1/service/requestAttributes"
Ne fournissez pas d’id dans le corps : il est attribué automatiquement, et la réponse 201 le renvoie. La source accepte notamment REQUEST_HEADER, QUERY_PARAMETER, METHOD_PARAM ou SPAN_ATTRIBUTE (avec spanAttributeKey) pour les traces OpenTelemetry. Cochez confidential pour toute donnée personnelle.
Rétention et limites propres à Managed

- Distributed traces : rétention configurable, 365 jours maximum. Elles vivent dans le transaction store (
DATASTORE_PATH/server/tenantData), non répliqué entre les nœuds du cluster : perdre un nœud, c’est perdre ses traces. Détails dans rétention et stockage des données. - Code-level insights : 10 jours en détail, puis données agrégées.
- Requêtes et request attributes : configurable, 365 jours maximum.
- Request attributes : 100 par requête, 10 valeurs par attribut et par requête, 1 000 attributs capturés par trace au plus ; au-delà, plus rien n’est capturé.
- Export CSV de la liste : 50 traces en « données affichées », les 3 000 plus récentes en « toutes les données ».
Pièges : échantillonnage, traces incomplètes, request attributes manquants
L’échantillonnage (Adaptive Traffic Management)
OneAgent ne capture pas toutes les requêtes. En Managed, chaque processus peut démarrer au plus 1 000 nouvelles distributed traces par minute par défaut. Au-delà, l’Adaptive Traffic Management garde la plupart des requêtes rares et une part réduite des requêtes très fréquentes (facteur 1/2 dans l’exemple de la documentation) ; la liste signale les requêtes non capturées par [n] more like this. Une requête lente mais rare a donc toutes les chances d’être capturée ; une requête lente parmi des milliers d’appels identiques peut manquer. Le quota se règle dans Settings > Server-side service monitoring > Deep monitoring > Adaptive capture control (global ou par process group), dans la limite fixée par la Cluster Management Console (quota d’environnement de 1 000 par défaut, jusqu’à 100 000). Les règles Trace sampling for HTTP requests (OneAgent 1.281+) et Trace sampling for RPC requests (OneAgent 1.307+) permettent de prioriser certaines URL ou de désactiver le tracing d’un bruit connu (health checks, images). Enfin, un cluster saturé déclenche l’adaptive load reduction : il ignore au hasard de nouvelles traces et affiche l’alerte Server [n] activated adaptive load reduction ; au-delà de 15 minutes, la fidélité des données en souffre et il faut ajouter un nœud ou réduire le trafic.
![Extrait de la page Adaptive Traffic Management de la documentation Managed : quota de 1 000 nouvelles traces par minute et par processus, exemple de facteurs de capture par URI, mentions [amount] more like this et adaptive load reduction](https://span.observer/wp-content/uploads/2026/10/157-adaptive-traffic-management-4.png)
Les traces incomplètes
Trois causes couvrent presque tous les cas. Un appelant non monitoré : la trace commence au premier process group entièrement monitoré, et Show full trace n’affiche que ce qui existe. Des en-têtes supprimés : un proxy, un WAF ou une passerelle d’API qui retire x-dynatrace, traceparent ou tracestate produit deux traces au lieu d’une ; la documentation demande aussi de laisser passer X-dynaTrace-RequestState, utilisé par les modules Apache, NGINX et IIS. Un environnement mixte : sans Send W3C Trace Context HTTP headers, OneAgent et OpenTelemetry ne partagent pas le trace ID, et les traces OpenTelemetry n’apparaissent que sous Ingested traces, coupées de leur amont. Si vos spans OpenTelemetry n’arrivent pas du tout, suivez la checklist des traces OpenTelemetry absentes.
Les request attributes manquants
Un request attribute absent de l’onglet Summary a presque toujours une cause de configuration. La règle est restreinte à un process group, un host group, une technologie ou un tag qui n’est pas celui du service observé. La source est mauvaise : un en-tête se capture avec REQUEST_HEADER et parameterName, un paramètre d’URL avec QUERY_PARAMETER, un attribut de span OpenTelemetry avec SPAN_ATTRIBUTE et spanAttributeKey. Le côté de capture est mauvais : pour un en-tête, capturingAndStorageLocation doit valoir client ou serveur, jamais CAPTURE_AND_STORE_ON_BOTH. Les limites sont atteintes : 100 attributs par requête, 10 valeurs par attribut, 1 000 attributs par trace, au-delà plus rien n’est capturé. Ou l’attribut existe mais ses valeurs s’affichent en ***** : il est marqué confidentiel et votre compte n’a pas le droit de voir les données masquées. Enfin, OneAgent capture les attributs au moment de la requête : les traces antérieures à la règle ne le porteront jamais, inutile de chercher une version dans les traces d’hier.
Bonnes pratiques
- Filtrez toujours par service et seuil de latence avant d’ouvrir une trace.
- Copiez le trace ID dans le ticket d’incident : la trace reste retrouvable par recherche.
- Créez les request attributes (version, client, tenant) avant l’incident, pas pendant.
- Vérifiez que proxies et load balancers laissent passer
x-dynatrace,traceparentettracestate. - Analysez le code-level dans les 10 jours ; au-delà, exportez ce dont vous avez besoin pour le post-mortem.
Comment vérifier que ça fonctionne
Ouvrez Distributed traces, filtrez sur un service avec PurePaths : des traces doivent apparaître avec plusieurs services dans le waterfall. Si une trace s’arrête net à un proxy, vérifiez la propagation des en-têtes. Après création d’un request attribute, le GET de l’API doit le lister, et l’attribut doit figurer dans l’onglet Summary des nouvelles traces. Pour aller plus loin dans l’exploration, voir aussi le module sur l’exploration des données Managed et la Multidimensional analysis.
Questions fréquentes
Que signifie [declared unavailable by agent] dans une trace ?
C’est une valeur de remplacement : OneAgent n’a pas pu capturer la métadonnée, par manque de visibilité ou parce que la technologie n’est pas prise en charge.
Pourquoi ma trace commence-t-elle au milieu de la chaîne ?
Une trace démarre toujours au premier process group entièrement monitoré. Un appelant sans OneAgent, ou des en-têtes supprimés en route, coupent l’amont. Show full trace affiche la trace complète quand elle existe.
Les traces OpenTelemetry sont-elles visibles dans Managed ?
Oui, dans la même vue avec le filtre Ingested traces. En environnement mixte, activez W3C Trace Context et évitez les doublons de spans (voir OneAgent et OpenTelemetry sans doublons).
Conclusion
Les Distributed traces Dynatrace Managed transforment « le service est lent » en « cette méthode, sur ce service, pour ces requêtes ». Filtrez d’abord, lisez le waterfall ensuite, descendez au code et aux logs en dernier, et tenez compte des 10 jours de code-level et du transaction store non répliqué. Référence officielle : Get started with Distributed Traces (Managed) et Data retention periods et Adaptive Traffic Management.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace et PurePath sont des marques de leur propriétaire. Les exemples sont fournis à titre indicatif : vérifiez-les dans la documentation officielle de votre version.