DQL Smartscape : interroger la topologie avec smartscapeNodes, smartscapeEdges et traverse

DQL Smartscape : interroger la topologie avec smartscapeNodes, smartscapeEdges et traverse, enrichir logs et métriques, avec des requêtes vérifiées.
DQL Smartscape : interroger la topologie avec smartscapeNodes, smartscapeEdges et traverse

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 type en majuscules (HOST, K8S_NAMESPACE, AWS_EC2_INSTANCE…) et un identifiant Smartscape de la forme ENTITY_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.start et lifetime.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.

Exemple de la documentation DQL : smartscapeNodes PROCESS filtré sur le binaire envoy, traverse runs_on vers HOST avec fieldsKeep name, puis fields process_name et host_name, avec la syntaxe de traverse et ses deux directions
Source : docs.dynatrace.com

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.

Correspondances documentées entre entités classiques et Smartscape on Grail : smartscapeNodes étoile, smartscapeNodes HOST au lieu de fetch dt.entity.host, smartscapeEdges étoile, dt.smartscape au lieu de dt.entity, getNodeName et getNodeField au lieu de entityName et entityAttr
Source : docs.dynatrace.com

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_on en backward pour 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

  1. Lancez smartscapeNodes "*" | fields type | dedup type : les types attendus doivent apparaître. Sinon, vérifiez la permission storage:smartscape:read.
  2. 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ès traverse vient souvent d’une direction inversée.
  3. Élargissez la période si un nœud manque : un nœud dont lifetime.end est 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 fieldsKeep pour 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 table smartscape, 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.

Total
0
Shares
Laisser un commentaire

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

Previous Post
DQL fonction in() : filtrer sur une liste, un tableau ou une sous-requête

DQL fonction in() : filtrer sur une liste, un tableau ou une sous-requête

Next Post
Formation observabilité gratuite : le chemin complet, des signaux aux SLO

Formation observabilité gratuite : le chemin complet, des signaux aux SLO

Related Posts