Il est possible qu'une partie ou l'ensemble des informations de cette page ne s'appliquent pas au Cloud de confiance S3NS. Pour en savoir plus, consultez Différences par rapport à Google Cloud.

Cette page a été traduite par l'API Cloud Translation.

PromQL pour Cloud Monitoring

Ce document explique comment configurer Grafana pour lire les données de métriques de Cloud Monitoring. Vous pouvez ensuite utiliser PromQL pour visualiser et représenter les données sous forme de graphique. Grafana et Cloud Monitoring sont associés par un processus appelé synchronisateur de sources de données, qui permet la communication entre une source de données Grafana et Cloud Monitoring. Le synchronisateur de sources de données effectue les opérations suivantes :

Envoie des valeurs de configuration à une source de données Grafana.
Conserve les identifiants d'authentification d'un compte de service Trusted Cloud by S3NS pouvant lire les données de métriques de Cloud Monitoring.

Ce document explique comment configurer le synchroniseur de sources de données et fournit des informations spécifiques à l'utilisation de PromQL dans Cloud Monitoring. Dans ce document, nous partons du principe que vous connaissez déjà Grafana.

Autoriser Grafana à lire les données de métriques

Cette section explique comment configurer l'autorisation entre Cloud Monitoring et Grafana à l'aide d'un synchronisateur de sources de données pour générer et synchroniser les identifiants.

Utiliser le synchroniseur de sources de données pour l'autorisation

Les APITrusted Cloud by S3NS nécessitent toutes une authentification via OAuth2. Toutefois, Grafana n'est pas compatible avec l'authentification OAuth2 pour les comptes de service utilisés avec des sources de données Prometheus. Pour utiliser Grafana avec Cloud Monitoring, vous devez utiliser le synchronisateur de sources de données pour générer des identifiants OAuth2 pour votre compte de service et les synchroniser avec Grafana via l'API de source de données Grafana.

Vous devez utiliser le synchronisateur de sources de données pour configurer et autoriser Grafana à interroger des données à l'échelle mondiale. Si vous ne suivez pas ces étapes, Grafana n'exécute des requêtes que sur les données du serveur Prometheus local.

Le synchronisateur de sources de données est un outil d'interface de ligne de commande qui envoie à distance les valeurs de configuration à une source de données Grafana Prometheus spécifiée. Cela garantit que les éléments suivants sont correctement configurés pour votre source de données Grafana :

Authentification, effectuée en actualisant périodiquement un jeton d'accès OAuth2
API Cloud Monitoring définie comme URL du serveur Prometheus
Méthode HTTP définie sur GET
Type et version de Prometheus définis sur 2.40.x comme version minimale
Les valeurs du délai d'expiration HTTP et de la requête sont définies sur 2 minutes

Le synchronisateur de sources de données doit s'exécuter à plusieurs reprises. Comme les jetons d'accès à l'APITrusted Cloud by S3NS ont une durée de vie d'une heure, l'exécution du synchronisateur de source de données toutes les 10 minutes garantit que vous disposez d'une connexion authentifiée ininterrompue entre Grafana et l'API Cloud Monitoring.

Configurer et authentifier la source de données Grafana

Vous pouvez utiliser Grafana pour interroger les données de métriques Cloud Monitoring à partir des services Google Kubernetes Engine ou d'autres environnements. Les instructions utilisent des variables modifiables pour créer des commandes exécutables. Nous vous recommandons vivement d'utiliser les variables modifiables et les icônes de copier-coller cliquables intégrées dans les exemples de code.

GKE

Pour déployer et exécuter le synchronisateur de sources de données dans un cluster Kubernetes, procédez comme suit :

Choisissez un projet, un cluster et un espace de noms dans lesquels déployer le synchronisateur de sources de données.
Ensuite, assurez-vous de bien configurer et autoriser le synchroniseur de sources de données :
- Si vous utilisez Workload Identity Federation for GKE, suivez les instructions pour créer et autoriser un compte de service. Veillez à le lier à l'espace de noms Kubernetes dans lequel vous souhaitez exécuter le synchronisateur de sources de données.
- Si vous n'utilisez pas Workload Identity Federation for GKE, vérifiez que vous n'avez pas modifié le compte de service Compute Engine par défaut.
Déterminez l'URL de votre instance Grafana, par exemple https://yourcompanyname.grafana.net pour un déploiement Grafana Cloud ou http://grafana.NAMESPACE_NAME.svc:3000 pour une instance locale configurée à l'aide du fichier YAML de déploiement de test.

Si vous déployez Grafana localement et que votre cluster est configuré pour sécuriser tout le trafic dans le cluster à l'aide de TLS, vous devez utiliser https:// dans votre URL et vous authentifier à l'aide de l'une des options d'authentification TLS compatibles.
Choisissez la source de données Prometheus Grafana que vous souhaitez utiliser pour Cloud Monitoring, qui peut être une nouvelle source ou une source de données préexistante, puis recherchez et notez l'UID de la source de données. L'UID de la source de données se trouve dans la dernière partie de l'URL lorsque vous explorez ou configurez une source de données. Exemple : https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. Ne pas copier l'intégralité de l'URL de la source de données.. Ne copiez que l'identifiant unique dans l'URL.
Configurez un compte de service Grafana en créant le compte de service et en générant un jeton que le compte utilisera:
1. Dans la barre latérale de navigation Grafana, cliquez sur Administration > Utilisateurs et accès > Comptes de service.
2. Créez le compte de service en cliquant sur Ajouter un compte de service, en lui attribuant un nom et en lui attribuant le rôle "Administrateur" dans Grafana. Si votre version de Grafana autorise des autorisations plus précises, vous pouvez utiliser le rôle Sources de données > Écrivain.
3. Cliquez sur Ajouter un jeton de compte de service.
4. Définissez le délai d'expiration du jeton sur "Aucun délai d'expiration", cliquez sur Générer un jeton, puis copiez le jeton généré dans le presse-papiers pour l'utiliser en tant que GRAFANA_SERVICE_ACCOUNT_TOKEN à l'étape suivante.

Configurez les variables d'environnement suivantes à l'aide des résultats des étapes précédentes :

# These values are required.
PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.
GCM_ENDPOINT_OVERRIDE=--gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

Exécutez la commande suivante pour créer un contrôleur CronJob qui actualise la source de données lors de l'initialisation, puis toutes les 10 minutes : Si vous utilisez Workload Identity Federation for GKE, la valeur de NAMESPACE_NAME doit correspondre au même espace de noms que celui que vous avez précédemment associé au compte de service.

curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' s|$GCM_ENDPOINT_OVERRIDE|'"$GCM_ENDPOINT_OVERRIDE"'|; \
| kubectl -n NAMESPACE_NAME apply -f -

Accédez à la source de données Grafana que vous venez de configurer, puis vérifiez que la valeur de l'URL du serveur Prometheus commence par https://monitoring.s3nsapis.fr. Vous devrez peut-être actualiser la page. Une fois la validation effectuée, accédez au bas de la page et sélectionnez Enregistrer et tester. Vous devez sélectionner ce bouton au moins une fois pour vous assurer que la saisie semi-automatique des étiquettes dans Grafana fonctionne.

Vérifier les identifiants du compte de service

Si Workload Identity Federation for GKE est activé sur votre cluster Kubernetes, vous pouvez ignorer cette section.

Lors de l'exécution sur GKE, Cloud Monitoring récupère automatiquement les identifiants de l'environnement en fonction du compte de service Compute Engine par défaut. Le compte de service par défaut dispose des autorisations nécessaires, monitoring.metricWriter et monitoring.viewer, par défaut. Si vous n'utilisez pas Workload Identity Federation for GKE et que vous avez précédemment supprimé l'un de ces rôles du compte de service de nœud par défaut, vous devrez rajouter ces autorisations manquantes avant de continuer.

Configurer un compte de service pour Workload Identity Federation for GKE

Si Workload Identity Federation for GKE n'est pas activé sur votre cluster Kubernetes, vous pouvez ignorer cette section.

Cloud Monitoring capture les données de métriques à l'aide de l'API Cloud Monitoring. Si votre cluster utilise Workload Identity Federation for GKE, vous devez autoriser votre compte de service Kubernetes à accéder à l'API Monitoring. Cette section décrit les opérations suivantes :

Créer un compte de serviceTrusted Cloud by S3NS dédié, SERVICE_ACCT_NAME.
Associer le compte de service Trusted Cloud au compte de service Kubernetes par défaut dans un espace de noms de test, NAMESPACE_NAME.
Accorder l'autorisation nécessaire au compte de service Trusted Cloud .

Créer et associer le compte de service

Cette étape apparaît à plusieurs endroits de la documentation Cloud Monitoring. Si vous avez déjà effectué cette étape dans le cadre d'une tâche précédente, vous n'avez pas besoin de la répéter. Passez directement à la section Autoriser le compte de service.

La séquence de commandes suivante crée le compte de service SERVICE_ACCT_NAME et l'associe au compte de service Kubernetes par défaut dans l'espace de noms NAMESPACE_NAME :

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create SERVICE_ACCT_NAME \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com

Si vous utilisez un autre espace de noms ou compte de service GKE, ajustez les commandes en conséquence.

Autoriser le compte de service

Les groupes d'autorisations associées sont collectés dans des rôles que vous attribuez à un compte principal, dans cet exemple, le compte de service Trusted Cloud. Pour en savoir plus sur les rôles Monitoring, consultez Contrôle des accès.

La commande suivante accorde au compte de service Trusted Cloud ,SERVICE_ACCT_NAME, les rôles de l'API Monitoring dont il a besoin pour lire les données de métriques.

Si vous avez déjà attribué un rôle spécifique au compte de service Trusted Cloud dans le cadre de la tâche précédente, vous n'avez pas besoin de le faire à nouveau.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

Déboguer votre configuration de Workload Identity Federation for GKE

Si vous rencontrez des difficultés pour utiliser Workload Identity Federation for GKE, consultez la documentation sur la vérification de la configuration de Workload Identity Federation for GKE et le guide de dépannage de Workload Identity Federation for GKE.

Les fautes de frappe et les copier-coller partiels sont les sources d'erreurs les plus courantes lors de la configuration de Workload Identity Federation for GKE. Nous vous recommandons vivement d'utiliser les variables modifiables et les icônes de copier-coller cliquables intégrées dans les exemples de code figurant dans ces instructions.

Workload Identity Federation for GKE dans les environnements de production

L'exemple décrit dans ce document associe le compte de service Trusted Cloud au compte de service Kubernetes par défaut et accorde au compte de service Trusted Cloudtoutes les autorisations nécessaires pour utiliser l'API Monitoring.

Dans un environnement de production, vous pouvez utiliser une approche plus précise, avec un compte de service pour chaque composant, chacun disposant d'autorisations minimales. Pour en savoir plus sur la configuration des comptes de service pour la gestion des identités de charge de travail, consultez la section Utiliser Workload Identity Federation for GKE.

Ailleurs

Pour déployer et exécuter le synchronisateur de sources de données dans des environnements autres que Google Kubernetes Engine, procédez comme suit :

Configurez un compte de service à utiliser avec le synchronisateur de sources de données :

Définissez le projet par défaut pour les commandes gcloud :
```
gcloud config set project PROJECT_ID
```
Créez un compte de service à utiliser avec le synchronisateur de sources de données :
```
gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME
```

Accordez au compte de service l'autorisation de lire les données de métriques :

 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
 --role=roles/monitoring.viewer \
 && \
 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
 --role=roles/iam.serviceAccountTokenCreator

Créez une clé pour le compte de service :
```
gcloud iam service-accounts keys create DS_SYNCER_SVCACCT_KEYFILE_NAME.json \
--iam-account DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com
```
Le chemin d'accès à ce répertoire est utilisé pour définir une variable d'environnement à une étape ultérieure. Pour obtenir le chemin d'accès, exécutez la commande pwd et notez la valeur :
```
pwd
DS_SYNCER_SVCACCT_KEYFILE_DIR
```

Déterminez l'URL de votre instance Grafana, par exemple https://yourcompanyname.grafana.net pour un déploiement Grafana Cloud ou https://localhost:3000 pour une instance de test locale. Cette valeur est utilisée dans la commande permettant d'exécuter le synchroniseur de sources de données.

Si vous déployez Grafana localement pour un cluster Kubernetes configuré pour sécuriser tout le trafic dans le cluster à l'aide de TLS, vous devez utiliser https:// dans votre URL et, à l'étape suivante, vous authentifier à l'aide de l'une des options d'authentification TLS compatibles.
Dans Grafana, ajoutez une source de données Prometheus à utiliser pour Cloud Monitoring, puis enregistrez l'UID de la source de données :
1. Cliquez sur Connexions > Sources de données > Ajouter une source de données. Sélectionnez Prometheus dans la liste des bases de données de séries temporelles.
2. Dans le champ URL du serveur Prometheus, saisissez la valeur suivante :
```
https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
```
3. Cliquez sur Enregistrer et tester.
  
  L'URL de la page de la source de données dans le navigateur contient l'UI de la source de données, par exemple https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID..
4. Notez l'UID de la source de données. Cette valeur est utilisée dans la commande permettant d'exécuter le synchroniseur de sources de données. Ne copiez pas l'URL complète de la source de données. Ne copiez que l'identifiant unique dans l'URL, qui est une valeur telle que ee0z3woqjah34e :
```
GRAFANA_DATASOURCE_UID
```
Configurez un compte de service Grafana en créant le compte de service et en générant un jeton que le compte de service utilisera :
1. Dans la barre latérale de navigation Grafana, cliquez sur Administration > Utilisateurs et accès > Comptes de service.
2. Créez le compte de service en cliquant sur Ajouter un compte de service, en lui attribuant un nom et en lui attribuant le rôle "Administrateur" dans Grafana.
3. Cliquez sur Ajouter un jeton de compte de service.
4. Définissez le délai d'expiration du jeton sur "Aucun délai d'expiration", cliquez sur Générer un jeton, puis copiez le jeton généré dans la variable modifiable suivante. Cette valeur est utilisée dans la commande permettant d'exécuter le synchroniseur de sources de données.
```
GRAFANA_SERVICE_ACCOUNT_TOKEN
```
Exécutez le synchronisateur de sources de données. Vous pouvez exécuter le synchroniseur à partir d'une image de conteneur prédéfinie à l'aide de Docker, ou compiler le code à partir de la source et l'exécuter manuellement. Le synchronisateur de sources de données est une application Go. Vous devez donc avoir installé Go pour compiler le synchronisateur à partir de la source.
Docker

Exécutez le synchroniseur de sources de données à partir de Docker en utilisant l'image de conteneur gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0. Pour les tests, vous pouvez exécuter le synchroniseur manuellement. Une fois que vous avez vérifié que la connexion fonctionne, vous devez utiliser un mécanisme automatisé tel qu'une job Cron pour exécuter le synchroniseur de source de données toutes les 10 minutes, car les jetons d'accès ont une durée de vie d'une heure. Cela permet de garantir que votre connexion n'est pas interrompue.

Exécutez la commande Docker suivante pour exécuter le synchronisateur de sources de données :
```
docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/DS_SYNCER_SVCACCT_KEYFILE_NAME.json" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0
-datasource-uids=UID_OF_GRAFANA_DATASOURCE
-grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
-grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
-project-id=PROJECT_ID
-query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
-gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
```
Pour créer un job cron afin d'exécuter le synchronisateur de sources de données, procédez comme suit :
1. Modifiez la table cron :
  cron -e
2. Ajoutez une entrée qui exécute la commande précédente toutes les 10 minutes :
  */10 * * * * * docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/<KEY_ID>" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
Pour en savoir plus sur les options de ligne de commande disponibles lors de l'exécution du synchroniseur de sources de données, consultez le document README.
Code source
1. Pour créer vous-même le synchronisateur de sources de données :
  1. Créez un répertoire pour contenir le code et accédez-y :
    
    mkdir data-source-syncer-code cd data-source-syncer-code
    
    Le chemin d'accès à ce répertoire est utilisé pour définir une variable d'environnement à une étape ultérieure. Pour obtenir le chemin d'accès, exécutez la commande pwd et enregistrez-le dans la variable modifiable :
    
    pwd PATH_TO_LOCAL_REPO_COPY
  2. Clonez le code à partir de la version actuelle du dépôt :
    
    git clone -b 'v0.15.3' --single-branch https://github.com/GoogleCloudPlatform/prometheus-engine
  3. Accédez au répertoire datasource-syncer et compilez le code :
    
    cd prometheus-engine/cmd/datasource-syncer go build main.go
2. Exécutez le synchronisateur de sources de données. Pour les tests, vous pouvez exécuter le synchroniseur manuellement. Une fois que vous avez vérifié que la connexion fonctionne, vous devez utiliser un mécanisme automatisé tel qu'un job cron pour exécuter le synchronisateur de source de données toutes les 10 minutes. En effet, les jetons d'accès ont une durée de vie d'une heure. Vous vous assurez ainsi que votre connexion est ininterrompue.
  
  Utilisez la commande suivante pour exécuter manuellement le synchronisateur de sources de données :
  main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  Pour créer un job cron afin d'exécuter le synchronisateur de sources de données, procédez comme suit :
  1. Modifiez la table cron :
    
    cron -e
  2. Ajoutez une entrée qui exécute la commande précédente toutes les 10 minutes :
    
    */10 * * * * * main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  Pour en savoir plus sur les options de ligne de commande disponibles lors de l'exécution du synchroniseur de sources de données, consultez le document README.
Accédez à la source de données Grafana que vous venez de configurer, puis vérifiez que la valeur de l'URL du serveur Prometheus commence par https://monitoring.s3nsapis.fr. Vous devrez peut-être actualiser la page. Une fois la validation effectuée, accédez au bas de la page et cliquez sur Enregistrer et tester. Vous devez cliquer sur ce bouton au moins une fois pour vous assurer que la saisie semi-automatique des étiquettes dans Grafana fonctionne.

Afficher les métriques dans Grafana

Pour afficher les métriques de votre projet Trusted Cloud dans Grafana, procédez comme suit :

Cliquez sur Explorer dans le panneau de navigation ou sur la page Sources de données.
Dans le champ Métrique, utilisez le menu déroulant pour sélectionner une métrique. Vous pouvez également sélectionner Explorateur de métriques pour rechercher des métriques spécifiques. Si la métrique est associée à plusieurs ressources surveillées, vous devez ajouter un filtre de libellé monitored_resource à votre requête et sélectionner un type de ressource.
Ajoutez d'autres filtres et opérations de libellé pour construire votre requête.

Pour savoir comment créer des visualisations et des tableaux de bord dans Grafana, consultez Panels and visualizations.

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 placés 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.

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.

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, peuvent être mappées à plusieurs types de ressources.

Vous pouvez voir quels types de ressources surveillées sont mappés à une métrique en consultant la liste des métriquesTrusted Cloud by S3NS . 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.

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"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

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
`compute.googleapis.com/instance/cpu/utilization`	`compute_googleapis_com:instance_cpu_utilization`
`logging.googleapis.com/log_entry_count`	`logging_googleapis_com:log_entry_count`

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.

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.