Enrichissement d'étendue

A propos de l'enrichissement d'étendue

Permettre aux utilisateurs d'enrichir les étendues avec des attributs personnalisés ou de modifier, de combiner ou de supprimer des données d'attributs existants.
Les opérations d'enrichissement sont définies au moyen de règles d'étendue qui contiennent une ou plusieurs actions à appliquer dans un ordre particulier sur une étendue donnée.
Il existe deux types de règle d'étendue : personnalisée et fournie par Oracle.
L'enrichissement d'étendue est configuré au niveau du domaine APM.

Exemples d'enrichissement d'étendue :

Suppression des informations personnelles identifiables (PII) des étendues.
Combinez les données issues de plusieurs attributs en un seul.
Extraire des données à partir d'un attribut. Par exemple, un chemin partiel à partir d'une URL plus longue.
Appliquer des fonctions mathématiques aux données. Par exemple, convertissez une unité de secondes en millisecondes.
Mapper une valeur d'attribut avec une nouvelle valeur. Par exemple, mappez la valeur '1' avec la couleur 'bleu', la valeur '2' avec la couleur 'rouge'.
Répartir des valeurs numériques dans des buckets. Par exemple, une plage de valeurs de température mappée dans des compartiments "froid", "chaud" et "chaud".

Sujets :

Utilisation de l'enrichissement d'étendue

L'enrichissement d'étendue est configuré via des règles d'étendue qui fonctionnent sur une étendue et sont utilisées pour modifier les attributs de l'étendue. La boîte à outils Règles d'étendue fournit diverses actions qui peuvent être exécutées dans le cadre d'une règle.

Les règles d'étendue sont gérées au sein des groupes. Un groupe est un ensemble de règles appliquées dans un ordre spécifié. Chaque règle peut appliquer une ou plusieurs actions sur une étendue et la sortie de chaque règle peut être utilisée comme entrée pour les règles de suivi. Les groupes de règles nécessitent un filtre d'étendue utilisé pour sélectionner les étendues sur lesquelles appliquer les règles.

Vous pouvez définir plusieurs groupes. Cela est utile lorsque vous devez tenir à jour différents types de règle pour différents types d'étendue, car il crée des entités logiques avec des fonctionnalités conçues à des fins spécifiques. Cela réduit la complexité globale de votre jeu de règles.

Si des filtres d'étendue sont configurés pour plusieurs groupes qui correspondent à la même étendue, tous appliquent leurs règles à cette étendue. L'ordre d'exécution est déterminé par l'ordre alphabétique des noms de groupe. Gardez cela à l'esprit lorsque vous nommez ou renommez vos groupes. Oracle recommande de préfixer les noms par un nombre pour éviter que les noms de groupe ne soient triés par ordre alphabétique. Par exemple, "1. Remove Location Data", "2. Convertir les unités de longueur".

Gardez à l'esprit que lorsque plusieurs groupes fonctionnent sur la même étendue, cela signifie que chaque groupe fonctionne sur une version de l'étendue qui peut avoir été modifiée par un groupe précédent de la chaîne. Cela peut être utile, car vous pouvez écrire des règles dans des groupes de suivi qui dépendent des modifications créées par des groupes précédents. En revanche, elle peut également entraîner l'échec des règles de suivi si un attribut sur lequel repose une règle est supprimé ou modifié par un groupe précédent.

Remarque

L'élément ci-dessus n'est important que lorsqu'une étendue correspond à plusieurs groupes.

Si vos groupes ont des filtres clairement disjoints, une étendue sera toujours modifiée par un seul groupe et les considérations ci-dessus ne seront plus pertinentes.

Attributs dans les événements d'étendue

Les étendues peuvent contenir une liste d'événements également appelés messages de journal. Ils sont généralement utilisés pour stocker des informations sur les moments importants pendant l'exécution de l'étendue. Par exemple, si une étendue décrit une requête de base de données, des événements peuvent être générés pour marquer le moment où la connexion a été ouverte, le moment où la demande de requête a été réellement soumise et le moment où la réponse a été reçue.

Un événement est identifié par name, timestamp et un ensemble de attributes (paires clé-valeur) qui fournissent un contexte supplémentaire pour les informations enregistrées.

Toutes les actions de règle d'étendue décrites ci-dessous, qui nécessitent un attribut en tant qu'entrée ou sortie, peuvent également être appliquées aux attributs d'événements individuels. Etant donné que les attributs d'événement sont indépendants des attributs d'étendue standard, vous devez utiliser la syntaxe event reference suivante pour identifier l'attribut d'événement approprié :

event['NameOfEvent']:'NameOfAttribute'.

Remarque

Les attributs d'événement ne peuvent pas être utilisés comme filtres d'étendue.

Créer et gérer des règles d'étendue

Vous pouvez créer et gérer des règles d'étendue en fonction de vos besoins en matière de génération de rapports.

Pour créer des règles d'étendue pour un domaine APM donné, procédez comme suit :

Accédez à la page Domaines APM et cliquez sur le domaine APM souhaité.

La page Détails du domaine est affichée.
Accédez à Ressources, en bas à gauche, puis cliquez sur Enrichissement d'étendue.

Le panneau Enrichissement d'étendue s'affiche.
Cliquez sur Créer un groupe pour créer un groupe de règles d'étendue.
Le panneau Créer un groupe de règles d'étendue apparaît.
- Entrez le nom du nouveau groupe.
- Sélectionnez un filtre d'étendue à utiliser avec ce groupe.
- Indiquez éventuellement une description pour le nouveau groupe.
- Cliquez sur Suivant pour passer au volet Actions de règle afin de commencer à ajouter des règles d'étendue au nouveau groupe en fonction du type de règle d'étendue : Règle d'étendue personnalisée ou Règle d'étendue fournie par Oracle.
- Entrez le nom de la règle.
- Sélectionnez éventuellement un filtre d'étendue de règle pour affiner davantage l'étendue de l'opération de la règle.
  
  Remarque
  
  Les filtres d'étendue sont créés séparément. Pour plus d'informations, reportez-vous à Filtres d'étendue.
- (Facultatif) Fournissez la description de la règle.
- Sélectionnez un type de règle d'étendue.
  - Si vous sélectionnez Règle d'étendue fournie par Oracle, une liste de règles vous est proposée.
    
    Les règles ont déjà été créées par Oracle pour aider les utilisateurs. La liste comprend les éléments suivants :
    Ajoute l'adresse IP du client à une étendue.
    Il ajoute l'adresse IP client à une étendue en tant qu'attribut nommé ClientIP.
    
    Suite EBS.
    Il fournit le modèle E-Business Suite.
    
    Conversion de noms OpenTelemetry en APM.
    Il convertit les noms d'attribut d'étendue de la convention de dénomination OpenTelemetry en convention de dénomination APM. Pour plus d'informations sur l'utilisation de OpenTelemetry avec APM, reportez-vous à Configuration de sources de données OpenTelemetry.
    Cliquez sur une règle dans la liste pour l'ajouter au groupe.
    
    Remarque
    
    Vous ne pouvez configurer aucune action car elle est gérée en interne par la règle elle-même. De plus, vous ne pouvez pas voir quelles sont les actions pour une règle fournie par Oracle.
  - Si vous choisissez de créer une règle d'étendue personnalisée, vous devez définir des actions pour cette règle. (Une règle contient toujours au moins une action).
    Pour pouvoir choisir une action, vous devez sélectionner une cible d'action et un type d'action.
    
    La cible d'action indique la partie de l'étendue sur laquelle l'action fonctionne. Deux cibles sont disponibles :
    
    Entité : ciblez l'étendue entière.
    
    Attribut : ciblez un seul attribut.
    
    Le type d'action indique le type. Il est principalement utilisé pour regrouper les actions de manière logique. Par exemple, chaîne ou numérique.
    
    Sélectionnez maintenant l'action appropriée dans la liste déroulante Actions disponibles.
    Etant donné que les actions ont différents contextes, la fenêtre change en fonction de chaque type d'action. Pour plus d'informations sur les actions, reportez-vous à Utilisation des actions.
    Pour plus d'informations sur les actions disponibles pour Cible d'action et Type d'action, reportez-vous à Actions disponibles.
    Utilisez le bouton Ajouter une action pour ajouter d'autres actions à la règle.
    
    Utilisez le menu d'élément d'action en haut à droite de chaque action pour le déplacer vers le haut ou vers le bas dans l'ordre des règles ou pour supprimer une action.

Utilisation

Les actions dont la cible est Attribut nécessitent toujours que vous indiquiez le nom de l'attribut dont la valeur sera utilisée comme entrée pour l'action. La fenêtre de configuration de chaque action le désigne par Input Attribute.

Certaines actions nécessitent également de fournir le nom d'un attribut dans lequel stocker le résultat de l'opération. C'est ce que l'on appelle Output Attribute. Si l'attribut existe sur l'étendue, toute valeur qu'il a à ce moment-là sera écrasée par le résultat de l'action. S'il n'existe pas encore, il est ajouté à l'étendue avec la nouvelle valeur. Vous pouvez utiliser ce mécanisme pour remplacer la valeur de n'importe quel attribut sur l'étendue (même l'attribut d'entrée) par le résultat de l'opération de l'action.

Vous pouvez ainsi alimenter les résultats d'une action de suivi (ou même d'une règle au sein du même groupe de règles).

Vous pouvez également l'utiliser pour stocker des valeurs dans des attributs temporaires qui peuvent être utilisés par des règles de suivi ou des actions, mais sans avoir à les conserver dans le résultat final. Veillez simplement à supprimer les attributs temporaires en tant que dernière étape à l'aide de l'action Enlever un attribut.

Remarque

Une action Bloquer rejette l'étendue et vous ne pouvez pas l'utiliser ultérieurement, même à partir d'un autre groupe de règles.

Actions disponibles

Cible	Type	Actions disponibles
Entité	Transfert Actions qui contrôlent si l'étendue dans son intégralité est transmise ou bloquée. Les étendues bloquées sont rejetées du pipeline de traitement. Les étendues rejetées ne seront plus traitées par APM, ne seront stockées nulle part et ne seront plus disponibles pour consultation ultérieure dans d'autres outils ou tableaux de bord APM.	Bloc : bloque cette plage de manière inconditionnelle. Les actions et les règles de suivi ne seront pas appliquées et l'étendue ne sera plus disponible dans les outils et produits APM OCI. Exemple : les échantillons (acceptés) s'étendent en fonction d'un pourcentage d'échantillon. Par exemple, un pourcentage d'échantillon de 25 % acceptera (aléatoirement) 25 % de toutes les étendues et bloquera le reste. Les étendues bloquées ici sont traitées de la même manière que les étendues bloquées par l'action Bloquer.
Attribut	Chaîne Actions permettant différentes opérations sur la valeur de l'attribut, qui est une chaîne. Par exemple, en modifiant la casse, en remplaçant une valeur ou en extrayant une partie de la chaîne.	Ajouter : ajoute une chaîne statique à la valeur d'un attribut à l'aide d'une chaîne de séparation facultative. Concaténer : concatène deux valeurs d'attribut. Une chaîne de séparation facultative peut être fournie sur laquelle les valeurs seront jointes. Le résultat est renvoyé en tant que nouvel attribut. Extraire : extrait une partie de la valeur d'un attribut en fonction d'une expression régulière. Le résultat est renvoyé en tant que nouvel attribut. L'expression régulière doit contenir un opérateur de groupe de capture qui identifie la partie de la chaîne à capturer. Si l'expression régulière ne correspond pas ou s'il n'existe aucun groupe de capture, l'action ne génère aucune sortie. Vous pouvez éventuellement fournir une valeur de secours qui sera utilisée comme sortie de l'action si l'extraction elle-même n'a produit aucun résultat. Minuscules : Convertit la valeur d'un attribut en minuscules. Rechercher et remplacer : remplace une ou plusieurs parties de la valeur d'un attribut à l'aide d'une expression régulière. La chaîne modifiée est renvoyée en tant que nouvel attribut. L'expression régulière peut contenir un groupe de capture. Sans groupe de capture, le contenu complet des correspondances de l'expression sera remplacé. Lorsqu'un groupe de capture est présent, seul le contenu capturé par le groupe est remplacé. L'occurrence de correspondance facultative peut être utilisée si seule une occurrence spécifique d'une correspondance doit être remplacée. Si ce paramètre n'est pas défini ou défini sur 0, toutes les occurrences correspondantes seront remplacées. Il s'agit du comportement par défaut. Trim : trie les espaces de début et de fin de la valeur d'un attribut. Majuscules : convertit la valeur d'un attribut en majuscules.
Attribut	Numérique Actions permettant différentes opérations mathématiques sur les valeurs d'attribut (à condition qu'elles soient des nombres). Les actions numériques prennent en charge les nombres réels et les nombres représentés sous forme de chaînes dans la valeur d'attribut, c'est-à-dire que les deux sont équivalents : "montant" : 2,5 "montant" : "2,5" Les actions numériques peuvent prendre comme entrée une chaîne représentant le nom d'un attribut dont la valeur doit être utilisée dans l'opération ou un nombre qui sera utilisé directement dans le calcul. Toutes les actions numériques ont une option dans laquelle vous pouvez appliquer l'arrondi à la valeur de sortie. L'arrondi peut être : Arrondi : arrondit le nombre par excès ou par défaut au nombre entier le plus proche. Plancher : arrondit le nombre au nombre entier inférieur le plus proche. Ceil : arrondit le nombre au nombre entier le plus proche. Aucun arrondi : option par défaut.	Absolue : renvoie la valeur absolue de la valeur en entrée. Ajouter : somme deux valeurs. Bucketize : mappe une valeur d'attribut numérique dans des noms de bucket. Si la valeur d'attribut est comprise dans la plage d'un bucket, le nom du bucket est renvoyé. Si aucun bucket ne correspond, une valeur de secours est renvoyée. Diviser : divise la première par la deuxième valeur. Si la deuxième valeur est 0, le résultat sera 0. Maximum : renvoie le maximum des deux valeurs. Minimum : renvoie le minimum des deux valeurs. Multiplier : multiplie les deux valeurs. Néger : négocie (modifie le signe) de la valeur. Soustraire : soustrait le deuxième du premier attribut.
Attribut	Générique Les actions génériques fournissent des opérations de niveau attribut, telles que la suppression d'un attribut de l'étendue.	Mettre en correspondance une valeur d'attribut : prend la valeur d'un attribut et la met en correspondance avec une nouvelle valeur. Enlever l'attribut : enlève l'attribut de l'étendue. Si l'attribut est une référence de nom d'événement, `event['EventName']`, l'ensemble de l'événement d'étendue sera enlevé. Renommer l'attribut : renomme l'attribut. Définir un attribut : définit un attribut sur une valeur statique. Si l'attribut n'existe pas, il est ajouté, sinon la nouvelle valeur lui est affectée, remplaçant la valeur existante.

Exemples de configuration d'action

Cette section fournit des exemples des étapes de configuration requises pour certaines actions individuelles.

Exemple de Bucketize :
Cette action utilise un mini-éditeur pour configurer un certain nombre de buckets et leurs valeurs de seuil. Vous pouvez utiliser le contrôle de droite pour créer, mettre à jour et enlever des buckets.

Les buckets sont ordonnés automatiquement en fonction de leurs valeurs de seuil. Une valeur de secours est utilisée lorsqu'une valeur est trop grande pour le dernier bucket. L'image suivante présente un exemple avec cinq buckets et une valeur de secours :
Exemple de carte :
Cette action utilise un mini-éditeur pour configurer la carte des paires de valeurs d'entrée/sortie. Les deux valeurs peuvent être des nombres ou des chaînes. Utilisez le contrôle de droite pour créer, mettre à jour et/ou supprimer un mappage.
Le bouton Exporter vous permet de télécharger tous les mappages vers un fichier (au format CSV) vers votre ordinateur.
Le bouton Importer vous permet de remplir les mappages à partir d'un fichier CSV sur votre ordinateur. Cela est particulièrement utile si vous disposez d'un grand nombre de mappages.

Validation des règles d'enrichissement d'étendue

Les configurations d'enrichissement d'étendue peuvent être complexes à écrire et il peut parfois être difficile de savoir à l'avance si une règle ou un groupe de règles fonctionnera comme prévu. Pour vous aider, l'éditeur de configuration d'enrichissement d'étendue fournit une option permettant de tester une règle ou un groupe de règles sur un échantillon d'étendue avant de l'enregistrer.

Pour utiliser l'option de test, procédez comme suit :

Sélectionnez un groupe, puis cliquez sur Modifier pour ouvrir le panneau Modifier un groupe de règles d'étendue. Vous pouvez également créer un groupe et afficher le panneau Modifier.
Cliquez sur l'étape Configure rule actions.
Cliquez sur Tester pour tester l'ensemble du groupe de règles. Pour tester une règle individuelle, vous pouvez également la sélectionner et cliquer sur Tester la règle.
Remarque

Tester la règle n'est pas disponible lorsque le groupe de règles ne contient qu'une seule règle.
Le panneau Tester le groupe de règles d'étendue apparaît.
Les règles à tester s'affichent avec une case à cocher en regard. Vous pouvez les basculer comme vous le souhaitez.
Entrez un exemple d'étendue dans la zone de texte Exemple d'étendue.
Cliquez sur Tester l'étendue pour effectuer un test des règles sélectionnées sur l'étendue donnée.

Figure 9-1 Validation de la règle d'enrichissement d'étendue

Validation de règle d'enrichissement d'étendue

L'exécution du test indique si l'étendue correspond ou non aux filtres d'étendue configurés.

Si les filtres correspondent, les règles seront appliquées à l'étendue et les différences résultantes (le cas échéant) seront affichées dans le tableau ci-dessous. Tous les attributs ajoutés à la suite de la règle seront mis en surbrillance en vert. Les attributs supprimés seront mis en surbrillance en rouge. Les attributs modifiés seront mis en surbrillance en jaune.

Explorateur de traces : pour obtenir des exemples précis d'étendues de votre trafic, cliquez sur Explorateur de traces en haut à droite pour ouvrir l'explorateur de traces et voir les étendues réelles qui ont été traitées. Vous pouvez sélectionner une étendue, ouvrir le menu contextuel à droite (les trois points verticaux) et cliquer sur Copier les données de l'étendue racine.

Une fenêtre contextuelle s'affiche avec le contenu de l'étendue. Vous pouvez copier les données d'étendue et les utiliser lors du test.

Une autre option consiste à coller vos propres étendues ou à les saisir manuellement, à condition qu'elles soient conformes au format d'étendue indiqué par l'explorateur de traces.

Etendue des alias de propriété

Remarque

Peu de propriétés d'étendue réelles sont référencées par un nom différent lorsqu'elles sont utilisées dans les fonctionnalités d'enrichissement d'étendue ou de filtres d'étendue. En dehors de la différence visuelle, cela n'a aucune incidence sur la configuration de vos règles et filtres. Par exemple, vous devez toujours utiliser l'alias lorsque vous faites référence à la propriété donnée.

Voici les propriétés qui ont actuellement un alias :

Propriété d'étendue	Alias d'enrichissement d'étendue	Remarque
`td-micros`	`SpanDuration`	`td-micros` est en microsecondes, tandis que `SpanDuration` est en millisecondes. La conversion d'unité de temps est appliquée automatiquement par les filtres d'enrichissement d'étendue et d'étendue.
`name`	`OperationName`	Le nom de l'étendue représente l'opération effectuée
`ts-micros`	`StartTime`	`ts-micros` est en microsecondes, tandis que `StartTime` est en millisecondes. La conversion d'unité de temps est appliquée automatiquement par les filtres d'enrichissement d'étendue et d'étendue.
`id`	`SpanId`
`parent-id`	`ParentId`
`trace-id`	`TraceId`

Documentation Oracle Cloud Infrastructure

Enrichissement d'étendue