DQL fieldsMove jsonExtract : manipuler des logs JSON sans écraser les champs existants

DQL fieldsMove jsonExtract : extrayez les clés d’un log JSON sans écraser un champ existant et rangez les champs k8s dans un enregistrement imbriqué.
DQL fieldsMove jsonExtract : manipuler des logs JSON sans écraser les champs existants

DQL fieldsMove jsonExtract : ces deux commandes, annoncées dans les notes de version SaaS du sprint 347 (16 septembre 2026), servent à remettre de l’ordre dans des logs JSON. jsonExtract transforme les clés d’un objet JSON en champs. fieldsMove range des champs de premier niveau dans un enregistrement imbriqué. Aucune des deux n’écrase un champ existant.

Le problème est classique en exploitation. Un log applicatif arrive avec un champ content qui contient du JSON, et ce JSON porte une clé loglevel alors que l’enregistrement a déjà un champ loglevel. Avec un parseur naïf, l’un des deux gagne en silence, et vos requêtes d’alerte lisent la mauvaise valeur. Ici, la collision est visible et vous choisissez où la ranger.

Cet article suit la référence DQL officielle (pages « DQL extraction and parsing commands » et « DQL selection and modification commands », lues le 27 octobre 2026) et les notes du sprint 347. Il vaut pour Dynatrace SaaS (Grail, DQL), pas pour Managed. Précision d’honnêteté : span.observer n’a exécuté aucune de ces requêtes. Les exemples tirés de la référence sont recopiés tels quels, et les résultats montrés sont ceux que la documentation indique.

DQL fieldsMove jsonExtract : ce que disent les notes du sprint 347

  • fieldsMove : déplace les champs de premier niveau qui correspondent à un motif include (moins ceux qui correspondent à exclude) dans un nouveau champ de type enregistrement imbriqué, et les retire du premier niveau. C’est le pendant de fieldsFlatten.
  • jsonExtract : analyse une chaîne JSON et place les clés du premier niveau de l’objet dans des champs de l’enregistrement. Les notes précisent qu’il n’écrase jamais un champ existant et qu’on peut regrouper les clés en collision dans un champ dédié.
  • Les deux commandes complètent la famille des commandes fields (fieldsKeep, fieldsRemove, fieldsRename). La même version introduit des fonctions pour manipuler les enregistrements (recordField, recordFields, recordFromFields, recordKeys, recordValues), que cet article ne détaille pas.

Syntaxe de fieldsMove

La syntaxe de la référence est la suivante :

fieldsMove fieldName [, include: {pattern [, ...]}] [, exclude: {pattern [, ...]}]

Au moins un des paramètres include ou exclude est obligatoire. Cette règle évite de déplacer tous les champs par mégarde. Le premier argument est le nom du nouveau champ qui recevra l’enregistrement.

Voici le premier exemple de la référence : tous les champs dont le nom commence par k8s. passent dans un champ k8s. Les champs event et status restent à la racine.

data record(
  event = "failed to find product",
  status = "NONE",
  k8s.namespace.name = "unguard",
  k8s.pod.name = "unguard-user-simulator-28334535-tqqxt",
  k8s.pod.uid = "d3e93267-e7f9-4a2d-b5df-dc2ac226a7ce"
)
| fieldsMove k8s, include: {"k8s.*"}
Requête DQL fieldsMove k8s avec include k8s.* sur un enregistrement de test, et résultat indiqué par la référence : event et status à la racine, trois champs k8s dans un enregistrement imbriqué
Source : docs.dynatrace.com

Le deuxième exemple de la référence ajoute exclude: {k8s.namespace.name} : le champ k8s.namespace.name reste à la racine, les deux autres entrent dans k8s. Cela sert quand un champ sert de filtre ou de dimension dans vos tableaux de bord et doit rester facile d’accès.

| fieldsMove k8s, include: {"k8s.*"}, exclude: {k8s.namespace.name}

Syntaxe de jsonExtract

jsonExtract input [, conflicts]
  • input (obligatoire) : une expression de type chaîne qui contient l’objet JSON.
  • conflicts (facultatif) : le nom du champ où ranger les clés en collision. Sans ce paramètre, les clés en collision sont écartées et aucun champ supplémentaire n’est créé.

Avec conflicts, le champ contient un enregistrement vide quand il n’y a aucune collision. Si l’objet JSON répète une clé, une seule valeur est conservée, sans garantie sur laquelle.

Les types suivent le JSON : nombre vers long ou double, booléen vers boolean, chaîne vers string, null vers null, tableau vers array, objet vers record.

Étapes pratiques : extraire du JSON sans rien perdre

Étape 1 — Voir la collision de clés

L’exemple de la référence utilise un enregistrement qui a déjà loglevel = "WARN", alors que le JSON de content contient "loglevel":"ERROR" :

data record(timestamp = now(),
            content = """{"loggerName":"Log4JGenerator", "threadId":33, "loglevel":"ERROR"}""",
            loglevel = "WARN",
            log.source = "/var/log/messages")
| jsonExtract content, conflicts: collisions
Requête DQL jsonExtract content avec conflicts collisions, et résultat indiqué par la référence : loglevel reste WARN, loggerName et threadId deviennent des champs, collisions contient loglevel ERROR
Source : docs.dynatrace.com

Le résultat décrit par la référence : loglevel garde la valeur WARN, loggerName et threadId apparaissent comme champs, et collisions contient loglevel: ERROR. La valeur d’origine est intacte et la valeur du JSON reste consultable.

Étape 2 — Appliquer jsonExtract à des logs réels

Dans Grail, tous les champs du flux doivent être connus à la planification de la requête. Les logs n’ont pas de schéma fixe : la référence insère donc fields avant jsonExtract. Voici son exemple :

fetch logs
| filter startsWith(content, "{")
| fields timestamp, content
| jsonExtract content

Le filtre garde les lignes dont le contenu commence par une accolade. fields liste ce qu’on retient, puis jsonExtract ajoute les clés du JSON.

Étape 3 — Ranger les champs Kubernetes

Autre exemple de la référence, sur des logs :

fetch logs
| fieldsMove k8s, include: {"k8s.*"}
Deux requêtes DQL de la référence sur des logs : jsonExtract content après un filter startsWith, et fieldsMove k8s avec include k8s.*
Source : docs.dynatrace.com

Le premier niveau reste lisible, et les attributs Kubernetes se retrouvent dans un enregistrement k8s.

Étape 4 — Enchaîner les deux commandes

Exemple écrit pour illustrer, non exécuté par span.observer. Il combine les commandes ci-dessus ; la syntaxe de chaque commande vient de la référence, l’enchaînement est le nôtre et reste à valider dans votre environnement :

fetch logs
| filter startsWith(content, "{")
| fields timestamp, content, k8s.namespace.name, k8s.pod.name
| jsonExtract content, conflicts: collisions
| fieldsMove k8s, include: {"k8s.*"}

Après fields, le flux ne contient que les champs listés. Si une clé du JSON porte le nom d’un champ retenu, la valeur du JSON atterrit dans collisions.

Comment vérifier que ça fonctionne

  1. Lancez d’abord les exemples data record(...) : ils ne dépendent d’aucune donnée de votre environnement. Comparez avec les résultats de la référence.
  2. Sur des logs, ouvrez le champ collisions : un enregistrement vide veut dire aucune collision.
  3. Vérifiez les types : un nombre du JSON doit être numérique, pas une chaîne.
  4. Relisez la page de référence de jsonExtract avant de l’utiliser dans une requête de production : la disponibilité d’une commande peut varier selon le contexte (requête DQL ou processeur DQL d’OpenPipeline).

Bonnes pratiques

  • Réservez toujours un champ conflicts en phase de découverte : une collision ignorée est une donnée perdue.
  • Filtrez d’abord (startsWith(content, "{")) pour ne pas analyser les lignes qui ne sont pas du JSON.
  • Gardez à la racine les champs que vos filtres et vos SLO utilisent, avec exclude.
  • Côté fiabilité, une alerte qui lit le mauvais loglevel rallonge le MTTR : traitez les collisions comme un signal.

Pour prolonger, voir https://span.observer/fr/dql-avance-lookup-join-parse/ (parse, lookup, join), https://span.observer/fr/commandes-dql-filter-summarize-timeseries/ pour les commandes de base, https://span.observer/fr/dql-smartscape-topologie/ pour la topologie et https://span.observer/fr/analyse-patterns-logs/ pour l’analyse de logs.

Liens internes : DQL avancé, commandes DQL, DQL Smartscape, analyse de patterns dans les logs.

Questions fréquentes

jsonExtract écrase-t-il un champ existant ?

Non. D’après la référence, les champs existants ne sont jamais supprimés ni écrasés. Les clés en collision sont écartées, ou rangées dans le champ nommé par conflicts.

Peut-on lancer fieldsMove sans include ni exclude ?

Non. Au moins un des deux paramètres est requis, pour éviter de déplacer tous les champs par erreur.

Quel est le lien avec fieldsFlatten ?

fieldsMove regroupe des champs dans un enregistrement imbriqué ; fieldsFlatten fait l’inverse en remontant les champs imbriqués à la racine, selon la référence.

Conclusion

fieldsMove et jsonExtract rendent les logs JSON plus lisibles sans perdre de données. Testez d’abord les exemples data record, puis adaptez à vos logs.

Sources : notes de version SaaS du sprint 347 et référence DQL, extraction et parsing.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les fonctionnalités SaaS évoluent vite : vérifiez leur disponibilité dans votre environnement et dans la documentation officielle.

Total
0
Shares
Laisser un commentaire

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

Previous Post
Service backtrace Dynatrace : enquêter plus vite avec traces en superposition et chaînes d'appels Smartscape

Service backtrace Dynatrace : enquêter plus vite avec traces en superposition et chaînes d’appels Smartscape

Next Post
Import STIX/TAXII et Recorded Future dans Dynatrace : rapports de menace et IoC

Import STIX/TAXII et Recorded Future dans Dynatrace : rapports de menace et IoC

Related Posts