Écrire des métriques Prometheus à l'aide du side-car Prometheus

Le side-car Managed Service pour Prometheus pour Cloud Run est la méthode recommandée par Google pour obtenir une surveillance de type Prometheus pour les services Cloud Run. Si votre service Cloud Run écrit des métriques OTLP, vous pouvez utiliser le side-car OpenTelemetry. Toutefois, pour les services qui écrivent des métriques Prometheus, utilisez le side-car Managed Service pour Prometheus décrit dans ce document.

Cette page explique comment effectuer les opérations suivantes :

• Ajoutez le side-car Managed Service pour Prometheus à un service Cloud Run existant.
• Créez une application exemple avec le side-car. Vous pouvez utiliser l'application exemple pour voir comment fonctionne le side-car si vous ne disposez pas d'un service Cloud Run.

Le side-car utilise Google Cloud Managed Service pour Prometheus côté serveur et une distribution d'OpenTelemetry Collector, personnalisée pour les charges de travail sans serveur, côté client. Cette distribution personnalisée inclut des modifications pour assurer la compatibilité avec Cloud Run. Le collecteur effectue une récupération de démarrage après 10 secondes et effectue une scrape d'arrêt, quelle que soit la durée de vie de l'instance. Pour une fiabilité maximale, nous recommandons que les services Cloud Run exécutant le side-car utilisent également un processeur toujours alloué. Pour en savoir plus, consultez la section Allocation de processeurs (services). Certaines tentatives de scraping peuvent échouer si l'allocation de processeurs est limitée en raison d'un faible nombre de requêtes par seconde (RPS). Un processeur toujours alloué reste disponible.

Le side-car s'appuie sur la fonctionnalité de multiconteneur Cloud Run (side-car) pour exécuter le collecteur en tant que conteneur side-car avec votre conteneur de charge de travail. Pour en savoir plus sur les side-cars dans Cloud Run, consultez la page Déployer plusieurs conteneurs sur un service (side-cars).

Le side-car Managed Service pour Prometheus pour Cloud Run introduit une nouvelle configuration, RunMonitoring, un sous-ensemble de la ressource personnalisée PodMonitoring de Kubernetes. La plupart des utilisateurs peuvent utiliser la configuration RunMonitoring par défaut, mais vous pouvez également créer des configurations personnalisées. Pour en savoir plus sur les configurations RunMonitoring par défaut et personnalisées, consultez la page Ajouter le side-car à un service Cloud Run.

Avant de commencer

Cette section décrit la configuration nécessaire pour utiliser ce document.

Installer et configurer gcloud CLI

La plupart des étapes décrites dans ce document utilisent Google Cloud CLI. Pour en savoir plus sur l'installation de gcloud CLI, consultez la page Gérer les composants de Google Cloud CLI.

Lorsque vous appelez des commandes gcloud, vous devez spécifier l'identifiant de votre projet Google Cloud. Vous pouvez définir un projet par défaut pour Google Cloud CLI et éliminer le besoin de le saisir à chaque commande. Pour définir votre projet par défaut, saisissez la commande suivante :

gcloud config set project PROJECT_ID

Vous pouvez également définir une région par défaut pour votre service Cloud Run. Pour définir une région par défaut, saisissez la commande suivante :

gcloud config set run/region REGION

Activer les API

Vous devez activer les API suivantes dans votre projet Google Cloud :

• API Cloud Run Admin : run.googleapis.com
• API Artifact Registry : artifactregistry.googleapis.com
• API Cloud Monitoring : monitoring.googleapis.com
• API Cloud Logging : logging.googleapis.com
• (Facultatif) Si vous créez une configuration RunMonitoring personnalisée, vous devez activer l'API Secret Manager : secretmanager.googleapis.com
• (Facultatif) Si vous choisissez d'exécuter l'exemple d'application à l'aide de Cloud Build, vous devez également activer les API suivantes :
  • API Cloud Build : cloudbuild.googleapis.com.
  • API Identity and Access Management : iam.googleapis.com. Pour en savoir plus, consultez la page Créer et exécuter l'exemple d'application.

Pour afficher les API activées dans votre projet, exécutez la commande suivante :

gcloud services list

Pour activer une API qui n'est pas activée, exécutez l'une des commandes suivantes :

gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable iam.googleapis.com

Compte de service pour Cloud Run

Par défaut, les tâches et les services Cloud Run utilisent le compte de service Compute Engine par défaut, PROJECT_NUMBER-compute@developer.gserviceaccount.com. Ce compte de service dispose généralement des rôles IAM (Identity and Access Management) nécessaires pour écrire les métriques et les journaux décrits dans ce document :

• roles/monitoring.metricWriter
• roles/logging.logWriter

Si vous créez une configuration RunMonitoring personnalisée, votre compte de service doit également disposer des rôles suivants :

• roles/secretmanager.admin
• roles/secretmanager.secretAccessor

Vous pouvez également configurer un compte de service géré par l'utilisateur pour Cloud Run. Un compte de service géré par l'utilisateur doit également disposer de ces rôles. Pour en savoir plus sur les comptes de service pour Cloud Run, consultez la page Configurer l'identité du service.

Configurer et ajouter le side-car à un service Cloud Run

Le side-car Managed Service pour Prometheus pour Cloud Run introduit une nouvelle configuration, RunMonitoring, un sous-ensemble de la ressource personnalisée PodMonitoring de Kubernetes. La configuration RunMonitoring utilise les options PodMonitoring existantes pour prendre en charge Cloud Run tout en éliminant certaines options spécifiques à Kubernetes.

Vous pouvez utiliser la configuration RunMonitoring par défaut ou créer une configuration personnalisée. Les sections suivantes décrivent ces deux approches. Il est inutile de supprimer l'association dans les deux outils. Pour plus d'informations sur l'utilisation des configurations par défaut ou personnalisées, sélectionnez l'onglet correspondant.

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: run-gmp-sidecar
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 30s

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
+       run.googleapis.com/container-dependencies: '{"collector":["app"]}'
    spec:
      containers:
      - image: "REGION-docker.pkg.dev/PROJECT_ID/run-gmp/sample-app"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
+     - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.2.0"
+       name: collector

gcloud run services replace run-service.yaml --region=REGION

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: my-custom-cloud-run-job
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 10s
    metricRelabeling:
    - action: replace
      sourceLabels:
      - __address__
      targetLabel: label_key
      replacement: label_value
  targetLabels:
    metadata:
    - service
    - revision

gcloud secrets create mysecret --data-file=custom-config.yaml

gcloud secrets versions add mysecret --data-file=custom-config-updated.yaml

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
+       run.googleapis.com/container-dependencies: '{"collector":["app"]}'
+       run.googleapis.com/secrets: 'mysecret:projects/PROJECT_ID/secrets/mysecret'
    spec:
      containers:
      - image: "REGION-docker.pkg.dev/PROJECT_ID/run-gmp/sample-app"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
+     - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.2.0"
+       name: collector
+       volumeMounts:
+       - mountPath: /etc/rungmp/
+         name: config
+     volumes:
+     - name: config
+       secret:
+         items:
+         - key: latest
+           path: config.yaml
+         secretName: 'mysecret'

gcloud run services replace run-service.yaml --region=REGION

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: my-custom-cloud-run-job
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 10s
    metricRelabeling:
    - action: replace
      sourceLabels:
      - __address__
      targetLabel: label_key
      replacement: label_value
  targetLabels:
    metadata:
    - service
    - revision

Créer et exécuter une application exemple

Cette section décrit comment exécuter le service side-car de Managed Service pour Prometheus avec une application exemple. Cette section est facultative. Si vous disposez déjà d'un service Cloud Run et que vous souhaitez le déployer avec le side-car, consultez la section Ajouter le side-car Managed Service pour Prometheus à un service Cloud Run.

Cloner le dépôt run-gmp-sidecar

Pour obtenir l'application exemple et ses fichiers de configuration, clonez le dépôt run-gmp-sidecar en exécutant la commande suivante :

git clone https://github.com/GoogleCloudPlatform/run-gmp-sidecar/

Après avoir cloné le dépôt, accédez au répertoire run-gmp-sidecar :

cd run-gmp-sidecar

Créer et exécuter l'application exemple

L'application exemple nécessite Docker ou un système de compilation de conteneurs similaire pour Linux. Vous pouvez créer et exécuter l'application exemple de l'une des manières suivantes :

• Utilisez Cloud Build pour exécuter une application sans compatibilité Docker locale. Si vous utilisez Cloud Build, vous devez également activer l'API Cloud Build.
• Créer et exécuter l'application exemple manuellement

Les sections suivantes décrivent ces deux approches. Il est inutile de supprimer l'association dans les deux outils. Pour plus d'informations, sélectionnez l'onglet correspondant à l'une des approches.

./create-sa-and-ar.sh

gcloud builds submit . --config=cloudbuild-simple.yaml --region=REGION

Logs are available at [
https://console.cloud.google.com/cloud-build/builds/637860fb-7a14-46f2-861e-09c1dc4cea6b?project=PROJECT_NUMBER].

gcloud run services describe my-cloud-run-service --region=REGION --format="value(status.url)"

https://my-cloud-run-service-abcdefghij-ue.a.run.app

export GCP_PROJECT=PROJECT_ID
export REGION=REGION

gcloud artifacts repositories create run-gmp \
    --repository-format=docker \
    --location=${REGION}

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
        run.googleapis.com/container-dependencies: '{"collector":["app"]}'
    spec:
      containers:
      - image: "%SAMPLE_APP_IMAGE%"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
      - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.2.0"
        name: collector

sed -i s@%SAMPLE_APP_IMAGE%@REGION-docker.pkg.dev/${GCP_PROJECT}/run-gmp/sample-app@g run-service-simple.yaml

gcloud run services replace run-service-simple.yaml --region=REGION
   

https://my-cloud-run-service-abcdefghij-ue.a.run.app

gcloud run services set-iam-policy my-cloud-run-service policy.yaml --region=REGION

Vérifier que votre application est en cours d'exécution

Pour vérifier que le service Cloud Run a correctement exécuté l'exemple d'application, utilisez l'utilitaire curl pour accéder au point de terminaison metrics du service.

1. Définissez la variable d'environnement SERVICE_URL sur l'URL du service Cloud Run de l'étape précédente :

   export SERVICE_URL=SERVICE_URL
   

2. Envoyez une requête à l'URL du service en exécutant la commande suivante :

   curl $SERVICE_URL
   

Si votre application a démarré correctement, la réponse suivante s'affiche :

User request received!

Afficher les métriques de l'application dans l'explorateur de métriques

L'exemple de conteneur app écrit les métriques suivantes :

• foo_metric : heure actuelle sous forme de valeur à virgule flottante (jauge).
• bar_metric : heure actuelle sous forme de valeur à virgule flottante (compteur).

Pour afficher ces métriques dans l'explorateur de métriques, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page leaderboardExplorateur 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 Monitoring.

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

3. Vérifiez que PromQL 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.

4. Saisissez la requête suivante dans le volet de l'éditeur :

   foo_metric
   

5. Cliquez sur Ajouter une requête.

6. Dans la barre d'outils du volet de création de requêtes, sélectionnez le bouton nommé code MQL ou code PromQL.

7. Vérifiez que PromQL 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.

8. Saisissez la requête suivante dans le deuxième volet de l'éditeur :

   bar_metric
   

9. Cliquez sur Exécuter la requête.

10. Pour afficher les détails des métriques, cliquez sur le bouton Créer un tableau des graphiques dans la liste, puis sélectionnez Les deux.

Effectuer un nettoyage

Lorsque vous avez terminé de tester l'exemple d'application, vous pouvez utiliser le script clean-up-cloud-run.sh du dépôt run-gmp-sidecar pour supprimer les ressources suivantes que vous avez créées pour l'exemple :

• Le service Cloud Run.
• Le dépôt Artifact Registry.
• Le compte de service créé pour Cloud Build.

La suppression de ces ressources garantit que vous n'engendrez pas de coûts après l'exécution de l'exemple.

Pour nettoyer l'exemple d'application, exécutez le script clean-up-cloud-run.sh :

./clean-up-cloud-run.sh

Afficher les métriques automatiques dans l'explorateur de métriques

Le side-car Managed Service pour Prometheus signale les métriques suivantes à son sujet à Cloud Monitoring :

• agent_uptime : temps d'activité du collecteur side-car (compteur).
• agent_memory_usage : mémoire utilisée par le collecteur side-car (jauge).
• agent_api_request_count : nombre de requêtes API du collecteur side-car (compteur).
• agent_monitoring_point_count : nombre de points de métriques écrits dans Cloud Monitoring par le collecteur side-car (compteur).

Pour afficher les métriques automatiques du side-car dans l'explorateur de métriques, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page leaderboardExplorateur 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 Monitoring.

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

3. Vérifiez que PromQL 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.

4. Saisissez le nom de la métrique que vous souhaitez interroger dans le volet de l'éditeur, par exemple :

   agent_api_request_count
   

5. Cliquez sur Exécuter la requête.

6. Pour afficher les détails des métriques, cliquez sur le bouton Créer un tableau des graphiques dans la liste, puis sélectionnez Les deux.

Afficher les journaux automatiques dans l'explorateur de journaux

Le side-car Managed Service pour Prometheus écrit des journaux dans Cloud Logging. Le side-car écrit les journaux par rapport au type de ressource surveillée cloud_run_revision.

Pour afficher les journaux du side-car dans l'explorateur de journaux, procédez comme suit :

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

   Accéder à l'explorateur de journaux

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

2. Sélectionnez le type de ressource Révision dans Cloud Run, ou saisissez la requête suivante et cliquez sur Exécuter la requête :

   resource.type="cloud_run_revision"
   

À propos des métriques collectées

Lorsque les métriques émises par le side-car sont ingérées dans Cloud Monitoring, elles sont écrites par rapport au type de ressource surveillée prometheus_target de Cloud Monitoring. Ce type de ressource est utilisé à la fois pour les métriques d'application et pour les métriques automatiques du side-car.

Lors de l'écriture des métriques, le side-car définit les libellés de ressources comme suit :

• project_id : ID du projet Google Cloud dans lequel le conteneur est exécuté.
• location : région Google Cloud dans laquelle le conteneur est exécuté.
• cluster : la valeur __run__.
• namespace : nom du service Cloud Run en cours d'exécution. Il provient de la variable d'environnement K_SERVICE.
• job : nom issu de la configuration RunMonitoring ; Valeur par défaut : run-gmp-sidecar.
• instance : valeur faas.ID:PORT de la charge de travail locale à partir de laquelle le conteneur est configuré pour extraire des métriques. La valeur faas.ID correspond à l'ID de l'instance Cloud Run.

Le side-car ajoute également les libellés de métriques suivants :

• instanceId : ID de l'instance Cloud Run.
• service_name : nom du service Cloud Run en cours d'exécution.
• revision_name : nom de la révision Cloud Run en cours d'exécution.
• configuration_name : nom de la configuration Cloud Run en cours d'exécution.

Ces libellés de métrique sont tous ajoutés par défaut. Si vous utilisez une configuration RunMonitoring personnalisée, vous pouvez omettre les libellés service_name, revision_name et configuration_name en utilisant les Option targetLabels dans la spécification RunMonitoring. Vous pouvez également utiliser une configuration personnalisée pour modifier les étiquettes des libellés service_name, revision_name et configuration_name.

Tous les autres libellés qui apparaissent avec des métriques ingérées proviennent de votre métrique. Si un libellé défini par l'utilisateur est en conflit avec l'un des libellés fournis par le système, il est précédé de la chaîne exported_. Par exemple, un libellé spécifié par l'utilisateur namespace="playground" entre en conflit avec le libellé namespace défini par le système. Le libellé utilisateur apparaît donc comme exported_namespace="playground".

Type de métrique

Lorsque les métriques émises par le side-car sont ingérées dans Cloud Monitoring, elles sont écrites en tant que métriques prometheus.googleapis.com et le type de la métrique Prometheus est ajouté à la fin du nom. Par exemple, l'exemple d'application émet une métrique de jauge Prometheus nommée foo_metric. Dans Cloud Monitoring, la métrique est stockée en tant que type de métrique prometheus.googleapis.com/foo_metric/gauge.

Lorsque vous interrogez la métrique avec PromQL, vous pouvez utiliser le nom Prometheus, comme illustré dans les sections Afficher les métriques d'application dans l'explorateur de métriques et Afficher les métriques automatiques dans l'explorateur de métriques. Lorsque vous utilisez des outils tels que le générateur de requêtes ou le langage MQL (Monitoring Query Language) dans l'explorateur de métriques, le type de métrique Cloud Monitoring est pertinent.

Facturation

Les métriques émises par le side-car sont ingérées dans Cloud Monitoring avec le préfixe prometheus.googleapis.com. Les métriques comportant ce préfixe sont facturées en fonction du nombre d'échantillons ingérés. Pour en savoir plus sur la facturation et le service géré pour Prometheus, consultez la page Facturation.