Agréger des données dans un espace de travail Log Analytics à l’aide de règles récapitulatives (préversion)

Une règle récapitulative vous permet d’agréger les données de journal à une cadence régulière et d’envoyer les résultats agrégés à une table de journaux personnalisée dans votre espace de travail Log Analytics. Utilisez des règles récapitulatives pour optimiser vos données pour :

• Analyse et rapports, en particulier sur des jeux de données volumineux et des intervalles de temps, comme requis pour l’analyse de la sécurité et des incidents, les rapports commerciaux mensuels ou annuels, et ainsi de suite. Les requêtes complexes sur un jeu de données volumineux expirent souvent. Il est plus facile et plus efficace d’analyser et de signaler nettoyés et des données agrégées résumées.

• Économies de coûts sur les journaux détaillés, que vous pouvez conserver aussi peu ou aussi longtemps que nécessaire dans une table de journaux de base bon marché, et envoyer des données résumées à une table Analytics pour l’analyse et les rapports.

• Sécurité et confidentialité des données en supprimant ou en obfusquant les détails de confidentialité dans les données partageables résumées et en limitant l’accès aux tables avec des données brutes.

Cet article explique comment fonctionnent les règles de synthèse et comment définir et afficher des règles de synthèse, et fournit des exemples d’utilisation et d’avantages des règles de synthèse.

Voici une vidéo qui fournit une vue d’ensemble de quelques-uns des avantages des règles de résumé :

Fonctionnement des règles de synthèse

Les règles récapitulatives effectuent directement le traitement par lots dans votre espace de travail Log Analytics. La règle de résumé agrège les blocs de données, définis par taille de compartiment, en fonction d’une requête KQL, et réingère les résultats résumés dans une table personnalisée avec un plan de journal Analytics dans votre espace de travail Log Analytics.

Vous pouvez agréger des données à partir de n’importe quelle table, que la table ait un plan de données Analytics ou De base. Azure Monitor crée le schéma de table de destination en fonction de la requête que vous définissez. Si la table de destination existe déjà, Azure Monitor ajoute toutes les colonnes requises pour prendre en charge les résultats de la requête. Toutes les tables de destination incluent également un ensemble de champs standard avec des informations de règle récapitulatives, notamment :

• _RuleName: règle récapitulative qui a généré l’entrée de journal agrégée.
• _RuleLastModifiedTime: lors de la dernière modification de la règle.
• _BinSize: intervalle d’agrégation.
• _BinStartTime : l’heure de début de l’agrégation.

Vous pouvez configurer jusqu’à 30 règles actives pour agréger des données à partir de plusieurs tables et envoyer les données agrégées à des tables de destination distinctes ou à la même table.

Vous pouvez exporter des données résumées à partir d’une table de journaux personnalisée vers un compte de stockage ou Event Hubs pour des intégrations supplémentaires en définissant une règle d’exportation de données.

Exemple : synthétiser les données ContainerLogsV2

Si vous surveillez des conteneurs, vous ingérer un grand volume de journaux détaillés dans la table ContainerLogsV2.

Vous pouvez utiliser cette requête dans votre règle de synthèse pour agréger toutes les entrées de journal uniques dans les 60 minutes, en conservant les données utiles pour l’analyse et la suppression de données dont vous n’avez pas besoin :

ContainerLogV2 | summarize Count = count() by  Computer, ContainerName, PodName, PodNamespace, LogSource, LogLevel, Message = tostring(LogMessage.Message)

Voici les données brutes de la table ContainerLogsV2 :

Voici les données agrégées que la règle récapitulative envoie à la table de destination :

Au lieu de journaliser des centaines d’entrées similaires dans un délai d’une heure, la table de destination affiche le nombre de chaque entrée unique, comme défini dans la requête KQL. Définissez le plan de données de base sur la table ContainerLogsV2 pour une rétention bon marché des données brutes et utilisez les données résumées dans la table de destination pour vos besoins d’analyse.

Autorisations requises

Considérations relatives à l’implémentation

• Le nombre maximal de règles actives dans un espace de travail est de 30.
• Les règles récapitulatives sont actuellement disponibles uniquement dans le cloud public.
• La règle de synthèse traite les données entrantes et ne peut pas être configurée sur un intervalle de temps historique.
• Lorsque les nouvelles tentatives d’exécution des compartiments sont épuisées, la corbeille est ignorée et ne peut pas être réexécutée.
• L’interrogation d’un espace de travail Log Analytics dans un autre locataire à l’aide de Lighthouse n’est pas prise en charge.

Modèle de tarification

Il n’y a aucun coût supplémentaire pour les règles de Résumé. Vous payez uniquement pour la requête et l’ingestion des résultats dans la table de destination, en fonction du plan de table de la table source dans laquelle vous exécutez la requête :

Par exemple, le calcul du coût pour une règle horaire qui retourne 100 enregistrements par bac est :

Pour plus d’informations, consultez Tarification Azure Monitor.

Créer ou mettre à jour une règle récapitulative

Les opérateurs que vous pouvez utiliser dans la règle récapitulative de votre requête dépendent du plan de la table source dans la requête.

• Analytique : prend en charge tous les opérateurs et fonctions KQL, à l’exception des éléments suivants :
  • Requêtes inter-ressources, qui utilisent les expressions workspaces(), app() et resource(), et les requêtes inter-services, qui utilisent les expressions ADX() et ARG().
  • Plugins qui remodèlent le schéma des données, notamment bag unpack, narrow, et pivot.
• De base : prend en charge tous les opérateurs KQL sur une table unique. Vous pouvez joindre jusqu’à cinq tables Analytics à l’aide de l’opérateur recherche.
• Fonctions : les fonctions définies par l’utilisateur ne sont pas prises en charge. Les fonctions système fournies par Microsoft sont prises en charge.

Les règles récapitulatives sont les plus avantageuses en termes de coût et d’expériences de requête lorsque le nombre de résultats ou le volume sont significativement réduits. Par exemple, cibler un volume de résultats de 0,01 % ou inférieure à la source. Avant de créer une règle, testez la requête dans Log Analytics et vérifiez que la requête n’atteint ni n’approche les limites de l’API de requête. Vérifiez que la requête produit le schéma et les résultats attendus prévus. Si la requête est proche des limites de requête, envisagez d’utiliser une plus petite taille de bac pour traiter moins de données par bac. Vous pouvez également modifier la requête pour retourner moins d’enregistrements ou de champs avec un volume plus élevé.

Lorsque vous mettez à jour une requête et que les résultats résumés comptent moins de champs, Azure Monitor ne supprime pas automatiquement les colonnes de la table de destination et vous devez supprimer des colonnes de votre table manuellement.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourcegroup}/providers/Microsoft.OperationalInsights/workspaces/{workspace}/summarylogs/{ruleName}?api-version=2023-01-01-preview
Authorization: {credential}

{
  "properties": {
      "ruleType": "User",
      "description": "My test rule",
      "ruleDefinition": {
          "query": "StorageBlobLogs | summarize count() by AccountName",
          "binSize": 30,
          "destinationTable": "MySummaryLogs_CL"
      }
  }
}

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workspaceName": {
      "type": "String",
      "metadata": {
        "description": "The workspace name where summary rule is deployed."
      }
    },
    "summaryRuleName": {
      "type": "String",
      "metadata": {
        "description": "The summary rule name."
      }
    },
    "description": {
      "type": "String",
      "metadata": {
        "description": "A description of the rule."
      }
    },
    "location": {
      "defaultValue": "[resourceGroup().location]",
      "type": "String",
      "metadata": {
        "description": "The Location of the workspace summary rule is deployed."
      }
    },
    "ruleType": {
      "defaultValue": "User",
      "allowedValues": [
        "User"
      ],
      "type": "String",
      "metadata": {
        "description": "The summary rule type (User,System). Should be 'User' for and rule with query that you define."
      }
    },
    "query": {
      "type": "String",
      "metadata": {
      "description": "The query used in summary rules."
      }
    },
    "binSize": {
      "defaultValue": 60,
      "allowedValues": [
        20,
        30,
        60,
        120,
        180,
        360,
        720,
        1440
      ],
      "type": "Int",
      "metadata": {
        "description": "The execution interval in minutes, and the lookback time range."
      }
    },
    "destinationTable": {
      "type": "String",
      "metadata": {
        "description": "The name of the custom log table that the summary results are sent to. Name must end with '_CL'."
      }
    }
    // ----- optional -----
    // "binDelay": {
    //   "type": "Int",
    //   "metadata": {
    //     "description": "Optional - The minimum wait time in minutes before bin execution. For example, value of '10' cause bin (01:00-02:00) to be executed after 02:10."
    //   }
    // },
    // "timeSelector": {
    //   "defaultValue": "TimeGenerated",
    //   "allowedValues": [
    //     "TimeGenerated"
    //   ],
    //   "type": "String",  
    //   "metadata": {
    //     "description": "Optional - The time field to be used by the summary rule. Must be 'TimeGenerated'."
    //   }
    // },
    // "binStartTime": {
    //   "type": "String",
    //   "metadata": {
    //     "description": "Optional - The Time of initial bin. Can start at current time minus binSize, or future, and in whole hours. For example: '2024-01-01T08:00'."
    //   }
    // }
  },
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.OperationalInsights/workspaces/summaryLogs",
      "apiVersion": "2023-01-01-preview",
      //"name": "[format('{0}/{1}', parameters('workspaceName'), parameters('summaryRuleName'))]",
      "name": "[concat(parameters('workspaceName'), '/', parameters('summaryRuleName'))]",
      "properties": {
        "ruleType": "[parameters('ruleType')]",
        "description": "[parameters('description')]",
        "ruleDefinition": {
          "query": "[parameters('query')]",
          "binSize": "[parameters('binSize')]",
          "destinationTable": "[parameters('destinationTable')]"
          // ----- optional -----
          //"binDelay": "[parameters('binDelay')]",
          //"timeSelector": "[parameters('timeSelector')]",
          //"binStartTime": "[parameters('binStartTime')]"
        }
      }
    }
  ]
}

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workspaceName": {
      "value": "myworkspace"
    },
    "summaryRuleName": {
      "value": "myrulename"
    },
    "description": {
      "value": "My rule description."
    },
    "location": {
      "value": "eastus" //Log Analytics workspace region
    },
    "ruleType": {
      "value": "User"
    },
    "query": {
      "value": "StorageBlobLogs | summarize Count = count(), DurationMs98 = percentile(DurationMs, 90) by StatusCode, CallerIpAddress, OperationName"
    },
    "binSize": {
      "value": 20
    },
    "destinationTable": {
      "value": "MySummaryLogs_CL"
    }
  }
}

Ce tableau décrit les paramètres de règle de synthèse :

Configurer le minutage d’agrégation

Par défaut, la règle récapitulative crée la première agrégation peu après l’heure entière suivante.

Le délai court d’Azure Monitor ajoute des comptes pour la latence d’ingestion , ou le temps entre le moment où les données sont créées dans le système surveillé et le temps qu’il devient disponible pour l’analyse dans Azure Monitor. Par défaut, ce délai est compris entre trois minutes et demi et 10 % de la valeur de la taille de bac avant d’agréger chaque bac. Dans la plupart des cas, ce délai garantit qu’Azure Monitor agrège toutes les données journalisées dans chaque période bin.

Par exemple :

• Vous créez une règle de résumé avec une taille de bac de 30 minutes à 14:44.

  La règle crée la première agrégation peu après 15:00 ( par exemple, à 15:04 ) pour les données enregistrées entre 14:30 et 15:00.

• Vous créez une règle de résumé avec une taille de bac de 720 minutes (12 heures) à 14 h 44.

  La règle crée la première agrégation à 16:12 - 72 minutes (10 % de la taille de 720 compartiments) après 13:00 - pour les données journalisées entre 03:00 et 15:00.

Utilisez les paramètres binStartTime et binDelay pour modifier le minutage de la première agrégation et le délai qu’Azure Monitor ajoute avant chaque agrégation.

Les sections suivantes fournissent des exemples de minutage d’agrégation par défaut et les options de minutage d’agrégation plus avancées.

Utiliser le minutage d’agrégation par défaut

Dans cet exemple, la règle de résumé est créée le 2023-06-07 à 14:44, et Azure Monitor ajoute un délai par défaut de quatre minutes.

Définir des paramètres de minutage d’agrégation facultatifs

Dans cet exemple, la règle de résumé est créée à l’adresse 2023-06-07 à 14:44, et la règle inclut ces paramètres de configuration avancés :

• binStartTime: 2023-06-08 07:00
• binDelay: 8 minutes

Afficher les règles récapitulatives

Utilisez cet appel d’API GET pour afficher la configuration d’une règle récapitulative spécifique :

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourcegroup}/providers/Microsoft.OperationalInsights/workspaces/{workspace}/summarylogs/{ruleName1}?api-version=2023-01-01-preview
Authorization: {credential}

Utilisez cet appel d’API GET pour afficher la configuration pour afficher la configuration de toutes les règles récapitulatives dans votre espace de travail Log Analytics :

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourcegroup}/providers/Microsoft.OperationalInsights/workspaces/{workspace}/summarylogs?api-version=2023-01-01-preview
Authorization: {credential}

Arrêter et redémarrer une règle récapitulative

Vous pouvez arrêter une règle pendant une période de temps , par exemple, si vous souhaitez vérifier que les données sont ingérées dans une table et que vous ne souhaitez pas affecter la table et les rapports résumés. Lorsque vous redémarrez la règle, Azure Monitor démarre le traitement des données à partir de l’heure entière suivante ou en fonction du paramètre défini binStartTime (facultatif).

Pour arrêter une règle, utilisez cet appel d’API POST :

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourcegroup}/providers/Microsoft.OperationalInsights/workspaces/{workspace}/summarylogs/{ruleName}/stop?api-version=2023-01-01-preview
Authorization: {credential}

Pour redémarrer la règle, utilisez cet appel d’API POST :

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourcegroup}/providers/Microsoft.OperationalInsights/workspaces/{workspace}/summarylogs/{ruleName}/start?api-version=2023-01-01-preview
Authorization: {credential}

Supprimer une règle récapitulative

Vous pouvez avoir jusqu’à 30 règles de synthèse actives dans votre espace de travail Log Analytics. Si vous souhaitez créer une règle, mais que vous avez déjà 30 règles actives, vous devez arrêter ou supprimer une règle récapitulative active.

Pour supprimer une règle, utilisez cet appel d’API DELETE :

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourcegroup}/providers/Microsoft.OperationalInsights/workspaces/{workspace}/summarylogs/{ruleName}?api-version=2023-01-01-preview
Authorization: {credential}

Surveiller les règles récapitulatives

Pour surveiller les règles de synthèse, activez la catégorie journaux de synthèse dans les paramètres de diagnostic de votre espace de travail Log Analytics. Azure Monitor envoie les détails de l’exécution de règle récapitulative, y compris les informations de démarrage, de réussite et d’échec de la règle de résumé, à la table LASummaryLogs dans votre espace de travail.

Nous vous recommandons de configurer des règles d’alerte de journal pour recevoir la notification des échecs de compartiment, ou lorsque l’exécution du bac est proche du délai d’attente, comme indiqué ci-dessous. Selon la raison de l’échec, vous pouvez réduire la taille du bac pour traiter moins de données sur chaque exécution, ou modifier la requête pour retourner moins d’enregistrements ou de champs avec un volume plus élevé.

Cette requête retourne des exécutions ayant échoué :

LASummaryLogs | where Status == "Failed"

Cette requête retourne des exécutions bin où la valeur QueryDurationMs est supérieure à 0,9 x 600 000 millisecondes :

LASummaryLogs | where QueryDurationMs > 0.9 * 600000

Vérifier l’exhaustivité des données

Les règles récapitulatives sont conçues pour la mise à l’échelle et incluent un mécanisme de nouvelle tentative pour surmonter les échecs temporaires de service ou de requête liés à limites de requête, par exemple. Le mécanisme de nouvelle tentative effectue 10 tentatives d’agrégation d’un bac défaillant dans les huit heures, et ignore un bac, s’il est épuisé. La règle est définie sur isActive: false et mise en attente après huit nouvelles tentatives consécutives de bac. Si vous activez surveiller les règles de synthèse, Azure Monitor journalise un événement dans la table LASummaryLogs de votre espace de travail.

Vous ne pouvez pas réexécuter une exécution bin ayant échoué, mais vous pouvez utiliser la requête suivante pour afficher les exécutions ayant échoué :

let startTime = datetime("2024-02-16");
let endtTime = datetime("2024-03-03");
let ruleName = "myRuleName";
let stepSize = 20m; // The stepSize value is equal to the bin size defined in the rule
LASummaryLogs
| where RuleName == ruleName
| where Status == 'Succeeded'
| make-series dcount(BinStartTime) default=0 on BinStartTime from startTime to endtTime step stepSize
| render timechart

Cette requête affiche les résultats sous forme d’organigramme :

Consultez la section Surveiller les règles récapitulatives pour connaître les options de correction des règles et les alertes proactives.

Chiffrer les requêtes de règles récapitulatives à l’aide de clés gérées par le client

Une requête KQL peut contenir des informations sensibles dans les commentaires ou dans la syntaxe de la requête. Pour chiffrer les requêtes de règle de synthèse, lier un compte de stockage à votre espace de travail Log Analytics et utiliser des clés gérées par le client.

Considérations relatives à l’utilisation de requêtes chiffrées :

• La liaison d’un compte de stockage pour chiffrer vos requêtes n’interrompt pas les règles existantes.
• Par défaut, Azure Monitor stocke les requêtes de règles récapitulatives dans le stockage Log Analytics. Si vous disposez de règles récapitulatives existantes avant de lier un compte de stockage à votre espace de travail Log Analytics, mettez à jour vos règles récapitulatives afin que les requêtes enregistrent les requêtes existantes dans le compte de stockage.
• Les requêtes que vous enregistrez dans un compte de stockage se trouvent dans la table CustomerConfigurationStoreTable. Ces requêtes sont considérées comme des artefacts de service et leur format peut changer.
• Vous pouvez utiliser le même compte de stockage pour les requêtes de règles récapitulatives, requêtes enregistrées dans log Analyticset Alertes de journal.

Résoudre les problèmes liés aux règles récapitulative

Cette section fournit des conseils pour résoudre les problèmes liés aux règles récapitulatives.

Table de destination de règle récapitulative accidentellement supprimée

Si vous supprimez la table de destination pendant que la règle récapitulative est active, la règle est suspendue et Azure Monitor envoie un événement à la table LASummaryLogs avec un message indiquant que la règle a été suspendue.

Si vous n’avez pas besoin des résultats récapitulatives dans la table de destination, supprimez la règle et la table. Si vous devez récupérer les résultats de résumé, suivez les étapes de la section Créer ou mettre à jour des règles de synthèse pour recréer la table. La table de destination est restaurée, y compris les données ingérées avant la suppression, en fonction de la stratégie de rétention dans la table.

Si vous n’avez pas besoin des résultats récapitulatives dans la table de destination, supprimez la règle et la table. Si vous avez besoin des résultats de résumé, suivez les étapes de la section Créer ou mettre à jour des règles récapitulatives pour recréer la table de destination et restaurer toutes les données, y compris les données ingérées avant la suppression, en fonction de la stratégie de rétention dans la table.

La requête utilise des opérateurs qui créent des colonnes dans la table de destination

Le schéma de table de destination est défini lorsque vous créez ou mettez à jour une règle récapitulative. Si la requête dans la règle récapitulative inclut des opérateurs qui autorisent l’expansion du schéma de sortie en fonction des données entrantes, par exemple, si la requête utilise la fonction arg_max(expression, *) - Azure Monitor n’ajoute pas de nouvelles colonnes à la table de destination après avoir créé ou mis à jour la règle de synthèse, et les données de sortie qui nécessitent que ces colonnes soient supprimées. Pour ajouter les nouveaux champs à la table de destination, mettre à jour la règle de synthèse ou ajouter une colonne à votre table manuellement.

Les données dans les colonnes supprimées restent dans l’espace de travail en fonction des paramètres de rétention de la table

Lorsque vous supprimez un champ dans la requête, les colonnes et les données restent dans la destination et sont basées sur la période de rétention définie sur la table ou l’espace de travail. Si vous n’avez pas besoin de la suppression dans la table de destination, supprimez les colonnes du schéma de table. Si vous ajoutez ensuite des colonnes portant le même nom, toutes les données qui ne sont pas plus anciennes que la période de rétention s’affichent à nouveau.

Contenu connexe

• En savoir plus sur plans de données journaux Azure Monitor.
• Suivez un tutoriel sur l’utilisation du mode KQL dans Log Analytics.
• Accédez à la documentation de référence de KQL complète.