Module 7 — Requêter et alerter : metric selector, alertes, API Metrics v2 et métriques calculées

Metric selector, alertes et API Metrics v2 en Dynatrace Managed : transformations, appels curl, métriques calculées et événements de métrique, avec quiz.
Module 7 — Requêter et alerter : metric selector, alertes, API Metrics v2 et métriques calculées

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/query en 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).

Descripteur de la métrique builtin:host.cpu.usage tel que le montre la documentation Dynatrace Managed : agrégations auto, avg, max, min, agrégation par défaut avg, dimension dt.entity.host

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.

Exemple curl de la documentation Dynatrace Managed pour GET metric data points : metricSelector builtin:host.cpu.(usage,idle):fold, entitySelector sur deux hôtes, from=now-5m

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) ou Inf pour 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 de from).
  • entitySelector : restreint aux entités choisies, par exemple type("HOST"),tag("prod").
  • mzSelector : restreint à une management zone, par exemple mzName("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 :

Corps de requête de l'exemple de la documentation Dynatrace Managed pour créer la métrique calculée calc:service.requestsbycode : REQUEST_COUNT, condition sur le tag payment, dimension HTTP Status class limitée aux 10 premières valeurs
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 :

  • tsmMetricKey commence obligatoirement par calc:service. ; c’est la clé à utiliser ensuite dans le metric selector.
  • dimensionDefinition avec topX plafonne 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 :

Exemples de lignes du protocole d'ingestion de métriques tirés de la documentation Dynatrace Managed : gauge simple, gauge résumée min max sum count, rattachement à un hôte par dt.entity.host, horodatage
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 autres dt.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/ingest par 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) ou METRIC_SELECTOR (un selector complet, expressions comprises).
  • Modèle : STATIC_THRESHOLD, AUTO_ADAPTIVE_THRESHOLD ou SEASONAL_BASELINE ; les deux derniers exigent un metric selector.
  • Fenêtre glissante : samples échantillons d’une minute, dont violatingSamples doivent violer le seuil pour ouvrir l’événement, et dealertingSamples revenir à 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 sort avant limit : 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 : topX pour 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

  1. 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
  2. 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
  3. Quel scope faut-il pour /api/v2/metrics/query ? a) ReadConfig b) metrics.ingest c) metrics.read d) entities.read
  4. Par quel préfixe commence une métrique calculée de service ? a) builtin: b) calc:service. c) log. d) ext:
  5. Quel préfixe est interdit à l’ingestion ? a) custom. b) app. c) dt. d) aucun
  6. Que signifie violatingSamples: 3 avec samples: 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é

  1. b) fold réduit la série à un seul point avec l’agrégation demandée.
  2. b) Toutes les séries sont fusionnées.
  3. c) metrics.read.
  4. b) calc:service..
  5. c) dt. est réservé à Dynatrace.
  6. b) Les échantillons durent une minute.

Pour aller plus loin

← 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.

Total
0
Shares
Laisser un commentaire

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

Previous Post
Module 6 — Cloud et extensions : les métriques cloud Managed, VMware, AWS, Azure

Module 6 — Cloud et extensions : les métriques cloud Managed, VMware, AWS, Azure

Next Post
Module 4 — Métriques RUM Grail : frontends et synthétique dt.frontend.* et dt.synthetic.*

Module 4 — Métriques RUM Grail : frontends et synthétique dt.frontend.* et dt.synthetic.*

Related Posts