Créer une transformation dans Azure Monitor

Les transformations dans Azure Monitor vous permettent de filtrer ou de modifier des données entrantes avant qu’elles ne soient stockées dans un espace de travail Log Analytics. Elles sont implémentées en tant qu’instruction Langage de requête Kusto (KQL) dans une règle de collecte de données (DCR). Cet article fournit des instructions sur la création et le test d’une requête de transformation et son ajout à une DCR.

Remarque

Si vous n’êtes pas familiarisé avec KQL ou que vous créez des requêtes de journal pour des données Azure Monitor, commencez par Vue d’ensemble de Log Analytics dans Azure Monitor et Requêtes de journal dans Azure Monitor.

Structure de la requête de base

Toutes les requêtes de transformation commencent par source, qui est une table virtuelle qui représente le flux d’entrée. Vous pouvez ensuite utiliser n’importe quel opérateur KQL pris en charge pour filtrer, modifier ou ajouter des colonnes aux données comme vous le feriez avec n’importe quelle autre table. La requête est appliquée individuellement à chaque entrée envoyée par la source de données.

La sortie de la requête doit correspondre au schéma de la table cible avec les considérations suivantes :

• Vous pouvez omettre toutes les colonnes qui ne doivent pas être remplies. La colonne sera vide pour l’enregistrement dans la table cible.
• Veillez à exclure les colonnes qui ne sont pas incluses dans la table de sortie. Les données seront acceptées sans erreur, mais vous serez facturé pour l’ingestion des données supplémentaires, même si elles ne sont pas stockées.
• La sortie de chaque transformation doit contenir un timestamp valide dans une colonne appelée TimeGenerated de type datetime. Si votre source de données n’inclut pas cette propriété, vous pouvez l’ajouter dans la transformation avec extend ou project.

Voici un exemple de transformation qui exécute plusieurs fonctions :

• Filtre les données entrantes avec une instruction where.
• Ajoute une nouvelle colonne à l’aide de l’opérateur extend.
• Met en forme la sortie pour qu’elle corresponde aux colonnes de la table cible à l’aide de l’opérateur project.

source  
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

Remarque

Consultez Exemples et scénarios de règle de collecte de données dans Azure Monitor pour obtenir différents exemples pour différents scénarios.

Créer la requête de transformation

Avant de créer ou de modifier la DCR qui inclut votre transformation, vous devez créer et tester la requête de transformation. Pour ce faire, vous exécutez généralement des requêtes de test sur des données existantes ou des données de test. Lorsque vous obtenez les résultats souhaités, vous pouvez remplacer le nom de la table par source et le coller dans votre DCR, comme expliqué ci-dessous dans Ajouter une transformation à une DCR.

Important

Les transformations ne prennent pas en charge toutes les fonctionnalités KQL. Pour connaître les fonctionnalités prises en charge et les limitations, consultez Fonctionnalités KQL prises en charge dans les transformations Azure Monitor.

Par exemple, si vous créez une transformation pour filtrer les événements Syslog, vous pouvez commencer par la requête suivante que vous pouvez exécuter dans Log Analytics.

Syslog | where SeverityLevel != 'info'

Vous pouvez coller cette requête dans votre DCR, puis remplacer le nom de la table par source.

source | where SeverityLevel != 'info'

Utilisez l’une des stratégies suivantes pour les données à utiliser pour tester votre requête.

• Si vous collectez déjà les données que vous souhaitez transformer, vous pouvez utiliser Log Analytics pour écrire une requête qui filtre ou modifie les données en fonction des besoins. Copiez le texte de la requête et collez-le dans votre DCR.
• Utilisez Log Analytics pour écrire votre requête à l’aide de l’opérateur datatable pour créer un exemple de jeu de données qui représente vos données entrantes. Copiez le texte de la requête sans l’opérateur datatable, et collez-le dans votre DCR.
• Utilisez le processus pour créer une table dans le portail Azure et fournir des exemples de données. Utilisez l’interface incluse pour créer et tester votre requête de transformation. Copiez le texte de la requête et collez-le dans votre DCR, ou terminez le processus puis modifiez la DCR de façon à copier la requête de transformation. Vous pouvez ensuite supprimer la nouvelle table si vous n’en avez pas besoin.

Ajouter une transformation à une DCR

Une fois que vous avez votre requête de transformation, vous pouvez l’ajouter à une DCR. Utilisez les instructions fournies dans Créer et modifier des règles de collecte de données dans Azure Monitor pour créer ou modifier la DCR en utilisant les informations de cette section pour inclure la requête de transformation dans la définition de DCR.

Remarque

Certaines sources de données fournissent une méthode à l’aide du portail Azure pour ajouter une transformation à une DCR. Par exemple, la collecte d’un texte à partir d’une machine virtuelle vous permet de spécifier une requête de transformation dans le portail Azure. La plupart des scénarios de collecte de données nécessitent actuellement que vous travailliez directement avec la définition de DCR pour ajouter une transformation. Il s’agit du processus décrit dans cette section.

La requête de transformation est spécifiée dans la propriété transformKql de la section Flux de données de la DCR. Il s’agit de la section qui associe une source de données à une destination. La transformation est appliquée au flux entrant du flux de données avant son envoi à la destination. Elle s’applique uniquement à ce flux de données, même si le même flux ou la même destination est utilisé dans d’autres flux de données.

Si la propriété transformKql est omise, ou si sa valeur est simplement source, aucune transformation n’est appliquée, et les données entrantes sont envoyées à la destination sans modification.

Important

La requête de transformation doit se trouver sur une seule ligne de la DCR. Si vous créez la transformation dans le portail Azure, vous pouvez utiliser plusieurs lignes à des fins de lisibilité, et \n sera inclus dans la requête pour chaque nouvelle ligne.

Dans l’exemple suivant, il n’existe aucune propriété transformKql, de sorte que les données entrantes sont envoyées à la destination sans modification.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

Dans l’exemple suivant, transformKql a une requête simple source ; les données entrantes sont donc envoyées à la destination sans modification. Sa fonctionnalité est identique à l’exemple précédent.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

Dans l’exemple suivant, transformKql a une requête qui filtre les données ; seuls les messages d’erreur sont donc envoyés à la destination.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source | where message has 'error'", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

Créer une DCR de transformation d’espace de travail

La règle de collecte des données (DCR) de transformation de l’espace de travail est une DCR spéciale qui s’applique directement à un espace de travail Log Analytics. Il ne peut y avoir qu’une seul DCR de transformation d’espace de travail pour chaque espace de travail, mais elle peut inclure des transformations pour n’importe quelle quantité de tables.

Appliquez l’une des méthodes suivantes pour créer une DCR de transformation d’espace de travail pour votre espace de travail et y ajouter une ou plusieurs transformations.

Azure

Vous pouvez créer une DCR de transformation d’espace de travail dans le portail Azure en ajoutant une transformation à une table prise en charge.

1. Dans le menu Espaces de travail Log Analytics du portail Azure, sélectionnez Tables. Cliquez à droite de la table qui vous intéresse et sélectionnez Créer une transformation.

   

2. Si la DCR de transformation d’espace de travail n’a pas encore été créée pour cet espace de travail, sélectionnez l’option pour en créer une. Si elle a déjà été créée, cette DCR sera déjà sélectionnée. Chaque espace de travail ne peut avoir qu’une seule DCR de transformation d’espace de travail.

   

3. Sélectionnez Suivant pour afficher des exemples de données à partir de la table. Cliquez sur Éditeur de transformation pour définir la requête de transformation.

   

4. Vous pouvez ensuite modifier et exécuter la requête de transformation pour afficher les résultats par rapport aux données réelles de la table. Continuez à modifier et à tester la requête jusqu’à obtenir les résultats souhaités.

5. Lorsque vous êtes satisfait de la requête, cliquez sur Appliquer, puis sur Suivant et Créer pour enregistrer la DCR avec votre nouvelle transformation.

   

JSON

Les DCR de transformation d’espace de travail ressemblent en grande partie à toutes les autres DCR. Elles utilisent la même structure JSON pour leur définition, et vous pouvez les créer et les modifier à l’aide des mêmes commandes et stratégies que celles décrites dans Créer ou modifier une DCR à l’aide de JSON. Les différences concernent la définition JSON :

• Elle doit inclure le paramètre kind avec une valeur de WorkspaceTransforms.
• La section dataSources doit être vide.
• La section destinations doit inclure une et une seule destination d’espace de travail Log Analytics. Il s’agit de l’espace de travail où la transformation sera appliquée.
• La section dataFlows doit inclure un flux de données distinct pour chaque table qui aura une transformation. Utilisez une clause where dans la requête si seuls certains enregistrements doivent être transformés.

Voici un exemple de définition JSON pour une DCR de transformation d’espace de travail.

{
    "kind": "WorkspaceTransforms",
    "location": "eastus",
    "properties": {
        "dataSources": {},
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/71b36fb6-4fe4-4664-9a7b-245dc62f2930/resourcegroups/my-resource-group/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "MyWorkspace"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Microsoft-Table-LAQueryLogs"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | where QueryText !contains 'LAQueryLogs'"
            },
            {
                "streams": [
                    "Microsoft-Table-Event"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | project-away ParameterXml"
            }
        ],
        "provisioningState": "Succeeded"
    }
}

Optimiser et surveiller les transformations

Les transformations exécutent une requête KQL sur chaque enregistrement collecté avec la DCR. Il est donc important qu’elles s’exécutent efficacement. Le temps d’exécution des transformations contribue à la latence globale d’ingestion des données, et les transformations dont l’exécution prend un temps excessif peuvent avoir un impact sur les performances du pipeline de collecte de données et entraîner une perte de données. Les transformations optimales ne doivent pas prendre plus d’une seconde. Pour obtenir des instructions sur le test de votre requête avant de l’implémenter en tant que transformation et pour obtenir des recommandations sur l’optimisation des requêtes qui ne s’exécutent pas efficacement, consultez Optimiser les requêtes de journal dans Azure Monitor.

Important

Vous pouvez rencontrer une perte de données si une transformation prend plus de 20 secondes.

Comme les transformations ne s’exécutent pas de façon interactive, il est important de les surveiller en permanence afin de s’assurer qu’elles s’exécutent correctement et qu’elles ne prennent pas un temps excessif pour traiter les données. Pour plus d’informations sur les journaux et les métriques qui surveillent l’intégrité et les performances des transformations, consultez Surveiller et résoudre les problèmes de collecte de données DCR dans Azure Monitor. Ceci inclut l’identification des erreurs qui se produisent dans le code KQL et les métriques pour suivre leur durée d’exécution.

Les métriques suivantes sont collectées automatiquement pour les transformations et doivent être examinées régulièrement pour vérifier que vos transformations continuent de s’exécuter comme attendu. Créez des règles d’alerte de métrique afin d’être averti automatiquement quand l’une de ces métriques dépasse un seuil.

• Logs Transformation Duration per Min
• Logs Transformation Errors per Min

Activez les journaux d’erreurs DCR pour faire le suivi des erreurs qui se produisent dans vos transformations ou d’autres requêtes. Créez une règle d’alerte de journal afin d’être averti automatiquement lorsqu’une entrée est écrite dans cette table.

Assistance

Il existe plusieurs méthodes pour créer des transformations en fonction de la méthode de collecte de données. Le tableau suivant répertorie des conseils pour différentes méthodes de création de transformations.

Collecte de données	Référence
API d’ingestion de journaux	Envoyer des données aux journaux Azure Monitor à l’aide de l’API REST (portail Azure) Envoyer des données aux journaux Azure Monitor à l’aide de l’API REST (modèles Azure Resource Manager)
Machine virtuelle avec l’agent Azure Monitor	Ajouter une transformation au journal Azure Monitor
Cluster Kubernetes avec Container Insights	Transformations de données dans Container Insights
Azure Event Hubs	Tutoriel : ingérer des événements d'Azure Event Hubs dans les journaux Azure Monitor (préversion publique)

Étapes suivantes

• Créez une règle de collecte de données et une association à celle-ci à partir d’une machine virtuelle à l’aide de l’agent Azure Monitor.