Utiliser l'éditeur de requête

Cette section décrit les fonctionnalités de l'éditeur de requête pour le langage MQL (Monitoring Query Language). L'éditeur est disponible dans Google Cloud Console et propose des suggestions, la détection d'erreurs et d'autres fonctionnalités permettant de créer des requêtes MQL valides.

Cette page ne couvre pas le langage MQL. pour consulter un ensemble d'exemples ainsi que des informations supplémentaires sur ce langage, consultez les pages Exemples et À propos du langage MQL. La documentation de référence sur MQL fournit des informations exhaustives sur ce langage.

Accéder à l'éditeur de requête

Vous accédez à l'éditeur de requêtes à partir des pages suivantes de Google Cloud Console:

  • Explorateur de métriques
  • Ajouter un graphique lors de la création de tableaux de bord

La capture d'écran suivante utilise l'explorateur de métriques comme exemple :

Le sélecteur MQL apparaît juste au-dessus de la zone intitulée "Type de ressource et métrique".

Pour afficher l'éditeur de requête, cliquez sur Éditeur de requête dans l'onglet Métrique. La capture d'écran suivante montre l'éditeur de requête :

L'éditeur de requêtes MQL.

Utiliser l'éditeur de requête

Pour utiliser l'éditeur de requête, saisissez votre requête dans la zone de texte, puis cliquez sur Run Query (Exécuter la requête) :

Requête MQL dans l'éditeur de requête.

Saisie semi-automatique

Lorsque vous saisissez une requête, l'éditeur affiche une liste d'achèvements valides d'un point de vue syntaxique. Vous pouvez afficher manuellement le menu de saisie semi-automatique en appuyant sur Control+Space et le fermer en appuyant sur Escape.

Pour parcourir la liste des options, utilisez les touches fléchées. Appuyez sur Enter pour insérer le choix sélectionné.

Pour insérer le préfixe commun à tous les choix disponibles, appuyez sur Tab.

Messages d'erreur

Les messages d'erreur apparaissent en bas du panneau de l'éditeur.

Si la requête contient des erreurs qui interfèrent avec les suggestions de saisie semi-automatique, des messages d'erreur s'affichent au fur et à mesure de la saisie. Sinon, des messages d'erreur s'affichent lorsque vous exécutez la requête.

Repliage du code

L'éditeur offre une fonction de repliage de code qui permet de réduire les segments de vos requêtes afin de les masquer temporairement.

L'éditeur indique les segments de votre requête que l'utilisateur peut replier par des curseurs de saisie à côté des numéros de ligne, comme illustré dans la capture d'écran suivante:

L'éditeur de requêtes indique un code repliable à l'aide de curseurs de saisie.

Rechercher et remplacer

L'éditeur est compatible avec une fonctionnalité de recherche et de remplacement. Pour rechercher et, éventuellement, remplacer des termes dans votre requête, appuyez sur Control+F (ou Command+F sur Mac). La capture d'écran suivante montre cette fonctionnalité:

L'éditeur de requête est compatible avec une fonctionnalité de recherche et de remplacement.

Commandes de l'éditeur

L'éditeur dispose de trois commandes qui déterminent la manière dont il interagit avec votre requête.

Les commandes de l'éditeur de requête MQL.

Par défaut, votre requête n'est exécutée que lorsque vous cliquez sur Run query (Exécuter la requête). Vous pouvez configurer l'éditeur de requêtes pour qu'il exécute automatiquement votre requête au fur et à mesure de la saisie, mais cette option est désactivée par défaut.

Pour activer l'option d'exécution automatique, utilisez le bouton Auto-execute (Exécution automatique). Lorsque cette option est activée, l'éditeur fonctionne comme suit :

  • Le bouton Run query (Exécuter la requête) ne s'affiche pas.
  • Les messages d'erreur s'affichent en continu pendant la saisie.
  • Si le curseur se trouve à la fin d'une requête incomplète, mais qui ne comporte aucune erreur, l'éditeur affiche un triangle jaune dans la barre de contrôle. Si l'espace est suffisant, le texte Incomplete query (Requête incomplète) apparaît également.

    L'éditeur de requête ne tente pas d'évaluer les requêtes incomplètes.

Pour modifier le format de la requête afin de la rendre plus lisible, cliquez sur Format. La modification du format de la requête ne modifie pas sa signification. Le reformat utilise une longueur de ligne de 80 caractères. Par conséquent, si la fenêtre de votre éditeur de requête est inférieure à celle de la ligne de commande, les lignes sont encapsulées.

Il existe également une barre oblique entre l'éditeur de requête et la région du graphique. Utilisez cette barre pour modifier les tailles relatives des deux régions.

Enregistrer des graphiques

Depuis l'explorateur de métriques

Dans l'éditeur de requête de l'explorateur de métriques, vous avez la possibilité d'enregistrer votre graphique dans un tableau de bord. Pour enregistrer votre graphique, procédez comme suit :

  1. Si l'option d'exécution automatique n'est pas activée, exécutez votre requête en cliquant sur Run query (Exécuter la requête) avant d'enregistrer le graphique. Si vous n'exécutez pas votre requête en premier, l'éditeur de requête enregistre la dernière requête exécutée.

  2. Cliquez sur Enregistrer le graphique. Une boîte de dialogue vous indique que l'enregistrement du graphique remplace la requête par une forme stricte. Pour en savoir plus, consultez la section Requêtes de format strict.

  3. Pour continuer à enregistrer le graphique, procédez comme suit :

    1. Donnez un titre descriptif au graphique.
    2. Sélectionnez le tableau de bord souhaité pour le nouveau graphique.
    3. Cliquez sur Save (Enregistrer) dans la boîte de dialogue.

Depuis un tableau de bord

Pour enregistrer un graphique que vous ajoutez à un tableau de bord, procédez comme suit :

  1. Donnez un titre descriptif au graphique.

  2. Si l'option d'exécution automatique n'est pas activée, exécutez votre requête en cliquant sur Run query (Exécuter la requête) avant d'enregistrer le graphique. Si vous n'exécutez pas votre requête en premier, l'éditeur de requête enregistre la dernière requête exécutée.

  3. Cliquez sur Enregistrer. Une boîte de dialogue vous indique que l'enregistrement du graphique remplace la requête par une forme stricte. Pour en savoir plus, consultez la section Requêtes de format strict.

  4. Cliquez sur Save (Enregistrer) dans la boîte de dialogue pour enregistrer le graphique et revenir au tableau de bord.

Quitter l'éditeur de requête

Pour quitter l'éditeur de requête sans enregistrer de graphique ou de condition, cliquez sur Revenir au widget de sélecteur de requête. Tout texte de requête dans l'éditeur est supprimé, mais vous pouvez l'enregistrer dans le presse-papiers.

Périodes, graphiques et éditeur de requête

À l'exception des requêtes MQL utilisées dans les conditions pour les règles d'alerte, les requêtes MQL dans l'éditeur de requêtes doivent inclure une période. La période spécifie le sous-ensemble de données à renvoyer dans le cadre de la requête.

La période peut être exprimée implicitement en utilisant le sélecteur de période pdu graphique ou explicitement dans votre texte de requête MQL.

Pour en savoir plus sur la création de règles d'alerte avec l'éditeur de requête, consultez la section Créer des règles d'alerte MQL.

Utiliser les paramètres de graphique pour sélectionner une période

Vous pouvez définir la période d'une requête à l'aide du sélecteur de temps du graphique. Ce sélecteur est la méthode utilisée par défaut pour définir la période. Pour modifier la période, sélectionnez une autre option dans le graphique. Par exemple, si vous sélectionnez une période d'une semaine, votre requête renvoie les données datant d'aujourd'hui à la semaine précédente.

MQL peut utiliser les périodes spécifiées dans le graphique.

Lorsque vous utilisez ce mécanisme par défaut, vous n'avez pas besoin de spécifier une période explicite dans le texte de votre requête. La valeur du graphique est utilisée implicitement.

Utiliser within pour sélectionner une période

Vous pouvez spécifier explicitement la période dans la requête à l'aide de l'opération within. Cette opération détermine la plage de données renvoyées. Si votre requête inclut une opération within, les options de sélection du temps du graphique sont désactivées et la période spécifiée dans la requête est utilisée.

Si vous supprimez une opération within explicite de votre requête, les options du graphique sont automatiquement réactivées, ce qui garantit que la requête inclut toujours une période.

Vous devez utiliser une sélection de période explicite si vous souhaitez utiliser la méthode d'API timeSeries.query pour envoyer la requête. Pour plus d'informations, consultez la page Utiliser MQL à partir de l'API Monitoring.

Paramètres d'heure et graphiques enregistrés

Si vous utilisez MQL pour créer un graphique, puis l'enregistrer dans un tableau de bord, votre requête subit deux modifications :

  1. La requête que vous avez fournie dans l'éditeur est convertie en une page canonique, ou stricte. La conversion ne modifie pas la signification de votre requête, mais elle rend explicite des éléments supposés dans votre requête, tels que des noms de colonnes complets ou des opérations d'alignement. Pour en savoir plus, consultez la section Requêtes de format strict.

  2. La sélection de la période dans votre requête est supprimée. Les graphiques des tableaux de bord partagent un sélecteur de période, et les modifications apportées à ce sélecteur s'appliquent à tous les graphiques du tableau de bord. Par conséquent, le sélecteur de période de la requête d'origine n'est plus nécessaire.

Pour en savoir plus sur la gestion des tableaux de bord et la modification des graphiques, consultez la page Gérer des tableaux de bord.

Requête, alignement et périodes d'affichage

MQL possède un certain nombre d'opérations spécifiant des périodes qui peuvent prêter à confusion. Les opérations suivantes sont liées à la plage d'une requête :

  • within : spécifie la fenêtre de sortie de la requête. Cette opération détermine la quantité de données renvoyées. Par exemple, si vous spécifiez within 1h, la requête ne produit que les points dont les horodatages sont compris dans l'heure précédente. C'est pourquoi cette opération remplace les options du sélecteur de temps du graphique.

  • Les opérations suivantes concernent la période d'alignement de leurs tables de sortie. Les deux nécessitent une table alignée en entrée, ou fournissent une valeur par défaut :

    • every : spécifie la période pour la sortie de table alignée.

    • window : spécifie la fenêtre pour les opérations d'alignement.

    Dans les deux cas, si une opération align est fournie avec une fenêtre d'alignement explicite, elle doit correspondre à la période spécifiée pour l'opération window, le cas échéant. Pour la fonction d'alignement delta, la fenêtre d'alignement et la période doivent être identiques. Si une fenêtre d'alignement explicite est donnée, l'opération every (si elle est fournie) doit correspondre. Dans tous les cas, la fenêtre d'alignement doit être au moins aussi large que la période d'alignement, sans quoi les données d'entrée seront ignorées.

MQL dispose également d'une opération graph_period qui spécifie la période des points de sortie des graphiques. Cette opération est utile pour les requêtes adressées à l'API, dont la sortie est représentée graphiquement par un logiciel tiers. Le logiciel de création de graphiques de Monitoring ignore l'opération graph_period dans les requêtes, en définissant la période des points en fonction de la largeur temporelle au moment de la création du graphique de sortie.

Dans les graphiques Monitoring, la période de représentation graphique est définie en fonction de la valeur du sélecteur de période du graphique. Par exemple, si vous sélectionnez une période d'une semaine, la période de représentation graphique peut être d'une heure. Cette valeur s'affiche sur un petit encadré avec des angles arrondis, appelé chip, dans la région du graphique. Le chip représentant la période de représentation graphique est associé au libellé 1 hr interval. Sur la capture d'écran suivante, le chip représentant la période de représentation graphique indique un intervalle d'une heure et le sélecteur de temps du graphique est défini sur une semaine :

Le sélecteur de temps du graphique détermine la période de représentation graphique, qui est indiquée par un chip sur le graphique.

La relation entre la période d'alignement de la requête et la période de représentation graphique peut modifier l'apparence du graphique. Cette relation est décrite dans la section suivante.

Bandes minimales/maximales

Lorsque la période d'alignement de la requête est proche de la période de représentation graphique, celui-ci représente graphiquement chaque série temporelle sur une seule ligne. Si la période d'alignement de la requête est inférieure à la moitié de la période de représentation graphique, le graphique inclut une zone ombrée autour de chaque ligne. Cette région, appelée bande minimale/maximale, indique la plage de valeurs ayant généré la valeur moyenne.

Prenons par exemple la requête MQL simple suivante :

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

Cette requête renvoie l'utilisation moyenne du processeur des VM par zone, avec une période d'alignement d'une heure.

Si le sélecteur de temps du graphique est défini sur une semaine, la période de représentation graphique indiquée sur le chip est alors d'une heure. Pour l'exemple de requête, la période de représentation graphique et la période d'alignement sont égales. L'exécution de la requête produit un graphique semblable à celui-ci :

Un graphique en courbes dont les périodes d'alignement et de représentation graphique sont égales n'affiche que des lignes.

Par exemple, si vous remplacez la valeur every par la valeur 1h pour la période d'alignement transmise à l'opération 1m dans la requête précédente, la requête génère un graphique qui inclut les bandes minimales/maximales :

Un graphique en courbes avec une période d'alignement inférieure à la moitié de la période de représentation graphique affiche des lignes et des bandes minimales/maximales.

Les lignes du graphique sont indiquées par une période de représentation graphique d'une heure, en fonction de la période d'une semaine sélectionnée pour le graphique. Par conséquent, les lignes sont identiques à celles de l'exemple précédent. Toutefois, la requête produit un point toutes les minutes, de sorte que les bandes minimales/maximales affichent la plage des valeurs d'une minute de la requête qui sont comprises dans chaque point d'une heure.

Si l'opération every est omise, la période d'alignement de la requête par défaut est soit définie sur la valeur de la fenêtre d'alignement, soit définie sur une minute si la fenêtre d'alignement n'est pas spécifiée.

Règles d'alerte basées sur MQL

Vous pouvez également utiliser MQL et l'éditeur de requête pour créer des requêtes à utiliser dans les règles d'alerte.

Pour créer une règle d'alerte basée sur MQL à partir de Google Cloud Console, suivez la procédure habituelle permettant de créer la règle, décrite sur la page Gérer des règles d'alerte. Cependant, lorsque vous créez la condition pour la règle d'alerte, utilisez l'éditeur de requête au lieu du sélecteur de métriques basé sur un formulaire.

Pour en savoir plus, consultez la section Créer des règles d'alerte MQL.

Convertir une requête

Vous pouvez utiliser le sélecteur de métriques pour les graphiques ou dans l'explorateur de métriques pour créer une requête, puis convertir cette requête en MQL en cliquant sur Éditeur de requête. La requête MQL correspondante est affichée dans l'éditeur.

Prenons une requête très simple, telle que "Obtenir l'utilisation du processeur à partir de mes instances de VM Compute Engine". Cette requête implique le type de ressource surveillée gce_instance et le type de métrique compute.googleapis.com/instance/cpu/usage_time.

La capture d'écran suivante montre cette requête dans le sélecteur de métriques basé sur un formulaire :

Sélectionnez une métrique et un type de ressource dans le sélecteur de métriques

Les types de métriques et de ressources surveillées ont été saisis manuellement. Les valeurs Aligner (Aligneur) et Alignment Period (Durée de l'alignement) sous Advanced Aggregation (Agrégation avancée) sont utilisées par défaut.

Lorsque vous cliquez sur Éditeur de requêtes, la requête exécutée dans le sélecteur de formulaire est convertie en une requête MQL. La capture d'écran suivante montre le résultat de la conversion :

L'éditeur indique le résultat de la conversion des valeurs du formulaire au format MQL.

La requête MQL récupère la série temporelle pour les types de métriques et de ressources spécifiés et effectue un alignement du débit sur des intervalles d'une minute. La requête convertie est au format strict.