Tutoriel : Ajout d’une transformation dans la règle de collecte de données d’espace de travail à Azure Monitor à l’aide de modèles Resource Manager

Ce tutoriel vous guide tout au long de la configuration d’un exemple de transformation dans une règle de collecte de données d’espace de travail à l’aide de modèles Resource Manager. Les transformations dans Azure Monitor vous permettent de filtrer ou de modifier des données entrantes avant qu’elles ne soient envoyées à leurs destinations. Les transformations d’espace de travail prennent en charge les transformations au moment de l’ingestion pour les flux de travail qui n’utilisent pas encore le pipeline d’ingestion de données Azure Monitor.

Les transformations d’espace de travail sont stockées ensemble dans une seule règle de collecte de données (DCR) pour l’espace de travail, appelée DCR de l’espace de travail. Chaque transformation est associée à une table particulière. La transformation est appliquée à toutes les données envoyées à cette table à partir d’un flux de travail qui n’utilise pas de DCR.

Notes

Ce tutoriel utilise des modèles Resource Manager et l’API REST pour configurer une transformation d’espace de travail. Pour accéder au même tutoriel avec le Portail Azure, consultez Tutoriel : Ajout d’une transformation dans la règle de collecte de données d’espace de travail à Azure Monitor à l’aide du Portail Azure.

Ce didacticiel vous apprend à effectuer les opérations suivantes :

• Configurer la transformation de l’espace de travail pour une table dans un espace de travail Log Analytics.
• Écrire une requête de journal pour une transformation de la durée d’ingestion.

Notes

Ce tutoriel utilise PowerShell depuis Azure Cloud Shell pour passer des appels d’API REST à l’aide de l’API Tables d’Azure Monitor et du portail Azure afin d’installer des modèles Resource Manager. Vous pouvez utiliser n’importe quelle autre méthode pour effectuer ces appels.

Prérequis

Pour suivre ce tutoriel, vous devez avoir de ce qui suit :

• Un espace de travail Log Analytics dans lequel vous avez au moins des droits de contributeur.
• Autorisations de créer des objets de règle de collecte de données dans l’espace de travail.
• La table doit déjà avoir des données.
• La table ne peut pas être déjà liée au DCR de transformation de l’espace de travail.

Vue d’ensemble du didacticiel

Dans ce didacticiel, vous allez réduire les besoins de stockage de la table LAQueryLogs en filtrant certains enregistrements. Vous supprimerez également le contenu d’une colonne lors de l’analyse des données de la colonne pour stocker une partie des données dans une colonne personnalisée. La table LAQueryLogs est créée lorsque vous activez l’audit de requête de journal dans un espace de travail, mais il est utilisé uniquement comme exemple pour le didacticiel. Vous pouvez utiliser ce même processus de base pour créer une transformation pour toute table prise en charge dans un espace de travail Log Analytics.

Activer les journaux d’audit des requêtes

Vous devez activer l’audit des requêtes pour votre espace de travail afin de créer la table LAQueryLogs avec laquelle vous allez travailler. Cela n’est pas obligatoire pour toutes les transformations de la durée d’ingestion. Il s’agit simplement de générer les exemples de données que cet exemple de transformation utilisera.

1. Dans le menu Espaces de travail Log Analytics du Portail Azure, sélectionnez Paramètres de diagnostic , puis Ajouter un paramètre de diagnostic.

   

2. Fournissez un nom pour le paramètre de diagnostic et sélectionnez l’espace de travail afin que les données d’audit soient stockées dans le même espace de travail. Sélectionnez la catégorie Audit, puis cliquez sur Enregistrer pour enregistrer le paramètre de diagnostic et fermer la page Paramètres de diagnostic.

   

3. Sélectionnez Journaux, puis exécutez des requêtes pour remplir LAQueryLogs avec des données. Ces requêtes n’ont pas besoin de retourner réellement des données.

   

Mettre à jour un schéma de table

Avant de pouvoir créer la transformation, les deux modifications suivantes doivent être apportées à la table :

• La table doit être activée pour la transformation de l’espace de travail. Cette opération est requise pour toute table qui aura une transformation, même si la transformation ne modifie pas le schéma de la table.
• Toutes les colonnes supplémentaires alimentées par la transformation doivent être ajoutées à la table.

Utilisez l’API Tables - Update pour configurer la table avec le code PowerShell ci-dessous. L’appel d’API active la table pour les transformations de l’espace de travail, que les colonnes personnalisées soient ou non définies. Dans cet exemple, il comprend une colonne personnalisée nommée Resources_CF qui sera remplie avec la requête de transformation.

Important

Toutes les colonnes personnalisées ajoutées à une table intégrée doivent se terminer par _CF. Les colonnes ajoutées à une table personnalisée (une table avec un nom qui se termine par _CL) n’ont pas besoin d’avoir ce suffixe.

1. Cliquez sur le bouton Cloud Shell dans le Portail Azure et vérifiez que l’environnement est défini sur PowerShell.

   

2. Copiez le code PowerShell suivant et remplacez le paramètre Path par les détails de votre espace de travail.

   $tableParams = @'
   {
       "properties": {
           "schema": {
               "name": "LAQueryLogs",
               "columns": [
                   {
                       "name": "Resources_CF",
                       "description": "The list of resources, this query ran against",
                       "type": "string",
                       "isDefaultDisplay": true,
                       "isHidden": false
                   }
               ]
           }
       }
   }
   '@
   
   Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/LAQueryLogs?api-version=2021-12-01-preview" -Method PUT -payload $tableParams
   

3. Collez le code dans l’invite Cloud Shell pour l’exécuter.

   

4. Vous pouvez vérifier que la colonne a été ajoutée en accédant au menu Espace de travail Log Analytics dans le Portail Azure. Sélectionnez Journaux pour ouvrir Log Analytics puis développez la table LAQueryLogs pour afficher ses colonnes.

   

Définir la requête de transformation

Utilisez Log Analytics pour tester la requête de transformation avant de l’ajouter à une règle de collecte de données.

1. Ouvrez votre espace de travail dans le menu Espaces de travail Log Analytics du Portail Azure et sélectionnez Journaux pour ouvrir Log Analytics.

2. Exécutez la requête suivante pour afficher le contenu de la table LAQueryLogs. Notez le contenu de la colonne RequestContext. La transformation récupère le nom de l’espace de travail à partir de cette colonne et supprime le reste des données qu’il contient.

   LAQueryLogs
   | take 10
   

   

3. Modifiez la requête comme suit :

   LAQueryLogs
   | where QueryText !contains 'LAQueryLogs'
   | extend Context = parse_json(RequestContext)
   | extend Workspace_CF = tostring(Context['workspaces'][0])
   | project-away RequestContext, Context
   

   Ceci apporte les modifications suivantes :

   • Suppression des lignes liées à l’interrogation de la table LAQueryLogs proprement dite pour gagner de l’espace, car ces entrées de journal ne sont pas utiles.
   • Ajout d’une colonne pour le nom de l’espace de travail interrogé.
   • Supprimez les données de la colonne RequestContext pour économiser de l’espace.

   

4. Apportez les modifications suivantes à la requête pour l’utiliser dans la transformation :

   • Au lieu de spécifier un nom de table (LAQueryLogs dans ce cas) comme source de données pour cette requête, utilisez le mot clé source. Il s’agit d’une table virtuelle qui représente toujours les données entrantes dans une requête de transformation.
   • Supprimez tous les opérateurs qui ne sont pas pris en charge par les requêtes de transformation. Consultez les fonctionnalités KQL prises en charge pour obtenir la liste détaillée des opérateurs pris en charge.
   • Aplatissez la requête sur une seule ligne afin qu’elle puisse tenir dans le fichier JSON DCR.

   Voici la requête que vous allez utiliser dans la transformation après ces modifications :

   source | where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''
   

Créer une règle de collecte de données

Dans la mesure où il s’agit de la première transformation de l’espace de travail, vous devez créer une DCR de transformation de l’espace de travail. Si vous créez des transformations de l’espace de travail pour d’autres tables dans le même espace de travail, elles doivent être stockées dans cette même DCR.

1. Dans le menu du Portail Azure, dans la zone de recherche, tapez modèle, puis sélectionnez Déployer un modèle personnalisé.

   

2. Cliquez sur Créer votre propre modèle dans l’éditeur.

   

3. Collez le modèle Resource Manager ci-dessous, dans l’éditeur, puis cliquez sur Enregistrer. Ce modèle définit la DCR et contient la requête de transformation. Vous n’avez pas besoin de modifier ce modèle, car il collecte des valeurs pour ses paramètres.

   

   {
       "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
       "contentVersion": "1.0.0.0",
       "parameters": {
           "dataCollectionRuleName": {
               "type": "string",
               "metadata": {
                   "description": "Specifies the name of the Data Collection Rule to create."
               }
           },
           "location": {
               "type": "string",
               "defaultValue": "westus2",
               "allowedValues": [
                   "westus2",
                   "eastus2",
                   "eastus2euap"
               ],
               "metadata": {
                   "description": "Specifies the location in which to create the Data Collection Rule."
               }
           },
           "workspaceResourceId": {
               "type": "string",
               "metadata": {
                   "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
               }
           }
       },
       "resources": [
           {
               "type": "Microsoft.Insights/dataCollectionRules",
               "name": "[parameters('dataCollectionRuleName')]",
               "location": "[parameters('location')]",
               "apiVersion": "2021-09-01-preview",
               "kind": "WorkspaceTransforms",
               "properties": {
                   "destinations": {
                       "logAnalytics": [
                           {
                               "workspaceResourceId": "[parameters('workspaceResourceId')]",
                               "name": "clv2ws1"
                           }
                       ]
                   },
                   "dataFlows": [
                       {
                           "streams": [
                               "Microsoft-Table-LAQueryLogs"
                           ],
                           "destinations": [
                               "clv2ws1"
                           ],
                           "transformKql": "source |where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''"
                       }
                   ]
               }
           }
       ],
       "outputs": {
           "dataCollectionRuleId": {
               "type": "string",
               "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
           }
       }
   }
   

4. Dans l’écran Déploiement personnalisé, spécifiez un Abonnement et un Groupe de ressources pour stocker la règle de collecte de données, puis occupez-vous des valeurs définies dans le modèle. Cela inclut un Nom pour la règle de collecte de données et l'ID de la ressource d’espace de travail que vous avez collecté au cours d’une étape précédente. L'Emplacement doit être le même que celui de l’espace de travail. La Région est déjà remplie et est utilisée pour l’emplacement de la règle de collecte de données.

   

5. Cliquez sur Examiner et créer, puis sur Créer lorsque vous examinez les détails.

6. Une fois le déploiement terminé, développez la zone Détails du déploiement et cliquez sur votre règle de collecte de données pour en afficher les détails. Cliquez sur Affichage JSON.

   

7. Copiez l'ID de ressource pour la règle de collecte des données. Vous l’utiliserez à l’étape suivante.

   

Lier un espace de travail au DCR

La dernière étape pour activer la transformation consiste à lier la DCR à l’espace de travail.

Important

Un espace de travail ne peut être connecté qu’à une seule DCR et la DCR liée doit contenir cet espace de travail en tant que destination.

Utilisez l’API Workspaces-Update pour configurer la table avec le code PowerShell ci-dessous.

1. Cliquez sur le bouton Cloud Shell pour rouvrir Cloud Shell. Copiez le code PowerShell suivant et remplacez les paramètres par des valeurs pour votre espace de travail et votre DCR.

   $defaultDcrParams = @'
   {
       "properties": {
           "defaultDataCollectionRuleResourceId": "/subscriptions/{subscription}/resourceGroups/{resourcegroup}/providers/Microsoft.Insights/dataCollectionRules/{DCR}"
       }
   }
   '@
   
   Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}?api-version=2021-12-01-preview" -Method PATCH -payload $defaultDcrParams
   

2. Collez le code dans l’invite Cloud Shell pour l’exécuter.

   

Transformation de test

Laissez environ 30 minutes pour que la transformation prenne effet et vous pouvez la tester en exécutant une requête sur la table. Seules les données envoyées à la table après l’application de la transformation seront affectées.

Pour ce didacticiel, exécutez des exemples de requêtes pour envoyer des données à la table LAQueryLogs. Incluez certaines requêtes à LAQueryLogs pour vous permettre de vérifier que la transformation filtre ces enregistrements. Notez que la sortie contient la nouvelle colonne Workspace_CF et qu’il n’y a aucun enregistrement pour LAQueryLogs.

Dépannage

Cette section décrit les différentes conditions d’erreur que vous pouvez recevoir et les mesures de correction.

IntelliSense dans Log Analytics ne reconnaît pas de nouvelles colonnes dans la table

La mise à jour du cache qui pilote IntelliSense peut durer jusqu’à 24 heures.

La transformation sur une colonne dynamique ne fonctionne pas

Il existe actuellement un problème connu affectant les colonnes dynamiques. Une solution de contournement temporaire consiste à analyser explicitement les données de colonne dynamique à l’aide de parse_json() avant d’effectuer des opérations sur celles-ci.

Étapes suivantes

• En savoir plus sur les transformations
• Découvrez quelles sont les tables qui prennent en charge les transformations de l’espace de travail
• En savoir plus sur l’écriture de requêtes de transformation