L’ID entité Dynatrace est la clé que réclament presque toutes les automatisations : scope d’un objet Settings, filtre d’un SLO, sélecteur d’une alerte, paramètre d’un module Terraform ou Monaco. Un nom d’hôte ou de service ne suffit pas : il change, se répète d’un environnement à l’autre et n’est pas unique. L’ID, lui, désigne une entité précise, par exemple SERVICE-1125C375A187D27A.
Le retrouver devrait prendre dix secondes. En pratique, on perd souvent du temps à copier un mauvais identifiant, à récupérer cinquante résultats au lieu d’un, ou à écrire une requête qui ne marche que sur une plateforme. Moins de toil ici, c’est des runbooks plus fiables et des automatisations qui ne cassent pas au premier renommage.
Ce guide couvre trois méthodes : l’API Monitored entities v2 avec un entitySelector (Managed et SaaS), DQL dans un Notebook (SaaS uniquement, Grail) et le passage de l’un à l’autre avec classicEntitySelector().
Ce qu’est un ID entité Dynatrace
Chaque objet surveillé (hôte, processus, service, application, test synthétique…) est une entité, avec un type et un identifiant. L’ID suit la forme TYPE-IDENTIFIANT : HOST-…, SERVICE-…, HTTP_CHECK-…, SYNTHETIC_TEST-…. Le nom affiché (displayName dans l’API, entity.name en DQL) est une étiquette ; c’est l’ID qu’attendent les API.
Exemple concret : pour déclarer des key requests par l’API Settings, le champ scope doit contenir l’ID du service, et la documentation renvoie justement vers l’appel GET entities list pour le trouver.
Prérequis
- Pour l’API : un token avec le scope
entities.read. Une erreur 401 ou 403 à ce stade relève du dépannage de token API. - URL de base :
https://{votre-domaine}/e/{id-environnement}en Managed,https://{id-environnement}.live.dynatrace.comen SaaS. Via un ActiveGate :https://{domaine-activegate}:9999/e/{id-environnement}. - Pour DQL (SaaS) : la permission
storage:entities:read.
Méthode 1 — L’API et l’entitySelector (Managed et SaaS)
Étape 1 — Chercher par type et par nom
L’appel GET /api/v2/entities exige l’un de deux critères : le type (type("…")) ou l’ID (entityId("…")). On ajoute ensuite le nom :
curl -s -G "$DT_URL/api/v2/entities" \
-H "Authorization: Api-Token $DT_TOKEN" \
--data-urlencode 'entitySelector=type("SERVICE"),entityName.equals("AuthenticationService")' \
--data-urlencode 'from=now-7d'
Trois détails comptent :
entityName("…")seul fait un CONTAINS, insensible à la casse par défaut.entityName.equals("…")exige l’égalité,entityName.startsWith("…")un préfixe,entityName.in("a","b")une liste. Pour une comparaison sensible à la casse :caseSensitive(entityName.equals("…")).- Sans
from, la recherche porte sur les trois derniers jours (now-3d). Une entité éteinte la semaine dernière n’apparaît donc pas : élargissez la fenêtre. - Si la valeur contient une parenthèse ou une virgule, mettez-la entre guillemets.

La réponse contient totalCount, pageSize (50 par défaut) et, s’il reste des résultats, un nextPageKey. Pour la page suivante, passez uniquement nextPageKey : la documentation impose d’omettre alors tous les autres paramètres.
Étape 2 — Affiner quand le nom ne suffit pas
Plusieurs services portent le même nom (un par environnement de test, un par cluster) ? Combinez les critères ; seules les entités qui les remplissent tous sont renvoyées :
# par tag
type("SERVICE"),entityName.equals("checkout"),tag("env:prod")
# par management zone
type("SERVICE"),entityName.equals("checkout"),mzName("Payments")
# par relation : les services qui tournent sur un hôte donné
type("SERVICE"),fromRelationships.runsOnHost(type("HOST"),entityName.equals("web-01"))
# en excluant
type("HOST"),not(tag("Infrastructure:Linux"))
Pour savoir quelles propriétés et relations un type expose, appelez GET /api/v2/entityTypes/{type} et regardez properties, fromRelationships et toRelationships. Le paramètre fields ajoute des champs à la réponse, par exemple fields=+lastSeenTms,+properties.serviceTechnologyTypes.
Étape 3 — Extraire l’ID proprement
curl -s -G "$DT_URL/api/v2/entities" \
-H "Authorization: Api-Token $DT_TOKEN" \
--data-urlencode 'entitySelector=type("HOST"),entityName.startsWith("web-")' \
| jq -r '.entities[] | "\(.entityId)\t\(.displayName)"'
Vous avez déjà un ID et voulez vérifier à quoi il correspond ? GET /api/v2/entities/{entityId} renvoie le détail de l’entité, avec le même scope entities.read.
Limites à garder en tête : un sélecteur fait au plus 2 000 caractères et ne vise qu’un seul type d’entité par requête. Les entités supprimées (tests synthétiques, applications, custom devices…) sont exclues par défaut ; deletedEntities.include() les réintègre.
Méthode 2 — DQL dans un Notebook (SaaS)
Dans Dynatrace SaaS, ouvrez un Notebook et tapez fetch dt.entity. : l’autocomplétion propose les types d’entités. Chaque enregistrement contient par défaut l’ID et le nom.
fetch dt.entity.service
| filter entity.name == "AuthenticationService"
| fields id, entity.name
Pour découvrir les champs disponibles d’un type, describe dt.entity.service en donne la liste. Pour filtrer selon des relations, la documentation recommande de réutiliser un sélecteur classique, plus rapide et plus complet que des expand/lookup en DQL natif (limités à 100 IDs par type et par enregistrement) :
fetch dt.entity.host
| filter in(id, classicEntitySelector("type(host),toRelationship.isProcessOf(type(PROCESS_GROUP_INSTANCE),softwareTechnologies(JAVA))"))
| fields id, entity.name
Deux mises en garde propres à Grail. D’abord, Grail n’applique pas les management zones : quiconque a storage:entities:read voit toutes les entités. Ensuite, depuis la version 1.334, la documentation annonce une transition vers le nouveau stockage Smartscape et déconseille les requêtes d’entités classiques ; le modèle Smartscape on Grail s’interroge avec smartscapeNodes, par exemple smartscapeNodes HOST | fields id, type | limit 10. Testez vos requêtes sur ce modèle avant de les figer dans un dashboard. Pour d’autres requêtes du quotidien, voir les requêtes DQL d’exploitation.
Méthode 3 — Dans Managed : rester sur l’API
Dynatrace Managed n’a ni Grail ni DQL. La méthode documentée reste l’API v2 avec l’entitySelector : même syntaxe, même scope, même pagination, avec l’URL https://{votre-domaine}/e/{id-environnement}/api/v2/entities. Le même sélecteur sert ensuite dans les SLO, le metric selector et les API de configuration, ce qui en fait un investissement rentable. Le panorama des endpoints est dans les API Dynatrace Managed.
Bonnes pratiques
- Cherchez avec
entityName.equalsplutôt qu’avecentityNameseul : le CONTAINS par défaut ramène des homonymes partiels. - Vérifiez toujours
totalCount: un script qui attend un résultat doit échouer s’il en reçoit deux. - Stockez l’ID dans votre configuration as code, mais gardez à côté le sélecteur qui l’a produit pour pouvoir le régénérer.
- Donnez au token de recherche le seul scope
entities.read, sans droit d’écriture.
Comment vérifier que ça fonctionne
Rejouez l’appel avec le sélecteur entityId("…") et l’ID obtenu : la réponse doit contenir exactement une entité, avec le displayName attendu et un lastSeenTms récent. En DQL, fetch dt.entity.service | filter id == "SERVICE-…" doit renvoyer un seul enregistrement. Si rien ne revient, élargissez la fenêtre de temps : l’entité n’a peut-être pas été vue depuis trois jours.
Références officielles : Entity selector et Query monitored entities in Grail.
Questions fréquentes
Pourquoi l’API ne trouve-t-elle pas une entité que je vois encore dans un ancien rapport ?
Sans paramètre from, la recherche se limite aux trois derniers jours. Ajoutez from=now-30d, et pour certains types (tests synthétiques, applications) deletedEntities.include().
Puis-je demander des hôtes et des services dans le même appel ?
Non, un sélecteur ne vise qu’un type par requête. Faites deux appels, ou passez par une relation (fromRelationships, toRelationships) pour obtenir le type voisin.
Les management zones filtrent-elles les résultats DQL ?
Non. La documentation précise que Grail n’applique pas les filtres de management zone aux entités ; c’est la permission storage:entities:read qui donne accès à l’ensemble.
Conclusion
Un bon réflexe : chercher l’ID par l’API avec un sélecteur précis, vérifier qu’un seul résultat revient, puis réutiliser ce même sélecteur partout où Dynatrace l’accepte. En SaaS, DQL et classicEntitySelector() font le pont avec les Notebooks, en gardant un œil sur la transition vers Smartscape on Grail.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de son propriétaire. Les syntaxes et limites peuvent évoluer selon la version et la plateforme (SaaS ou Managed) : vérifiez-les dans la documentation officielle.