Utiliser PromQL pour les métriques Cloud Monitoring

Vous pouvez utiliser le langage de requête Prometheus (PromQL) pour interroger toutes les métriques dans Cloud Monitoring, y compris les métriques système Google Cloud, les métriques Kubernetes, les métriques personnalisées et les métriques basées sur les journaux.

Mapper les noms des métriques Cloud Monitoring à 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 PromQL n'accepte que les caractères spéciaux : et _, vous devez d'abord rendre les noms de métriques Monitoring compatibles avec PromQL. Pour mapper les noms des métriques Monitoring à PromQL, appliquez les règles suivantes :

• 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 affiche certains noms de métriques et leurs équivalents PromQL :

Nom de la métrique Cloud Monitoring	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	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

Spécifier un type de ressource surveillée

Lorsqu'une métrique 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.

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 sélectionner la métrique. 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é  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 requête affichée indique le type de ressource. En particulier, MQL 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, qui peut être utilisé 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 du service géré pour Prometheus.

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

Utiliser des libellés de métadonnées

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)

Le seul caractère spécial que vous pouvez utiliser dans les clés de libellé de métadonnées est le caractère _. L'agrégation à l'aide de libellés de métadonnées de type MULTI_STRING ou KEY_VALUE n'est pas disponible.

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"}

Autres sujets

Règles et alertes

Vous pouvez utiliser les métriques Cloud Monitoring à la fois dans les règles d'enregistrement et dans les règles d'alerte dans Managed Service pour Prometheus. Pour obtenir des instructions, consultez la section Évaluation et alerte des règles gérées ou Évaluation et alerte des règles auto-déployées.

Remarque : Vous pouvez créer des règles d'alerte Cloud Monitoring basées sur les requêtes PromQL et les règles d'alerte Prometheus. Pour en savoir plus, consultez la page Règles d'alerte avec PromQL.

Formation PromQL

Pour découvrir les principes de base de l'utilisation de PromQL, nous vous recommandons de consulter la documentation Open Source. Voici quelques liens utiles :

• Interroger Prometheus
• Exemples de requêtes
• Aide-mémoire PromQL

Différences PromQL

PromQL pour le service géré pour Prometheus peut fonctionner légèrement différemment de celui de PromQL en amont. Pour obtenir la liste de ces différences, consultez la page Différences PromQL.