Créer une métrique custom Dynatrace : calculated metrics, log metrics, Metrics API et OneAgent SDK

Métrique custom Dynatrace : calculated service metrics, log metrics, OpenPipeline, ingestion par Metrics API et OneAgent SDK, avec limites et vérification.
Créer une métrique custom Dynatrace : calculated metrics, log metrics, Metrics API et OneAgent SDK

Le métier demande un SLO sur les commandes validées, l’équipe paiement veut suivre les refus par motif, l’exploitation veut compter les erreurs d’un batch qui n’écrit que des logs. Aucune de ces valeurs n’existe dans les métriques intégrées. Il faut créer une métrique custom Dynatrace, et le choix de la méthode compte autant que la métrique elle-même : il détermine la cardinalité possible, le coût, et ce qu’il faudra modifier le jour où la source change.

Ce guide compare les quatre façons de créer une métrique custom Dynatrace : les calculated service metrics (à partir des traces), les log metrics (à partir des logs), l’ingestion par la Metrics API (depuis un script ou une application), et le OneAgent SDK, qui ne crée pas de métrique mais fournit la matière première. Chaque méthode est illustrée par un exemple et une vérification.

Le contenu couvre Dynatrace Managed et Dynatrace SaaS. Les différences sont signalées : en SaaS sur Grail, OpenPipeline devient la voie recommandée pour extraire des métriques des logs et des spans, et la syntaxe de requête passe du metric selector à DQL.

Quelle méthode pour créer une métrique custom Dynatrace

La donnée est dans… Méthode Préfixe de clé Plateformes
Les requêtes d’un service (traces) Calculated service metric calc:service. Managed, SaaS (OpenPipeline recommandé sur Grail)
Les logs Log metric log. Managed, SaaS (OpenPipeline Metric extraction sur Grail)
Un script, un job, une application Metrics API ingest Libre (sauf dt.) Managed, SaaS
Une technologie non instrumentée OneAgent SDK, puis calculated metric calc:service. Managed, SaaS

Règle simple : si la donnée passe déjà par Dynatrace (traces, logs), dérivez la métrique de cette donnée plutôt que de l’envoyer une seconde fois. Réservez l’ingestion aux valeurs que Dynatrace ne voit pas. Pour les bases (types de métriques, dimensions, résolution), voir le module « comprendre les métriques ».

Méthode 1 — Calculated service metrics (traces)

Dynatrace capture déjà chaque requête de service. Une calculated service metric en extrait une valeur (temps de réponse, nombre de requêtes, valeur d’un request attribute…) pour les requêtes qui remplissent des conditions, avec un découpage optionnel par dimension.

Étapes

  1. Allez dans Settings > Server-side service monitoring > Calculated service metrics > Create new metric.
  2. Donnez un nom : Dynatrace préfixe automatiquement la clé par calc:service..
  3. Choisissez la Metric source. Pour un request attribute, sélectionnez l’unité.
  4. Option : management zone, et Ignore muted requests.
  5. Ajoutez les conditions (toutes doivent être vraies), par exemple service = checkout et request attribute orderStatus = VALIDATED. L’aperçu liste les services concernés.
  6. Option : Split by dimension, avec un placeholder (ou un custom placeholder extrait par délimiteur ou regex) et le nombre de top values.
  7. Relisez la source et les noms de dimensions : ils ne pourront plus être modifiés. Save metric.

Limites à connaître

  • Seules les nouvelles données alimentent la métrique : aucun calcul rétroactif.
  • 500 calculated metrics actives par environnement, 100 par service.
  • Règle « top X » : au plus 100 valeurs de dimension ; le reste est agrégé dans une dimension remainder.

Sur SaaS, la documentation recommande désormais d’extraire ces métriques des spans avec OpenPipeline : pas de limite de 500 métriques ni de règle top X, cardinalité complète, routage vers des buckets Grail. Pour les request attributes eux-mêmes, voir Distributed traces et PurePath.

Méthode 2 — Log metrics (logs)

Managed et Log Monitoring Classic

  1. Allez dans Settings > Log Monitoring > Metrics extraction et sélectionnez Add log metric (ou, depuis le log viewer, Create metric sur une requête).
  2. Metric key : complétez après log., par exemple log.paiement_refus.
  3. Matcher : la requête qui filtre les logs, par exemple status="error".
  4. Measure : Occurrence of log records (comptage) ou Attribute value (moyenne, somme, min, max, médiane, percentiles d’un attribut numérique).
  5. Add dimension : par exemple le process group instance, pour savoir où se produisent les erreurs.

Deux pièges. La métrique n’existe qu’à partir des logs ingérés après sa création. Et modifier la clé crée une nouvelle métrique : l’historique reste sous l’ancienne clé. Sur Managed, la documentation cite une limite de 1 000 000 de dimensions par métrique et 50 000 000 pour l’ensemble ; la création de métriques à partir de logs supprimés (dropped logs) n’y est pas disponible.

SaaS sur Grail : OpenPipeline

Dans OpenPipeline, l’étape Metric extraction propose les processeurs Counter metric (compte les enregistrements), Value metric (gauge à partir d’un champ numérique) et Histogram metric (distribution), plus des variantes pour spans échantillonnés. Chaque processeur a une condition DQL, une clé et des dimensions ; l’enregistrement source n’est pas modifié.

Exemple de la documentation OpenPipeline : processeur Counter metric avec condition isNotNull(http.status_code) AND toLong(http.status_code) supérieur ou égal à 400, clé log.http.errors, dimension status_code et point créé

Pour les histogrammes, voir métriques histogrammes avec OpenPipeline.

Méthode 3 — Ingestion par la Metrics API

Pour une valeur que Dynatrace ne voit pas (résultat d’un job, compteur métier, mesure d’un équipement), envoyez-la avec POST /api/v2/metrics/ingest. Pas besoin de déclarer la métrique avant.

Le protocole

Extraits du Metric ingestion protocol de la documentation Dynatrace : syntaxe metric.key,dimensions payload, exemple cpu.temperature, gauge avec min max sum count, count avec delta et ligne de métadonnées
  • Clé : sections séparées par des points, 3 à 255 caractères, lettres, chiffres, tirets et underscores ; pas de début par un chiffre ou un tiret. Le préfixe dt. est réservé.
  • Jusqu’à 50 dimensions clé="valeur" par ligne ; dt.entity.host=HOST-… rattache la mesure à un host.
  • Format gauge (valeur ou min/max/sum/count) ou count,delta=…. En métriques Classic (Managed), une clé de type count reçoit le suffixe .count ; les métriques Grail n’appliquent pas ce suffixe.
  • Horodatage optionnel en millisecondes UTC, accepté entre 1 heure dans le passé et 10 minutes dans le futur.
  • Charge utile text/plain limitée à 1 Mo.

Exemple

# Jeton avec le scope metrics.ingest (Managed : https://{votre-domaine}/e/{id-environnement})
curl -s -X POST "https://{votre-domaine}/e/{id-environnement}/api/v2/metrics/ingest" \
  -H "Authorization: Api-Token {token}" \
  -H "Content-Type: text/plain; charset=utf-8" \
  --data-binary $'#shop.orders.validated gauge dt.meta.displayName="Commandes validées"\nshop.orders.validated,channel="web",country="fr" 42'

La réponse 202 renvoie linesOk et linesInvalid ; un 400 signale des lignes invalides, les lignes valides étant tout de même acceptées. Lisez toujours ces compteurs dans vos scripts.

Sur un host équipé de OneAgent, le module EEC expose aussi http://localhost:14499/metrics/ingest (port par défaut), sans jeton : la dimension dt.entity.host est ajoutée automatiquement. C’est la solution la plus simple pour un cron local. En SaaS, la même API accepte un platform token ; l’exemple de la documentation indique le scope openpipeline:metrics:ingest.

Méthode 4 — OneAgent SDK : instrumenter d’abord

Le OneAgent SDK (Java, C/C++, Node.js, .NET, Python, PHP) sert à tracer ce que OneAgent ne voit pas seul : appels distants, requêtes de base de données, requêtes web, files et messages, exécution asynchrone, et capture de request attributes. Il ne crée pas de métrique directement. Le chemin est donc : instrumenter avec le SDK, capturer la valeur comme request attribute, puis créer une calculated service metric (méthode 1). Prérequis : OneAgent en mode full-stack sur le host et redémarrage de l’application après l’installation de OneAgent.

Comment vérifier que ça fonctionne

  1. Managed : ouvrez Data Explorer et cherchez la clé (calc:service.…, log.… ou shop.orders.validated). Une requête de contrôle :
    shop.orders.validated:splitBy("channel"):sum
  2. SaaS : dans un Notebook, interrogez la métrique en DQL :
    timeseries total = sum(shop.orders.validated), by:{channel}
  3. Ingestion : vérifiez linesInvalid = 0 dans la réponse de l’API.
  4. Log metric et calculated metric : générez un événement connu (une erreur de test) et vérifiez qu’il apparaît dans la minute suivante.

Une fois la métrique en place, transformez-la en alerte : voir créer une alerte Dynatrace pas à pas.

Bonnes pratiques

  • Dériver des données existantes avant d’ingérer en double.
  • Convention de nommage (équipe.domaine.mesure) et métadonnées dt.meta.displayName et dt.meta.description dès la première ligne.
  • Cardinalité maîtrisée : pas d’ID de commande, d’utilisateur ou d’URL complète en dimension.
  • Clés figées : un renommage casse l’historique, les dashboards et les alertes.
  • Jetons d’ingestion limités au scope metrics.ingest.

Questions fréquentes

Pourquoi ma métrique ingérée s’appelle-t-elle soudain « .count » ?

En métriques Classic, une ligne au format count ajoute automatiquement le suffixe .count à la clé. Interrogez ma.cle.count, ou envoyez des gauges si vous voulez garder la clé telle quelle.

Ma calculated service metric est vide pour le mois dernier. Est-ce normal ?

Oui. Elle ne s’alimente qu’avec les requêtes postérieures à sa création. Pour une analyse rétroactive, utilisez Multidimensional analysis sur les traces conservées.

Log metric ou ingestion par API pour un batch qui écrit des logs ?

Si les logs sont déjà ingérés, la log metric évite une seconde chaîne à maintenir. Si le batch peut appeler une API et que ses logs ne sont pas collectés, l’ingestion directe est plus fiable qu’un parsing de texte.

Conclusion

Créer une métrique custom Dynatrace, c’est surtout choisir la bonne source : traces pour les services, logs pour ce qui n’existe que dans les logs, API pour le reste, SDK pour combler un trou d’instrumentation. Une métrique bien nommée, à cardinalité maîtrisée, devient un SLI fiable, une alerte et une ligne de dashboard.

Références : Metric ingestion protocol et Calculated metrics for services (documentation Managed), Metric extraction in OpenPipeline (documentation SaaS).

span.observer est un blog indépendant, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les informations proviennent de la documentation publique ; vérifiez limites et options sur votre version avant toute mise 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
Alertes Dynatrace Slack et Microsoft Teams : Problem notifications, webhook et Workflows

Alertes Dynatrace Slack et Microsoft Teams : Problem notifications, webhook et Workflows

Next Post
Host groups Dynatrace : à quoi ils servent et comment les définir

Host groups Dynatrace : à quoi ils servent et comment les définir

Related Posts