PromQL pour Cloud Monitoring

Ce document décrit l'utilisation du langage de requête Prometheus (PromQL) dans Cloud Monitoring. PromQL offre une alternative à l'interface de l'explorateur de métriques, qui est basée sur des menus, pour créer des graphiques et des tableaux de bord.

Vous pouvez utiliser PromQL pour interroger des données Cloud Monitoring et les représenter dans des graphiques à partir des sources suivantes :

Vous pouvez également utiliser des outils comme Grafana pour représenter des données de métriques ingérées sous forme de graphique dans Cloud Monitoring. Les métriques disponibles incluent celles de Managed Service pour Prometheus et celles de Cloud Monitoring indiquées dans les listes des métriques. Pour savoir comment configurer Grafana et d'autres outils basés sur l'API Prometheus, consultez la documentation Managed Service pour Prometheus concernant Grafana.

Vous pouvez également importer vos tableaux de bord Grafana dans Cloud Monitoring.

Interroger des métriques Cloud Monitoring à l'aide de PromQL

Les métriques Cloud Monitoring peuvent être interrogées à l'aide de la spécification UTF-8 pour PromQL. Les noms de métriques UTF-8 doivent être placés entre guillemets et déplacés à l'intérieur des accolades. Les noms de libellés doivent également être mis entre guillemets s'ils contiennent des caractères incompatibles avec l'ancienne version. Pour la métrique Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, les requêtes suivantes sont équivalentes :

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

Les métriques à valeur de distribution Cloud Monitoring peuvent être interrogées comme des histogrammes Prometheus, avec le suffixe _count, _sum ou _bucket ajouté au nom de la métrique.

Vous pouvez utiliser des libellés de métadonnées dans PromQL comme n'importe quel autre libellé, même si les libellés de métadonnées doivent être compatibles avec PromQL. La syntaxe permettant de faire référence à un libellé de système de métadonnées version est metadata_system_version et la syntaxe du libellé de l'utilisateur de métadonnées version est metadata_user_version. Les requêtes PromQL correctement formées qui utilisent des libellés de métadonnées peuvent se présenter comme suit :

  • {"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

Si la clé de libellé de vos métadonnées contient des caractères spéciaux autres que le caractère _, vous devez l'encadrer de guillemets doubles (") conformément à la spécification UTF-8 de PromQL. Vous devez toujours ajouter le préfixe metadata_user_ au libellé de vos métadonnées.

Les graphiques et tableaux de bord créés avant la compatibilité avec UTF-8 interrogent les métriques Cloud Monitoring en convertissant leurs noms en équivalents hérités compatibles avec PromQL. Pour en savoir plus sur les anciennes règles de conversion PromQL, consultez Mapper des métriques Cloud Monitoring à l'ancien PromQL.

Accéder à PromQL dans Cloud Monitoring

Vous pouvez utiliser PromQL depuis l'onglet Code des pages suivantes de la console Google Cloud  :

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

Pour savoir comment accéder à l'éditeur et l'utiliser, consultez Utiliser l'éditeur PromQL.

Règles et alertes PromQL

Vous pouvez utiliser PromQL pour créer des règles d'alerte pour n'importe quelle métrique dans Cloud Monitoring. Pour en savoir plus, consultez Règles d'alerte basées sur PromQL.

Vous pouvez également utiliser PromQL pour créer des règles d'enregistrement et d'alerte sur n'importe quelle métrique dans Cloud Monitoring en utilisant les alertes de style Prometheus dans le cluster dans Cloud Monitoring. Pour en savoir plus, consultez Évaluation et alerte des règles gérées ou Évaluation et alerte des règles auto-déployées.

Formation PromQL

Pour découvrir les principes de base de l'utilisation de PromQL, nous vous recommandons de consulter la documentation Open Source. Les ressources suivantes peuvent vous aider à faire vos premiers pas :

Spécifier un type de ressource surveillée

Lorsqu'une métrique Cloud Monitoring est associée à un seul type de ressource surveillée Cloud Monitoring, les requêtes PromQL fonctionnent sans spécifier manuellement de type de ressource. Cependant, certaines métriques de Cloud Monitoring, y compris certaines métriques système et celles de la plupart générées par des métriques basées sur les journaux, peuvent être mappées à plusieurs types de ressources. Si vous utilisez l'une de ces métriques, en particulier les métriques basées sur les journaux, vous devez spécifier explicitement le type de ressource.

Vous pouvez voir quels types de ressources surveillées sont mappés à une métrique en effectuant l'une des opérations suivantes :

  • Pour les métriques sélectionnées par Google, vous pouvez consulter les listes de métriques disponibles, y compris les métriques Google Cloud et les métriques Kubernetes. Chaque entrée de la documentation répertorie les types de ressources surveillées associés dans la première colonne de chaque entrée sous le type. Si aucun type de ressource surveillée n'est répertorié, la métrique peut être associée à n'importe quel type.

  • L'explorateur de métriques vous permet d'effectuer les opérations suivantes :

    1. Saisissez le nom de votre métrique dans le champ Sélectionner une métrique, puis parcourez les menus pour la sélectionner. Le menu des ressources regroupe les types de ressources valides pour cette métrique, par exemple "Instance de VM".

    2. Dans la barre d'outils du volet de création de requêtes, sélectionnez le bouton nommé < > PromQL.

      La requête PromQL affichée indique le type de ressource comme valeur du champ monitored_resource. En particulier, cette méthode est utile pour les métriques qui peuvent être associées à de nombreux types de ressources surveillées, telles que les métriques basées sur les journaux, les métriques personnalisées ou toute métrique définie par l'utilisateur.

Si une métrique est associée à plusieurs types de ressources, vous devez spécifier le type de ressource dans votre requête PromQL. Il existe un libellé spécial, monitored_resource, que vous pouvez utiliser pour sélectionner le type de ressource.

Les types de ressources surveillées sont dans la plupart des cas une chaîne courte, telle que gce_instance, mais ils apparaissent parfois comme des URI complets, par exemple, monitoring.googleapis.com/MetricIngestionAttribution. Des requêtes PromQL correctement formées peuvent se présenter comme suit :

  • logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
  • custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

La valeur de "" pour le libellé monitored_resource est spéciale et fait référence au type de ressource prometheus_target par défaut utilisé pour les métriques Cloud Monitoring.

Si vous n'utilisez pas l'étiquette monitored_resource lorsqu'il est nécessaire, vous obtenez l'erreur suivante :

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

Résoudre les conflits de libellés

Dans Cloud Monitoring, les libellés peuvent appartenir à la métrique ou à la ressource. Si un libellé de métrique porte le même nom de clé qu'un libellé de ressource, vous pouvez faire référence au libellé de métrique spécifiquement en ajoutant le préfixe metric_ au nom de clé de libellé dans votre requête.

Par exemple, supposons que vous disposiez d'un libellé de ressource et d'un libellé de métrique nommés tous deux pod_name dans la métrique example.googleapis.com/user/widget_count.

  • Pour filtrer sur la valeur du libellé de ressource, utilisez
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • Pour filtrer sur la valeur du libellé de métrique, utilisez
    example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Mapper les noms des métriques Cloud Monitoring à l'ancienne version de PromQL

Les noms de métriques Cloud Monitoring incluent deux composants : un domaine (par exemple, compute.googleapis.com/) et un chemin d'accès (par exemple, instance/disk/max_read_ops_count). Comme l'ancienne version de PromQL n'accepte que les caractères spéciaux : et _, vous devez appliquer les règles suivantes pour rendre les noms de métriques Monitoring compatibles avec l'ancienne version de PromQL :

  • Remplacez la première expression / par :.
  • Remplacez tous les autres caractères spéciaux (y compris . et d'autres caractères /) par _.

Le tableau suivant répertorie certains noms de métriques et leurs équivalents dans l'ancien PromQL :

Nom de la métrique Cloud Monitoring Ancien nom de la métrique PromQL
kubernetes.io/container/cpu/limit_cores kubernetes_io:container_cpu_limit_cores
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count
custom.googleapis.com/opencensus/opencensus.io/
http/server/request_count_by_method		 custom_googleapis_com:opencensus_opencensus_io_
http_server_request_count_by_method
agent.googleapis.com/disk/io_time agent_googleapis_com:disk_io_time

Les métriques à valeur de distribution Cloud Monitoring peuvent être interrogées comme des histogrammes Prometheus, avec le suffixe _count, _sum ou _bucket ajouté au nom de la métrique :

Nom de la métrique Cloud Monitoring Anciens noms de métriques PromQL
networking.googleapis.com/vm_flow/rtt networking_googleapis_com:vm_flow_rtt_sum
networking_googleapis_com:vm_flow_rtt_count
networking_googleapis_com:vm_flow_rtt_bucket

Compatibilité de PromQL

PromQL pour Cloud Monitoring peut fonctionner légèrement différemment de celui de PromQL en amont.

Les requêtes PromQL dans Cloud Monitoring sont partiellement évaluées au niveau du backend Monarch à l'aide d'un langage de requête interne, et il existe des différences connues dans les résultats de la requête. À l'exception des différences mentionnées dans cette section, PromQL dans Cloud Monitoring est identique à celui de PromQL disponible dans la version Prometheus 2.44.

Les fonctions PromQL ajoutées après la version 2.44 de Prometheus peuvent ne pas être compatibles.

Prise en charge d'UTF-8

PromQL pour Cloud Monitoring est compatible avec les requêtes UTF-8.

Si le nom de votre métrique Prometheus ne contient que des caractères alphanumériques ainsi que les caractères _ ou :, et si vos clés de libellé ne contiennent que des caractères alphanumériques ainsi que le caractère _, vous pouvez effectuer des requêtes à l'aide de la syntaxe PromQL traditionnelle. Par exemple, une requête valide peut ressembler à job:my_metric:sum{label_key="label_value"}.

Toutefois, si le nom de votre métrique Prometheus utilise des caractères spéciaux autres que _ ou :, ou si vos clés de libellé utilisent des caractères spéciaux autres que _, vous devez construire votre requête en suivant les spécifications UTF-8 pour PromQL.

Les noms de métriques UTF-8 doivent être placés entre guillemets et entre accolades. Les noms de libellés doivent également être mis entre guillemets s'ils contiennent des caractères incompatibles avec l'ancienne version. Les exemples de requêtes valides suivants sont tous équivalents :

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

Correspondance des noms de métriques

Seule une correspondance exacte avec les noms de métriques est acceptée. Vous devez inclure une correspondance exacte du nom de la métrique dans votre requête.

Nous vous recommandons les solutions de contournement suivantes pour les scénarios courants qui utilisent un outil de correspondance d'expressions régulières sur le libellé __name__ :

  • Les configurations de l'adaptateur Prometheus utilisent souvent l'opérateur =~ pour faire correspondre plusieurs noms de métriques. Pour corriger cette utilisation, développez la configuration afin d'utiliser une règle distincte pour chaque métrique et nommez chaque métrique de manière explicite. Cela vous empêche également d'autoscaler accidentellement sur des métriques inattendues.
  • Les expressions régulières sont souvent utilisées pour représenter graphiquement plusieurs métriques non dimensionnelles sur le même graphique. Par exemple, si vous disposez d'une métrique telle que cpu_servicename_usage, vous pouvez utiliser un caractère générique pour représenter graphiquement tous vos services ensemble. L'utilisation de métriques non dimensionnelles comme celle-ci est une mauvaise pratique explicite dans Cloud Monitoring, qui entraîne des performances de requête extrêmement médiocres. Pour corriger cette utilisation, déplacez toute la dimensionnalité dans les libellés de métriques au lieu d'intégrer les dimensions dans le nom de la métrique.
  • L'interrogation de plusieurs métriques est souvent utilisée pour voir quelles métriques sont disponibles pour l'interrogation. Nous vous recommandons d'utiliser plutôt l'appel /labels/__name__/values pour découvrir les métriques. Vous pouvez également découvrir des métriques à l'aide de l'interface utilisateur Cloud Monitoring.
  • La mise en correspondance de plusieurs métriques est utile pour voir le nombre d'échantillons extraits, ingérés et facturés pour chaque métrique. Cloud Monitoring fournit ces informations sur la page Gestion des métriques. Vous pouvez également accéder à ces informations sous forme de données de métrique à l'aide de la métrique "Échantillons ingérés" ou "Échantillons écrits par ID d'attribution".

Obsolescence

L'obsolescence n'est pas disponible dans le backend Monarch.

Calcul de irate

Lorsque la période d'analyse de la fonction irate est inférieure à la taille de l'étape, nous augmentons cette période à la taille de l'étape. Cette modification est nécessaire dans Monarch afin de s'assurer qu'aucune des données d'entrée n'est complètement ignorée dans le résultat. Cette différence s'applique également aux calculs de rate.

Calcul de rate et increase

Lorsque la période d'analyse de la fonction rate est inférieure à la taille de l'étape, nous augmentons cette période à la taille de l'étape. Cette modification est nécessaire dans Monarch afin de s'assurer qu'aucune des données d'entrée n'est complètement ignorée dans le résultat. Cette différence s'applique également aux calculs de irate.

Il existe des différences dans les calculs d'interpolation et d'extrapolation. Monarch utilise un algorithme d'interpolation différent de celui de Prometheus, et cette différence peut produire des résultats légèrement différents. Par exemple, les échantillons de compteur Monarch sont stockés avec une période, alors que Prometheus utilise un seul horodatage. Par conséquent, les échantillons de compteur Monarch peuvent être inclus dans un calcul de taux, même si l'horodatage Prometheus l'exclut. Cela permet généralement d'obtenir des résultats plus précis, en particulier lorsque vous interrogez le début ou la fin de la série temporelle sous-jacente.

Calcul de histogram_quantile

Un calcul PromQL de histogram_quantile sur un histogramme sans échantillon génère une valeur NaN. Le calcul du langage de requête interne ne produit aucune valeur. Le point à l'horodatage est supprimé à la place.

Les différences de calcul de taux peuvent également affecter l'entrée des requêtes histogram_quantile.

Fonctions spécifiques au type sur les métriques de différents types

Bien que Prometheus en amont soit faiblement typé, Monarch est fortement typé. Cela signifie que l'exécution de fonctions spécifiques à un seul type sur une métrique de type différent (par exemple, l'exécution de rate() sur une métrique GAUGE ou de histogram_quantile() sur une métrique COUNTER ou une métrique non typée) ne fonctionnera pas dans Cloud Monitoring, même si ces fonctions sont compatibles avec Prometheus en amont.