Utiliser l'éditeur de code pour MQL

Cette section décrit les fonctionnalités de l'éditeur de code pour le langage MQL (Monitoring Query Language). L'éditeur est disponible dans la console Google Cloud. Il fournit des suggestions, des fonctionnalités de détection d'erreurs et d'autres fonctionnalités pour 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 code

Pour accéder à l'éditeur de code lorsque vous utilisez l'Explorateur de métriques, procédez comme suit:

1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Monitoring, puis  Explorateur de métriques :

   Accéder à l'Explorateur de métriques

2. Dans la barre d'outils du volet du générateur de requêtes, sélectionnez le bouton dont le nom est  MQL ou  PromQL.
3. Vérifiez que MQL est sélectionné dans le bouton Langage. Le bouton d'activation/de désactivation de la langue se trouve dans la barre d'outils qui vous permet de mettre en forme votre requête.

Les étapes similaires permettent d'accéder à l'éditeur de code lorsque vous créez un graphique sur un tableau de bord.

Utiliser l'éditeur de code

Pour utiliser l'éditeur de code, saisissez votre requête dans la zone de texte, puis cliquez sur Run Query (Exécuter la 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:

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é:

Commandes de l'éditeur

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

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 code pour qu'il exécute automatiquement la 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, cliquez sur le bouton 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 code ne tente pas d'évaluer les requêtes incomplètes.

Il existe également une barre de raccourci entre l'éditeur de code et la zone du graphique. Utilisez cette barre pour modifier les tailles relatives des deux régions.

Enregistrer les graphiques

Depuis l'explorateur de métriques

À partir de l'éditeur de code 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 Exécuter la requête avant d'enregistrer le graphique. Si vous n'exécutez pas d'abord votre requête, l'éditeur de code 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 Exécuter la requête avant d'enregistrer le graphique. Si vous n'exécutez pas d'abord votre requête, l'éditeur de code 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 code

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

Afficher les requêtes au format strict

Pour afficher une requête au format strict lorsque vous utilisez l'éditeur de code, cliquez sur Plus d'options, puis sélectionnez Voir le format strict.

Pour en savoir plus, consultez la section Requêtes de format strict.

Périodes, graphiques et éditeur de code

À l'exception des requêtes MQL utilisées dans les conditions des règles d'alerte, les requêtes MQL dans l'éditeur de code 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 à l'aide du sélecteur de période du graphique ou explicitement dans le texte de votre requête MQL.

Par défaut, le sélecteur de période est défini sur une heure.

Pour modifier la période d'un graphique, utilisez le sélecteur de période. Par exemple, si vous souhaitez afficher les données de la semaine passée, sélectionnez La semaine dernière dans le sélecteur de période. Vous pouvez également spécifier une heure de début et de fin, ou une heure à afficher.

Pour en savoir plus sur la création de règles d'alerte avec l'éditeur de code, 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.

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 de graphiques, consultez la page Gérer les tableaux de bord personnalisés.

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 du graphique est définie en fonction de la valeur du sélecteur de période du graphique et du nombre maximal de points qu'un graphique peut afficher. Par exemple, si vous sélectionnez une période d'une semaine, la période de représentation graphique peut être d'une heure. Pour afficher la période d'un graphique dans un tableau de bord, cliquez sur Statistiques sur la requête.

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 :

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 :

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 code 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 la console Google Cloud, suivez la procédure habituelle de création de la règle, décrite dans la section Gérer les règles d'alerte. Toutefois, lorsque vous créez la condition pour la règle d'alerte, vous utilisez l'éditeur de code au lieu du sélecteur de métriques basé sur le 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 la convertir en MQL. La requête MQL correspondante est affichée dans l'éditeur.

Pour convertir une requête composée d'un menu en MQL, lorsque vous utilisez l'Explorateur de métriques, procédez comme suit:

1. Dans la barre d'outils du volet du générateur de requêtes, sélectionnez le bouton dont le nom est  MQL ou  PromQL.
2. Vérifiez que MQL est sélectionné dans le bouton Langage. Le bouton d'activation/de désactivation de la langue se trouve dans la barre d'outils qui vous permet de mettre en forme votre requête.

Pour convertir une requête basée sur un formulaire en MQL, lorsque vous consultez un graphique dans un tableau de bord, cliquez sur MQL.

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 :

Les types de métriques et de ressources surveillées ont été saisis manuellement. Tous les autres champs ont leurs valeurs par défaut.

La capture d'écran suivante montre le résultat de la conversion de la sélection basée sur un formulaire en requête 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.

Remarque :Vous ne pouvez pas reconvertir la représentation MQL en paramètres dans le sélecteur de métriques basé sur un formulaire. MQL accepte les requêtes que vous ne pouvez pas créer avec le sélecteur de métriques. Lorsque vous quittez l'éditeur de code, le texte de votre requête est supprimé si vous ne l'enregistrez pas.