Utiliser l'éditeur de code pour MQL

Cette section décrit les fonctionnalités de l'éditeur de code Langage MQL (Monitoring Query Language) L'éditeur est disponible dans la console Google Cloud et propose des suggestions, des fonctionnalités de détection d'erreurs la prise en charge de la création de 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 : effectuer les opérations suivantes:

1. Dans la console Google Cloud, accédez à la page Explorateur de métriques :

   Accéder à l'explorateur de métriques

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

2. Dans la barre d'outils du volet de création de requêtes, sélectionnez le bouton nommé  MQL ou  PromQL.
3. Vérifiez que MQL est sélectionné dans le bouton d'activation Langage. Le bouton de langage se trouve dans la barre d'outils qui vous permet de mettre en forme votre requête.

La procédure est la même pour 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. 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 votre requête en tant que lorsque vous saisissez du texte, 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 progression entre l'éditeur de code et la région du graphique. Utilisez cette barre pour modifier les tailles relatives des deux régions.

Enregistrer les graphiques

Depuis l'explorateur de métriques

Dans l'éditeur de code de l'Explorateur de métriques, vous avez la possibilité d'enregistrer votre graphique vers 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 cliquez sur Exécuter la requête avant d'enregistrer le graphique. Si vous n'exécutez pas votre requête Tout d'abord, 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 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 cliquez sur Exécuter la requête avant d'enregistrer le graphique. Si vous n'exécutez pas votre requête Tout d'abord, 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, procédez comme suit : Cliquez sur Revenir au widget de sélection 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 lors de l'utilisation de l'éditeur de code, cliquez sur Plus d'options et sélectionnez Voir le format strict.

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

Plages de dates, 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 la requête. La période peut être exprimée implicitement à l'aide de la fonction un sélecteur de période ou de façon explicite 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. Pour Par exemple, si vous souhaitez afficher les données de la semaine précédente, sélectionnez La semaine dernière selon le sélecteur de période. Vous pouvez également spécifier une heure de début et de fin, ou indiquer une heure à voir autour de vous.

Pour en savoir plus sur la création de règles d'alerte avec l'éditeur de code, consultez la page 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 plus d'informations sur la gestion des tableaux de bord et la modification des graphiques, consultez Gérer des 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 est définie en fonction du 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 les graphiques des tableaux de bord, Pour la période du graphique, 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 l'exemple de la requête MQL 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 d'une heure.

Si le sélecteur de temps du graphique est défini sur une semaine, la période du graphique est d'une heure, qui est indiquée sur un chip. 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 modifiez la période d'alignement transmise à every de 1h à 1m dans la requête précédente, la requête produit une graphique qui inclut les bandes min/max:

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 depuis la console Google Cloud, vous suivez la procédure habituelle pour créer la règle, décrite dans Gérer les règles d'alerte, mais lorsque vous créez la condition pour la règle d'alerte, utilisez l'éditeur de code au lieu sélecteur de métriques.

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 intégrée dans un menu en MQL, lorsque vous utilisez la Explorateur de métriques:

1. Dans la barre d'outils du volet de création de requêtes, sélectionnez le bouton nommé  MQL ou  PromQL.
2. Vérifiez que MQL est sélectionné dans le bouton d'activation Langage. Le bouton de langage 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, lors de l'affichage d'un graphique sur 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. Toutes les autres ont leurs valeurs par défaut.

La capture d'écran suivante montre le résultat de la conversion de la requête dans une 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.