Surveiller les résultats de vos requêtes SQL avec une règle d'alerte

Preview

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document explique comment créer une règle d'alerte pour surveiller les résultats d'une requête que vous exécutez dans Log Analytics. Ces requêtes sont écrites en SQL et doivent interroger une vue d'observabilité nommée _AllSpans. La règle d'alerte vous avertit lorsque le résultat de la requête remplit les conditions que vous spécifiez.

Les règles d'alerte que vous créez sur la page Analyse de journaux s'exécutent sur un moteur BigQuery. Par conséquent, les données interrogées doivent être accessibles via un ensemble de données BigQuery associé.

Pour obtenir des informations générales sur l'analyse de journaux, consultez Interroger et analyser des traces avec l'Analyse de journaux.

Fonctionnement des règles d'alerte

Une règle d'alerte décrit les circonstances dans lesquelles vous souhaitez être averti d'un incident et de quelle manière. Vous pouvez utiliser différentes approches pour recevoir une notification lorsque du contenu ou des modèles apparaissent dans vos données de trace :

• Pour surveiller le nombre de délais Cloud Trace ingérés par mois, votre utilisation du quota et votre taux d'ingestion des délais, créez des règles d'alerte dans Cloud Monitoring. Si vous n'avez jamais créé de règle d'alerte, consultez Créer des règles d'alerte pour obtenir des informations détaillées sur l'utilisation de la console Cloud Monitoring.

• Pour afficher ou explorer des traces ou des spans individuels, ou pour afficher les attributs associés aux spans, utilisez la page Explorateur Trace. Pour en savoir plus sur cette page, consultez Rechercher et explorer des traces.

• Pour surveiller l'analyse agrégée de vos données de trace, combinez l'analyse de journaux avec des règles d'alerte. Dans ce scénario, vous utilisez des requêtes SQL pour interroger la vue _AllSpans sur le bucket d'observabilité nommé _Trace. Enfin, vous créez la règle d'alerte pour surveiller les résultats de la requête SQL. Ce type de règle d'alerte est appelé règle d'alerte basée sur SQL.

  Pour en savoir plus sur le stockage de vos données de trace, consultez Présentation du stockage.

  Le reste de ce document explique comment utiliser les règles d'alerte basées sur SQL.

Composants des règles d'alerte

Une règle d'alerte basée sur SQL contient une condition et une programmation :

• La condition contient la requête, qui est une requête SQL interrogeant vos données. La condition définit également les circonstances dans lesquelles le résultat de la requête amène Monitoring à créer un incident.

• La programmation définit la fréquence à laquelle la règle d'alerte exécute sa requête. La planification définit également la taille de la période d'analyse, qui est un filtre qui ne sélectionne que les données reçues depuis la dernière évaluation de la requête. Par exemple, si vous définissez la programmation sur 60 minutes, la requête est exécutée toutes les 60 minutes à l'aide d'une période d'analyse qui sélectionne les 60 dernières minutes de données.

Les règles d'alerte contiennent également une liste de canaux de notification. Lorsque la condition de la règle d'alerte est remplie, Cloud Monitoring crée un incident, puis envoie des notifications à son sujet via ces canaux. Un incident est un enregistrement des données qui ont entraîné le respect de la condition, ainsi que d'autres informations pertinentes. Ces informations peuvent vous aider à résoudre les problèmes qui ont provoqué l'incident. Vous pouvez afficher l'incident à l'aide de la console Google Cloud .

Types d'évaluation pour les règles d'alerte basées sur SQL

Les conditions qui surveillent le résultat d'une requête SQL sont compatibles avec deux types d'évaluation :

• Seuil du nombre de lignes : la condition est remplie lorsque le nombre de lignes dans le résultat de la requête est supérieur, égal ou inférieur à une valeur seuil.

• Booléen : la condition est remplie lorsqu'une colonne booléenne spécifique du tableau de résultats de la requête contient une ligne avec une valeur true.

Les règles d'alerte qui surveillent le résultat d'une requête SQL ne doivent comporter qu'une seule condition.

Règles d'alerte et BigQuery

Pour qu'une règle d'alerte interroge vos données de trace, vous devez configurer un ensemble de données BigQuery associé. Les ensembles de données associés permettent à BigQuery de lire vos données de trace et d'exécuter des fonctions BigQuery sur les données renvoyées par votre requête SQL.

Lorsqu'une règle d'alerte exécute une requête SQL, cette requête est exécutée sur le moteur BigQuery dans le projet Google Cloud où la règle d'alerte est définie. Par défaut, les requêtes exécutées sur le moteur BigQuery utilisent des emplacements à la demande. Les emplacements à la demande et les emplacements réservés sont soumis à la tarification BigQuery.

Vous pouvez également choisir de configurer des réservations emplacement BigQuery dédiées pour votre projet :

1. Créez une réservation avec des emplacements dédiés ou identifiez une réservation existante.
2. Créez des attributions de réservation pour votre projet.

Période d'analyse et délai de propagation des incidents

Lorsqu'une règle d'alerte est programmée pour évaluer sa condition, l'analyse de journaux retarde l'exécution de la requête SQL de cinq minutes pour laisser le temps à Cloud Logging d'indexer les données reçues pendant la période d'analyse. Par exemple, si la règle d'alerte utilise une période d'analyse qui se termine à 14h, l'analyse de journaux n'exécute la requête SQL qu'à 14h05.

Si la condition d'alerte est remplie après l'exécution de la requête, la propagation de l'incident dans le système peut prendre jusqu'à deux minutes supplémentaires.

Échecs des requêtes

Les requêtes émises par les règles d'alerte basées sur SQL peuvent échouer pour différentes raisons, y compris les suivantes :

• Le compte de service de surveillance n'existe plus ou ne dispose plus des autorisations nécessaires pour lire les données de trace interrogées.

• Le temps d'exécution de la requête dépasse cinq minutes.

• Une erreur interne se produit.

Une requête ayant échoué génère une entrée de journal contenant l'ID de la règle d'alerte et l'état de l'erreur. Vous pouvez utiliser une règle d'alerte basée sur les journaux pour créer une alerte lorsqu'une erreur est consignée.

Avant de commencer

Cette section suppose que vous disposez d'un ensemble de données BigQuery associé à vos données de trace.

Avant de créer une règle d'alerte basée sur SQL, procédez comme suit :

1. Pour obtenir les autorisations nécessaires pour interroger les données de trace et créer des règles d'alerte basées sur SQL, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

   • Interroger les données de trace : Utilisateur Cloud Trace (roles/cloudtrace.user)
   • Créez des règles d'alerte basées sur SQL :
     • Éditeur Monitoring (roles/monitoring.editor)
     • Logging SqlAlertWriter (roles/logging.sqlAlertWriter)

2. Vérifiez que le compte de service Monitoring existe et qu'il dispose des rôles suivants :

   1. Agent de service Monitoring (roles/monitoring.notificationServiceAgent) sur votre projet.
   2. Lecteur de données BigQuery (roles/bigquery.dataViewer) sur votre ensemble de données associé.

   Si le compte de service de surveillance n'existe pas, consultez Dépannage : aucun compte de service de surveillance.

3. Configurez les canaux de notification que vous souhaitez utiliser pour recevoir les notifications d'incidents. À des fins de redondance, nous vous recommandons de créer plusieurs types de canaux de notification. Pour en savoir plus, consultez Créer et gérer des canaux de notification.

Créer une règle d'alerte basée sur SQL

Pour créer une règle d'alerte basée sur SQL, procédez comme suit :

ConsoleGoogle Cloud

1. Dans la console Google Cloud , accédez à la page Analyse de journaux :

   Accéder à l'Analyse de journaux

   Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

2. Sur la page Log Analytics, dans l'éditeur de requête, saisissez une requête SQL qui interroge vos données de trace.

3. Dans la barre d'outils, cliquez sur Exécuter sur BigQuery.

   Log Analytics exécute votre requête sur le moteur BigQuery et affiche les résultats dans le tableau Résultats.

   Si l'option Exécuter sur BigQuery ne s'affiche pas, cliquez sur Sélectionner le moteur de requête, puis sur BigQuery. Le bouton Exécuter la requête devient Exécuter sur BigQuery.

4. Dans le tableau Résultats de la page Analyse de journaux, cliquez sur  Créer une alerte.

   La page Analyse de journaux affiche la fenêtre Créer une règle d'alerte SQL, qui affiche votre requête dans la section Requête SQL.

5. Dans la section Condition d'alerte, configurez la condition et la programmation de votre règle d'alerte.

6. Configurez les détails de l'alerte de votre règle d'alerte.

   1. Ajoutez des canaux de notification et configurez le contenu des notifications, comme une ligne d'objet personnalisée.

   2. Facultatif : Ajoutez des libellés de règles d'alerte et de la documentation.

   3. Cliquez sur Suivant.

7. Examinez votre règle d'alerte, puis créez-la en cliquant sur Enregistrer.

API Cloud Monitoring

Utilisez la méthode alertPolicies.create pour créer des règles d'alerte par programmation. Le type Condition de votre règle d'alerte doit être MonitoringQueryLanguageCondition, qui est une instance de SqlCondition. Ce type de condition vous permet de définir les conditions de votre règle d'alerte avec SQL.

Pour définir la programmation, définissez une valeur periodicity pour l'un des champs minutes, hours ou days. Par exemple, si vous souhaitez que la requête s'exécute toutes les 12 heures, définissez la périodicité du champ hours sur 12.

Pour définir la condition, utilisez les champs suivants :

• boolean_test : configure la règle d'alerte de sorte que sa condition soit remplie lorsqu'une ligne d'une colonne booléenne du tableau des résultats de la requête contient une valeur "true".
• row_count_test : configure la règle d'alerte de sorte que sa condition soit remplie lorsque le nombre de lignes dans le tableau des résultats de la requête atteint un certain seuil.

Pour obtenir la liste complète des champs et des définitions, consultez SqlCondition dans la documentation de l'API Cloud Monitoring.

Pour plus d'informations sur l'API Monitoring pour les règles d'alerte, consultez la page Gérer des règles d'alerte à l'aide d'API.

Terraform

1. Installez et configurez Terraform pour votre projet. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.

2. Dans Cloud Shell, accédez au répertoire contenant votre configuration Terraform.

3. Dans votre configuration Terraform, configurez une instance de la ressource google_monitoring_alert_policy, y compris condition_sql.

4. Dans Cloud Shell, saisissez terraform apply.

Pour modifier votre règle d'alerte, apportez les modifications souhaitées, puis appliquez à nouveau la configuration Terraform. Pour en savoir plus, consultez Gérer les règles d'alerte avec Terraform.

Pour obtenir des informations générales sur l'utilisation de Google Cloud avec Terraform, consultez Terraform avec Google Cloud.

Limites

• Vous ne pouvez définir qu'une seule condition par règle d'alerte basée sur SQL.

• Les règles d'alerte basées sur SQL ne peuvent pas interroger une vue analytique.

• Les requêtes émises par les règles d'alerte basées sur SQL échouent lorsque leur durée d'exécution dépasse cinq minutes.

• Il s'écoule jusqu'à sept minutes, plus le temps d'exécution de la requête, entre le moment où une requête est planifiée et celui où un incident est créé.

Pour obtenir la liste complète des limites associées aux règles d'alerte, consultez Limites de Monitoring.

Étapes suivantes

• Interroger un ensemble de données BigQuery associé
• Exemples de requêtes SQL
• Enregistrer et partager une requête SQL