PromQL pour les métriques Cloud Monitoring

Vous pouvez utiliser 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 (tel que compute.googleapis.com/) et un chemin d'accès (tel que instance/disk/max_read_ops_count). Comme PromQL n'accepte que les caractères spéciaux : et _, vous devez d'abord rendre ces noms de métriques compatibles avec PromQL en suivant ces deux règles :

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

Le tableau ci-dessous répertorie 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 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 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 :

  1. 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.
  2. Vous pouvez accéder à la section "Configuration" de l'Explorateur de métriques de Cloud Monitoring et saisir le nom de votre métrique. Une liste des types de ressources valides s'affiche, par exemple "VM Instance" (Instance de VM). Si vous sélectionnez votre métrique et accédez à l'onglet MQL, le type de ressource surveillée sous-jacente s'affiche dans le champ fetch, par exemple gce_instance. 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, 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. Une requête correctement formée peut ressembler à ceci :

  • 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 le libellé monitored_resource lorsque cela est nécessaire, l'erreur suivante est renvoyée :

"la métrique est configurée pour être utilisée avec plusieurs types de ressources surveillées ; le sélecteur de série doit spécifier un outil de mise en correspondance des libellés sur le nom de la ressource surveillée"

Autres sujets

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 foo est metadata_system_foo et la syntaxe du libellé de l'utilisateur de métadonnées bar est metadata_user_bar. Une requête correctement formée qui utilise des libellés de métadonnées peut ressembler à ceci :

  • 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, si vous disposez d'un libellé de ressource et d'un libellé de métrique nommé pod_name dans la métrique logging.googleapis.com/user/widget_count, vous pouvez filtrer le libellé de ressource à l'aide de logging_googleapis_com:user_widget_count{pod_name="resource_label_value"} et le libellé de métrique à l'aide de logging_googleapis_com:user_widget_count{metric_pod_name="metric_label_value"}.

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. 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.

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 :

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.