DQL Smartscape désigne les commandes qui interrogent la topologie stockée dans Grail : smartscapeNodes pour les entités, smartscapeEdges pour les relations et traverse pour passer d’un nœud à ses voisins. Pendant un incident, elles répondent en une requête à des questions qui demandaient plusieurs écrans : sur quels hôtes tourne ce processus, quels services appartiennent à ce namespace, quels volumes sont attachés à ces instances ?
Ce guide présente le modèle (nœuds, arêtes, durée de vie), la syntaxe exacte des trois commandes et des fonctions d’enrichissement, puis des requêtes d’exploitation. Toutes les syntaxes citées viennent des pages « DQL Smartscape commands » et « Smartscape on Grail » de la documentation officielle, consultées en octobre 2026.
Smartscape on Grail est une fonctionnalité de Dynatrace SaaS. Dynatrace Managed n’a ni Grail ni DQL ; la topologie s’y consulte dans Smartscape classique et via le sélecteur d’entités de l’API. Si DQL est nouveau pour vous, commencez par les commandes DQL commentées.
Le modèle DQL Smartscape : nœuds, arêtes, durée de vie
- Nœuds : chaque entité a un champ
typeen majuscules (HOST,K8S_NAMESPACE,AWS_EC2_INSTANCE…) et un identifiant Smartscape de la formeENTITY_TYPE-000000000000007B, comparable à une chaîne. - Arêtes : une relation porte un type (
runs_on,calls,belongs_to…) et relie deux nœuds. Les arêtes statiques, issues de la configuration, héritent de la durée de vie du nœud ; les arêtes dynamiques, issues des signaux (un service qui en appelle un autre d’après les traces), sont enregistrées à un instant donné. - Durée de vie : un nœud n’a pas d’horodatage unique mais deux champs,
lifetime.startetlifetime.end. Une requête ne voit que les nœuds dont la durée de vie chevauche sa période.
Trois points de la documentation à retenir : une période de requête commençant il y a moins de 15 minutes est automatiquement étendue à 15 minutes ; la rétention est fixée à 35 jours ; les données Smartscape sont incluses dans la licence DPS, sans coût de requête supplémentaire. La permission nécessaire est storage:smartscape:read, qui couvre smartscapeNodes, smartscapeEdges, getNodeName() et getNodeField().
Étape par étape : interroger la topologie
Étape 1 — Lister les types de nœuds présents
smartscapeNodes "*"
| fields type
| dedup type
Le paramètre type accepte un type exact sans guillemets (HOST), une liste entre accolades ({ HOST, PROCESS }) ou un motif entre guillemets avec * ("*EC2*"). Un motif accepte au plus 64 jokers, et deux jokers consécutifs (**) ne sont pas pris en charge. Les paramètres optionnels from, to et timeframe fixent la période.
Étape 2 — Filtrer des nœuds
smartscapeNodes HOST
| fields id, type
| limit 10
Chaque nœud a un champ tags. Les étiquettes cloud et Kubernetes y sont rangées autrement que sur les logs : la documentation donne par exemple aws.tags.team qui devient tags:aws[team], et les labels de pod ou de workload qui deviennent tags:k8s.labels[*].
Étape 3 — Interroger les arêtes
smartscapeEdges "*"
| filter source_type == "K8S_POD"
| summarize by:{type, target_type}, edges = count()
Chaque arête expose type, source_id, source_type, target_id et target_type. Cette requête de la documentation dresse l’inventaire des relations qui partent des pods ; pour la syntaxe du regroupement, voir DQL group by.
Étape 4 — Parcourir la topologie avec traverse
Syntaxe documentée :
traverse edgeType, …, targetType, … [, direction] [, fieldsKeep: field, …] [, nodeId]
direction vaut forward (par défaut) ou backward. traverse suit une commande smartscapeNodes et lit l’identifiant du nœud source dans le champ id, sauf si nodeId en désigne un autre. Il renvoie les nœuds cibles avec un champ dt.traverse.history : un tableau d’enregistrements, un par parcours, contenant par défaut id, edge_type et direction, plus les champs listés dans fieldsKeep.

Le sens compte. Un processus tourne sur un hôte : on part du processus et on suit runs_on vers l’avant. Pour lister les services d’un namespace, on part du namespace et on remonte belongs_to vers l’arrière :
smartscapeNodes K8S_NAMESPACE
| filter tags[`example.com/annotation`] == "my-annotation"
| traverse belongs_to, K8S_SERVICE, direction: backward
Plusieurs types d’arêtes et de cibles se combinent entre accolades, comme dans cet exemple officiel :
smartscapeNodes CONTAINER
| filter k8s.workload.kind == "daemonset"
| traverse {runs_on, belongs_to}, {HOST, K8S_CLUSTER}, fieldsKeep:name
| fields container_name = dt.traverse.history[0][name], node_name = name, node_type = type
Étape 5 — Enrichir logs, spans et métriques
Les signaux rattachés à un nœud portent des champs dt.smartscape.<type>. Deux fonctions récupèrent les informations du nœud :
fetch bizevents
| fieldsAdd getNodeName(dt.smartscape.host)
timeseries avg(dt.host.cpu.idle), by:{ dt.smartscape.host }
| fieldsAdd getNodeField(dt.smartscape.host, "tags")
La documentation recommande getNodeField à la place de entityAttr. Le tableau ci-dessous résume les correspondances avec le modèle d’entités classique.

Les types de nœuds diffèrent parfois du modèle classique : CLOUD_APPLICATION_INSTANCE s’appelle K8S_POD dans Smartscape on Grail. Le champ id_classic donne l’identifiant classique correspondant, quand il existe (entités Kubernetes, entités de base et services).
Requêtes utiles en exploitation
- Rayon d’impact : partir d’un hôte en panne et remonter
runs_onenbackwardpour lister ce qui tourne dessus. - Inventaire par équipe : filtrer les nœuds sur un tag propriétaire, puis parcourir vers les ressources liées, comme l’exemple officiel des volumes EC2 attachés aux instances d’une équipe.
- Comptage par hôte :
smartscapeNodes CONTAINER | summarize by:references[runs_on.host], count()utilise le champ cachéreferences, qui expose les arêtes statiques depuis le nœud source.
Ces requêtes réduisent le MTTR : la question « qu’est-ce qui dépend de ce composant ? » obtient une réponse vérifiable, partagée dans un Notebook, au lieu d’une reconstitution de mémoire.
Comment vérifier que la requête est juste
- Lancez
smartscapeNodes "*" | fields type | dedup type: les types attendus doivent apparaître. Sinon, vérifiez la permissionstorage:smartscape:read. - Avant un
traverse, listez les arêtes réelles :smartscapeEdges "*" | filter source_type == "PROCESS" | summarize by:{type, target_type}, edges = count(). Un résultat vide aprèstraversevient souvent d’une direction inversée. - Élargissez la période si un nœud manque : un nœud dont
lifetime.endest antérieur à la période n’apparaît pas.
Bonnes pratiques
- Partez toujours du nœud le plus filtré, puis parcourez : moins de nœuds en entrée, résultat plus lisible.
- Gardez le nom du nœud source avec
fieldsKeeppour ne pas perdre le contexte. - Préférez les types exacts aux motifs
"*"dans les requêtes de tableau de bord. - Protégez les champs sensibles (par exemple
k8s.object) avec un fieldset sur la tablesmartscape, comme le décrit la documentation. - Pour la stratégie d’ensemble, reliez ces requêtes à vos requêtes DQL d’exploitation.
Questions fréquentes
Quelle différence entre fetch dt.entity.host et smartscapeNodes HOST ?
fetch dt.entity.host lit le modèle d’entités classique ; smartscapeNodes HOST lit Smartscape on Grail. Seul ce dernier permet d’interroger tous les types à la fois ("*"), toutes les relations et de parcourir la topologie avec traverse.
Peut-on utiliser un sélecteur d’entités dans Smartscape on Grail ?
Non : la documentation indique que classicEntitySelector n’y est pas pris en charge. Le parcours se fait avec traverse. Pour filtrer sur une liste d’identifiants, voir la fonction DQL in().
Combien de temps la topologie est-elle conservée ?
35 jours. Les nœuds dont lifetime.end dépasse cette durée sont supprimés avec leurs arêtes statiques ; les arêtes dynamiques sont nettoyées au même terme.
Conclusion
DQL Smartscape tient en trois commandes : smartscapeNodes pour trouver, smartscapeEdges pour inventorier les relations, traverse pour suivre une dépendance. Avec getNodeName et getNodeField pour enrichir les signaux, la topologie devient une donnée qu’on interroge, qu’on vérifie et qu’on partage, au lieu d’un schéma qu’on regarde. Pour situer ces requêtes dans une démarche plus large, voir observabilité vs monitoring.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Les marques citées appartiennent à leurs propriétaires. La syntaxe DQL évolue : vérifiez-la dans la documentation officielle avant de l’utiliser en production.