Module 7 du parcours métriques Dynatrace Managed, consacré au metric selector, alertes et API Metrics v2 : écrire une requête de métriques, l’appeler en curl, créer les métriques qui manquent, puis déclencher une alerte Davis quand elles dérivent.
Parcours : Formation aux métriques Dynatrace Managed · Module 7/7 · Durée : ~75 min · Niveau : Intermédiaire à avancé
Objectifs :
- Lire le descripteur d’une métrique et enchaîner les transformations du metric selector
- Écrire une expression arithmétique entre métriques et appeler
/api/v2/metrics/queryen curl - Créer une métrique calculée de service, une métrique de logs ou une métrique ingérée
- Configurer un metric event : seuil statique, auto-adaptatif ou baseline saisonnière
Prérequis : les modules 2 à 6 ; un jeton d’API avec le scope metrics.read, puis WriteConfig, metrics.ingest et settings.write selon les étapes ; curl, jq et un environnement de recette.
Les modules précédents ont montré quelles métriques regarder. Celui-ci montre comment les interroger, puis comment en faire un signal d’astreinte. Le metric selector est le langage commun au Data Explorer, aux tuiles de tableau de bord, aux metric events et à l’API Metrics v2 : la même chaîne de caractères sert à tracer une courbe, à alimenter un SLO et à lever une alerte.
Ce module vaut pour Dynatrace Managed (et pour les métriques classiques de SaaS). Il ne traite pas de DQL ni de la commande timeseries de Grail, réservées à Dynatrace SaaS et traitées dans le parcours métriques SaaS.
Metric selector, alertes, API : la même syntaxe partout
Un selector commence par une ou plusieurs clés de métriques, suivies de transformations séparées par des deux-points, évaluées de gauche à droite. Chaque transformation s’applique au résultat de la précédente.
builtin:host.cpu.usage:sort(value(avg,descending)):limit(10)
Deux limites à connaître : un selector contient au moins une clé, et une requête interroge au plus 10 métriques. Pour plusieurs métriques d’un même parent, la documentation autorise la forme courte builtin:host.cpu.(usage,idle).
Le conseil de la documentation Dynatrace : construisez vos selectors dans l’onglet Code du Data Explorer (mode avancé), qui propose l’autocomplétion, puis copiez-les dans l’API ou dans une configuration.
Commencer par le descripteur
Avant d’écrire un selector, lisez le descripteur de la métrique avec GET /api/v2/metrics/{metricId}. Trois champs comptent : aggregationTypes (les agrégations possibles), defaultAggregation (celle appliquée si vous n’en précisez pas) et dimensionDefinitions (les clés de dimensions utilisables dans splitBy et filter).

Ici, builtin:host.cpu.usage s’agrège par défaut en moyenne et n’a qu’une dimension, dt.entity.host.
Les transformations essentielles
| Transformation | Syntaxe | Effet |
|---|---|---|
| Agrégation | :max, :avg, :percentile(90)… |
Agrégation dans le temps, par intervalle |
| Split by | :splitBy("dim1","dim2") |
Garde ces dimensions, fusionne les autres ; :splitBy() fusionne tout |
| Filter | :filter(eq("dim","valeur")) |
Filtre sur une dimension ou sur la valeur d’une série |
| Fold | :fold(max) |
Réduit chaque série à un seul point |
| Sort / Limit | :sort(value(avg,descending)):limit(10) |
Top N |
| Default | :default(0) |
Remplace les valeurs nulles |
| Rate | :rate(1m) |
Convertit un compteur en débit |
| Rollup | :rollup(avg,15m) |
Lisse sur une fenêtre glissante |
| Time shift | :timeshift(-1d) |
Décale la période (comparaison avec la veille) |
| To unit | :toUnit(<source>,<cible>) |
Convertit l’unité des points (liste des unités : GET /api/v2/units) |
Agrégation dans le temps et dans l’espace
Sans agrégation explicite, la métrique utilise son agrégation par défaut. Pour voir le pic de CPU de chaque intervalle plutôt que la moyenne :
builtin:host.cpu.usage:max
Pour obtenir un seul chiffre, le pic de toute la période, ajoutez fold :
builtin:host.cpu.usage:fold(max)
L’agrégation dans l’espace passe par splitBy. Sans argument, elle fusionne tous les hôtes en une seule série :
builtin:host.cpu.usage:splitBy()
Filtrer par dimension, par entité ou par valeur
Le filtre eq compare une dimension à une valeur ; in accepte un entity selector, ce qui permet de filtrer par tag. Les guillemets internes s’échappent avec un tilde :
builtin:host.cpu.usage
:filter(
in(
"dt.entity.host",entitySelector("type(~"HOST~"),tag(~"easyTravel~")")
)
)
La condition series filtre sur la valeur agrégée de chaque série : ici, seuls les hôtes dont la moyenne dépasse 80 % restent.
builtin:host.cpu.usage:filter(series(avg,gt(80)))
Les conditions se combinent avec and, or et not.
Rate, rollup et timeshift exigent une agrégation
La documentation impose d’appliquer une agrégation avant rate, rollup et toUnit. Exemple de lissage sur 15 minutes, utile pour un graphique de tendance :
builtin:host.cpu.usage:avg:rollup(avg,15m)
Et la même métrique décalée d’un jour, à superposer à la courbe du jour :
builtin:host.cpu.usage:timeshift(-1d)
Expressions arithmétiques entre métriques
Le selector accepte les opérations + - * / entre métriques et nombres, avec des parenthèses. Les séries sont appariées par tuple de dimensions puis alignées par horodatage. L’exemple de la documentation calcule un taux d’erreur de service :
builtin:service.errors.total.count:value:default(0)
/
(
builtin:service.errors.total.successCount:value:default(0)
+
builtin:service.errors.total.count:value:default(0)
)
Le default(0) évite qu’un intervalle sans erreur rende tout le ratio nul. Deux règles de la documentation : appliquez limit au résultat de l’expression, jamais aux opérandes, et n’utilisez pas d’expression pour convertir une unité (préférez toUnit).
Appeler l’API Metrics v2 en curl
En Managed, l’endpoint est https://{votre-domaine}/e/{id-environnement}/api/v2/metrics/query (ou via un ActiveGate, port 9999 par défaut). Il exige le scope metrics.read.

Adapté à un cluster Managed, avec curl qui encode les paramètres :
export DT_ENV="https://dynatrace.example.com/e/votre-id-environnement"
curl -sS -G "$DT_ENV/api/v2/metrics/query" \
-H "Authorization: Api-Token $DT_TOKEN" \
--data-urlencode 'metricSelector=builtin:host.cpu.usage:sort(value(avg,descending)):limit(5)' \
--data-urlencode 'from=now-24h' \
--data-urlencode 'resolution=1h' \
| jq '.result[0].data[] | {host: .dimensionMap["dt.entity.host"], last: .values[-1]}'
Les paramètres à connaître :
resolution: par défaut 120 points ; une durée (10m,1h) ouInfpour un seul point. La résolution la plus fine est la minute, et elle dépend aussi de l’âge des données.from/to: horodatage, date ISO ou relatif (now-2h, valeur par défaut defrom).entitySelector: restreint aux entités choisies, par exempletype("HOST"),tag("prod").mzSelector: restreint à une management zone, par exemplemzName("Paiement").- En-tête
Accept: text/csv; header=present: réponse en CSV au lieu de JSON.
La liste complète des endpoints Managed est dans API Dynatrace Managed : endpoints et schémas, et l’automatisation plus générale dans le module 8 du parcours Managed.
Créer les métriques qui manquent
Les métriques intégrées couvrent l’essentiel, mais pas tout : le temps de réponse d’un seul endpoint de paiement, le nombre de commandes refusées lu dans un log, la profondeur d’une file interne. Trois mécanismes comblent ces trous : métriques calculées de service (calc:service.), métriques de logs (log.) et ingestion de métriques.
Ces métriques sont des métriques personnalisées : contrairement aux métriques intégrées, elles consomment des Davis data units (DDU). Créez-les pour un besoin précis, pas par réflexe.
Créer une métrique calculée de service
Une métrique calculée de service applique des conditions aux requêtes d’un service (tag, chemin d’URL, attribut de requête…) et mesure une valeur : REQUEST_COUNT, RESPONSE_TIME, FAILURE_RATE, ERROR_COUNT, CPU_TIME, etc. Elle peut être découpée par une dimension, limitée aux N valeurs principales.
L’API de configuration la crée avec POST /api/config/v1/calculatedMetrics/service (scope WriteConfig). L’exemple de la documentation compte les requêtes des services tagués payment, par classe de statut HTTP :

curl -sS -X POST "$DT_ENV/api/config/v1/calculatedMetrics/service" \
-H "Authorization: Api-Token $DT_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d @requestsbycode.json
# réponse attendue (201) : {"id":"calc:service.requestsbycode","name":"Requests by code"}
Points d’attention :
tsmMetricKeycommence obligatoirement parcalc:service.; c’est la clé à utiliser ensuite dans le metric selector.dimensionDefinitionavectopXplafonne le nombre de valeurs de dimension conservées : un découpage par URL complète exploserait la cardinalité.- La métrique n’a pas d’historique : elle commence à se remplir à sa création.
Une fois créée, elle s’interroge comme les autres : calc:service.requestsbycode:splitBy("dt.entity.service"):sum par exemple, à adapter aux dimensions de son descripteur.
Extraire une métrique de logs
En Log Monitoring Classic, une métrique de logs se crée dans Settings > Log Monitoring > Metrics extraction, avec Add log metric, ou depuis le log viewer avec Create metric. Sa clé commence toujours par log.. Vous choisissez :
- un Matcher : la requête de log qui sélectionne les lignes ;
- une mesure : Occurrence of log records (nombre de lignes) ou Attribute value (valeur numérique d’un attribut) ;
- des dimensions optionnelles, prises parmi les attributs de log.
Exemple typique : log.payment.refused, qui compte les lignes contenant le code de refus d’un prestataire de paiement, découpé par prestataire. Deux limites : la métrique n’existe qu’à partir des logs ingérés après sa création, et la documentation fixe un plafond de 1 000 000 de valeurs de dimension par métrique. Choisissez des dimensions à faible cardinalité. Modifier la clé crée une nouvelle métrique : l’historique reste sous l’ancienne.
Ingérer vos propres métriques
Pour une mesure qu’aucun agent ne voit (taille d’une file, résultat d’un batch, chiffre métier), envoyez des points sur POST /api/v2/metrics/ingest (scope metrics.ingest), au format texte du protocole d’ingestion. Une ligne = un point :

curl -sS -X POST "$DT_ENV/api/v2/metrics/ingest" \
-H "Authorization: Api-Token $DT_TOKEN" \
-H "Content-Type: text/plain; charset=utf-8" \
--data-binary 'batchjob.duration,job=facturation,dt.entity.host=HOST-4587AE40F95AD90D gauge,412'
# réponse attendue (202) : "linesOk": 1, "linesInvalid": 0
Les règles du protocole à retenir :
- Gauge par défaut ; le format
count,delta=…crée une métrique suffixée.count. - 50 dimensions maximum ;
dt.entity.host(et les autresdt.entity.*) rattache le point à une entité, donc les alertes à cette entité. - Horodatage en millisecondes UTC, accepté d’une heure dans le passé à dix minutes dans le futur.
- Préfixe
dt.interdit, réservé à Dynatrace ; charge utile limitée à 1 Mo par requête. - Depuis un hôte surveillé, OneAgent expose aussi un endpoint local (
http://localhost:14499/metrics/ingestpar défaut) qui ne demande pas de jeton.
Metric selector et alertes : les metric events
Un metric event transforme n’importe quelle métrique, intégrée ou personnalisée, en événement Davis, donc en problème et en notification. Il se configure dans Settings > Anomaly detection > Metric events, ou par l’API Settings avec le schéma builtin:anomaly-detection.metric-events.
- Type de requête :
METRIC_KEY(une clé, seuil statique uniquement) ouMETRIC_SELECTOR(un selector complet, expressions comprises). - Modèle :
STATIC_THRESHOLD,AUTO_ADAPTIVE_THRESHOLDouSEASONAL_BASELINE; les deux derniers exigent un metric selector. - Fenêtre glissante :
sampleséchantillons d’une minute, dontviolatingSamplesdoivent violer le seuil pour ouvrir l’événement, etdealertingSamplesrevenir à la normale pour le fermer. - Données manquantes :
alertOnNoData; la documentation conseille de le désactiver pour les séries clairsemées.
Exemple : alerter quand le taux d’échec d’un service tagué payment dépasse 5 % pendant 3 minutes sur 5. Le corps suit les champs du schéma ; vérifiez-les sur votre version avec GET /api/v2/settings/schemas/builtin:anomaly-detection.metric-events.
[{
"schemaId": "builtin:anomaly-detection.metric-events",
"scope": "environment",
"value": {
"enabled": true,
"summary": "Taux d'échec paiement > 5 %",
"queryDefinition": {
"type": "METRIC_SELECTOR",
"metricSelector": "builtin:service.errors.total.rate:filter(in(\"dt.entity.service\",entitySelector(\"type(~\"SERVICE~\"),tag(~\"payment~\")\"))):splitBy(\"dt.entity.service\"):avg"
},
"modelProperties": {
"type": "STATIC_THRESHOLD",
"threshold": 5,
"alertCondition": "ABOVE",
"alertOnNoData": false,
"samples": 5,
"violatingSamples": 3,
"dealertingSamples": 5
},
"eventTemplate": {
"title": "Taux d'échec paiement élevé",
"description": "Le taux d'échec dépasse 5 %.",
"eventType": "ERROR",
"davisMerge": true
}
}
}]
Envoyez-le avec POST /api/v2/settings/objects (scope settings.write). Le routage des notifications qui suivent relève des profils d’alerte : voyez Alerting, profils et intégrations en Managed et, pour éviter l’avalanche, Réduire le bruit des alertes Davis.
Exercice pratique
Étape 1 — Lire un descripteur
curl -sS "$DT_ENV/api/v2/metrics/builtin:host.disk.avail" \
-H "Authorization: Api-Token $DT_TOKEN" | jq '.dimensionDefinitions[].key'
Résultat attendu : dt.entity.host et dt.entity.disk.
Étape 2 — Construire un top 5 dans le Data Explorer
Dans l’onglet Code, écrivez un selector qui affiche les cinq hôtes au CPU moyen le plus élevé sur 24 heures, puis ajoutez une seconde requête avec :timeshift(-1d). Résultat attendu : deux courbes superposées sur la même période.
Étape 3 — Ingérer une métrique et la retrouver
Envoyez cinq points de batchjob.duration à une minute d’intervalle avec la commande d’ingestion ci-dessus, puis saisissez batchjob.duration:splitBy("job"):max dans le Data Explorer. Résultat attendu : "linesOk": 1 à chaque envoi, puis une série facturation avec vos cinq valeurs.
Étape 4 — Un metric event de test
Créez un metric event à seuil statique sur cette métrique, avec un seuil inférieur à vos valeurs. Résultat attendu : un problème ouvert sur l’hôte référencé par dt.entity.host.
Étape 5 — Comment vérifier que ça fonctionne
La réponse de /api/v2/metrics/query doit contenir "totalCount" et un tableau result ; un code 403 indique un scope manquant, un 400 une erreur de syntaxe décrite dans le message. Ouvrez ensuite le problème : l’événement porte le titre de votre eventTemplate. Dans Settings > Anomaly detection > Metric events, la vue d’ensemble signale aussi les configurations en échec (QUERY_FAILED, THROTTLED) sur les dernières 24 heures. Supprimez enfin l’événement de test.
Bonnes pratiques
- Prototypez dans le Data Explorer, puis copiez le selector dans le script, le tableau de bord ou le metric event.
- Filtrez tôt et toujours
sortavantlimit: moins de séries lues, un top N qui a un sens. - Une métrique personnalisée par question, pas par curiosité : chacune consomme des DDU.
- Cardinalité maîtrisée :
topXpour les métriques calculées, dimensions à valeurs limitées pour les logs et l’ingestion. - Plusieurs échantillons en violation plutôt qu’un seul, et alerte sur le symptôme (taux d’échec, latence) : moins de faux positifs, moins de fatigue d’astreinte.
- Versionnez vos selectors avec les tableaux de bord et les alertes : ce sont vos SLI.
Quiz
- Que renvoie
builtin:host.cpu.usage:fold(max)? a) Une série par minute b) Un point par série : le maximum de la période c) La moyenne de tous les hôtes d) Une erreur - Que fait
:splitBy()sans argument ? a) Rien b) Fusionne toutes les dimensions en une série c) Découpe par toutes les dimensions d) Supprime les valeurs nulles - Quel scope faut-il pour
/api/v2/metrics/query? a)ReadConfigb)metrics.ingestc)metrics.readd)entities.read - Par quel préfixe commence une métrique calculée de service ? a)
builtin:b)calc:service.c)log.d)ext: - Quel préfixe est interdit à l’ingestion ? a)
custom.b)app.c)dt.d) aucun - Que signifie
violatingSamples: 3avecsamples: 5? a) 3 alertes sur 5 jours b) 3 minutes en violation sur une fenêtre de 5 minutes ouvrent l’événement c) 3 % de tolérance d) 5 relances
Corrigé
- b)
foldréduit la série à un seul point avec l’agrégation demandée. - b) Toutes les séries sont fusionnées.
- c)
metrics.read. - b)
calc:service.. - c)
dt.est réservé à Dynatrace. - b) Les échantillons durent une minute.
Pour aller plus loin
- Dashboard Dynatrace Managed : tuiles, Data Explorer et JSON
- SLO Dynatrace Managed : configuration et API, où les SLI sont des metric selectors
- Davis, problèmes et alerting en Managed
- Metric selector (documentation Dynatrace Managed)
- Metric ingestion protocol (documentation Dynatrace Managed)
← Module 6 : cloud et extensions · Sommaire du parcours · Fin du parcours
Questions fréquentes
Pourquoi ma requête renvoie-t-elle moins de points que demandé ?
La résolution est une valeur de référence : Dynatrace l’ajuste selon la période et l’âge des données. Les données anciennes ne sont plus disponibles à la minute.
Une métrique calculée récupère-t-elle l’historique ?
Non. Elle se remplit à partir de sa création. Si vous avez besoin du passé, analysez les traces existantes dans l’analyse multidimensionnelle du service, puis créez la métrique pour la suite.
Metric event ou détection d’anomalies automatique de Davis ?
Les deux se complètent. Davis surveille déjà services, applications et infrastructure avec ses références automatiques. Le metric event sert aux métriques que Davis ne surveille pas seul : métriques calculées, de logs ou ingérées, ou un seuil contractuel précis.
Vous avez terminé le parcours : vous savez lire une clé de métrique, choisir la bonne pour un hôte, un service, une application, un processus ou une ressource cloud, l’interroger en selector et par l’API, et créer puis surveiller vos propres métriques. Gardez le sommaire sous la main comme aide-mémoire.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Ce parcours ne remplace pas les formations et certifications officielles de Dynatrace University. Vérifiez les clés de métriques et les fonctionnalités dans la documentation officielle de votre version.