Configurer un champ d'application de métriques à l'aide de l'API

Ce document explique comment utiliser la Google Cloud CLI ou l'API Cloud Monitoring pour configurer le champ d'application des métriques d'un projet Google Cloud. Cette page est destinée aux développeurs et aux administrateurs système.

Champs d'application des applications et des métriques App Hub

Vous gérez le champ d'application des métriques pour les projets hôtes App Hub. Vous pouvez gérer cette portée à l'aide de la console Google Cloud ou de l'API Cloud Monitoring.

Google Cloud gère le champ d'application des métriques pour les dossiers compatibles avec les applications, sauf si l'ajout d'un projet au champ d'application des métriques échoue en raison de l'épuisement du quota du champ d'application des métriques. Dans ce cas, vous pouvez demander une augmentation de quota, puis ajouter manuellement des projets au champ d'application des métriques du projet de gestion du dossier activé par l'application. Pour en savoir plus, consultez la section Champs d'application des métriques pour les dossiers compatibles avec les applications.

Avant de commencer

  • Si vous ne connaissez pas les termes champ d'application des métriques et projet de champ d'application, consultez la section champs d'application des métriques.

  • Assurez-vous que vos rôles IAM (Identity and Access Management) sur le projet de champ d'application et sur chaque projet que vous souhaitez ajouter en tant que projet surveillé incluent toutes les autorisations du rôle Administrateur de surveillance (roles/monitoring.admin). Pour en savoir plus, consultez la section Configurations de champ d'application des métriques.

  • Les méthodes de champ d'application des métriques de l'API Cloud Monitoring qui récupèrent des informations sont synchrones. Cependant, ces API qui changent d'état sont asynchrones. Les commandes Google Cloud CLI sont bloquées jusqu'à la fin de l'opération asynchrone. Pour savoir comment déterminer lorsqu'une méthode d'API asynchrone est terminée et déterminer son état, consultez la page Méthodes d'API asynchrones.

  • Si vous prévoyez d'appeler l'API Cloud Monitoring à l'aide de curl ou si vous souhaitez utiliser les exemples de cette page, suivez la procédure de configuration de la commande curl.

Ajouter un projet à un champ d'application des métriques

gcloud

Pour ajouter un projet Google Cloud à un champ d'application des métriques, exécutez la commande gcloud beta monitoring metrics-scopes create:

gcloud beta monitoring metrics-scopes create MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

Avant d'exécuter la commande précédente, procédez comme suit:

  • Saisissez le nom ou l'ID du projet Google Cloud dont le champ d'application des métriques doit être modifié dans la variable SCOPING_PROJECT_ID_OR_NUMBER. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion du dossier compatible avec les applications.

  • Saisissez l'identifiant de votre projet surveillé dans la variable MONITORED_PROJECT_ID_OR_NUMBER. Il a le format suivant : projects/PROJECT_ID_OR_NUMBER.

Par exemple, la commande suivante ajoute le projet my-monitored-project au champ d'application des métriques du projet nommé my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

La réponse à la commande précédente confirme que la commande a bien abouti:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

Pour ajouter un projet Google Cloud à un champ d'application des métriques, envoyez une requête POST au point de terminaison locations.global.metricsScopes.projects.create:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

Dans l'exemple précédent, les variables d'environnement sont définies comme suit:

  • MONITORED_PROJECT_ID_OR_NUMBER stocke l'ID du projet à ajouter au champ d'application des métriques.
  • SCOPING_PROJECT_ID_OR_NUMBER stocke l'ID du projet dont le champ d'application des métriques est mis à jour.

La réponse de cette méthode asynchrone est un objet Operation.

Les applications appelant cette méthode doivent interroger le point de terminaison operation.get jusqu'à ce que la valeur du champ Operation.done soit true. Lorsque le champ Operation.done est défini sur false, cela signifie que l'opération est en cours. Pour en savoir plus, consultez la page Commandes d'API asynchrones.

Voici un exemple de réponse lorsque le projet surveillé est ajouté:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

Dans la réponse précédente, le champ Operation.done est défini sur true. Cette valeur indique que la commande est terminée. Comme la commande a bien été exécutée, le champ Operation.response est défini et sa valeur est un objet MonitoredProject. Le champ response.name inclut l'identifiant du projet de champ d'application et du projet surveillé. Le champ providerAccountId répertorie le nom du projet surveillé.

L'appel de cette méthode entraîne une entrée dans les journaux d'audit du projet de champ d'application. La console Google Cloud n'appelle pas cette méthode API. Par conséquent, les modifications apportées à un champ d'application de métriques lors de l'utilisation de Google Cloud Console ne sont pas enregistrées dans les journaux d'audit.

Supprimer un projet du champ d'application des métriques

gcloud

Pour supprimer un projet Google Cloud d'un champ d'application des métriques, exécutez la commande gcloud beta monitoring metrics-scopes delete:

gcloud beta monitoring metrics-scopes delete MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

Avant d'exécuter la commande précédente, procédez comme suit:

  • Saisissez le nom ou l'ID du projet Google Cloud dont le champ d'application des métriques doit être modifié dans la variable SCOPING_PROJECT_ID_OR_NUMBER. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion du dossier compatible avec les applications.

  • Saisissez l'identifiant de votre projet surveillé dans la variable MONITORED_PROJECT_ID_OR_NUMBER. Il a le format suivant : projects/PROJECT_ID_OR_NUMBER.

Par exemple, la commande suivante supprime le projet my-monitored-project du champ d'application des métriques du projet nommé my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

La réponse à la commande précédente confirme que la commande a bien abouti:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

L'erreur suivante est signalée lorsque le projet de champ d'application ne surveille pas le projet spécifié par la variable MONITORED_PROJECT_ID_OR_NUMBER:

NOT_FOUND: Requested entity was not found.

curl

Pour supprimer un Google Cloud projet d'un champ d'application des métriques, envoyez une requête DELETE au point de terminaison locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

Dans l'exemple précédent, les variables d'environnement sont définies comme suit:

  • MONITORED_PROJECT_ID_OR_NUMBER stocke l'ID du projet à supprimer du champ d'application des métriques.
  • SCOPING_PROJECT_ID_OR_NUMBER stocke l'ID du projet dont le champ d'application des métriques est mis à jour.

La réponse à cette méthode asynchrone est un objet Operation.

Les applications appelant cette méthode doivent interroger le point de terminaison operation.get jusqu'à ce que la valeur du champ Operation.done soit true. Lorsque le champ Operation.done est défini sur false, cela signifie que l'opération est en cours. Pour en savoir plus, consultez la page Commandes d'API asynchrones.

Voici un exemple de réponse lorsque la suppression d'un projet surveillé est une réussite:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Dans la réponse précédente, le champ Operation.done est défini sur true. Cette valeur indique que la commande est terminée. Comme la commande a bien été exécutée, le champ Operation.response est défini et contient un champ @type.

L'appel de cette méthode entraîne une entrée dans les journaux d'audit du projet de champ d'application. La console Google Cloud n'appelle pas cette méthode API. Par conséquent, les modifications apportées à un champ d'application de métriques lors de l'utilisation de Google Cloud Console ne sont pas enregistrées dans les journaux d'audit.

Répertorier tous les champs d'application des métriques incluant un projet

Si vous souhaitez savoir quelles ressources peuvent afficher les données stockées par un projet Google Cloud, vous pouvez lister tous les champs d'application des métriques qui incluent le projet, puis trouver des informations sur ces champs d'application. Cette section explique comment lister le champ d'application des métriques qui incluent un projet Google Cloud spécifique.

gcloud

Pour obtenir la liste des champs d'application des métriques pouvant afficher les métriques d'un projet Google Cloud, exécutez la commande gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER

Avant d'exécuter la commande, saisissez l'identifiant de votre projet surveillé dans la variable MONITORED_PROJECT_ID_OR_NUMBER. Le format est le suivant : projects/PROJECT_ID_OR_NUMBER.

Par exemple, pour lister les champs d'application des métriques qui incluent le projet my-project, exécutez la commande suivante:

gcloud beta monitoring metrics-scopes list projects/my-project

La réponse suivante indique que le projet my-project est inclus dans deux champs d'application des métriques:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

Pour obtenir des informations détaillées sur un champ d'application de métriques, exécutez la commande gcloud beta monitoring metrics-scopes describe.

curl

Pour obtenir la liste des champs d'application des métriques pouvant afficher les métriques d'un projet, envoyez une requête GET au point de terminaison locations.global.metricsScopes.listMetricsScopesByMonitoredProject et incluez le paramètre de requête spécifiant le projet.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

Dans l'exemple précédent, la variable d'environnement PROJECT_ID_OR_NUMBER stocke l'ID du projet dont l'inclusion dans le champ d'application des métriques est interrogée.

Si la requête aboutit, la réponse est un tableau d'objets MetricsScope.

Cette méthode ne génère pas l'écriture d'une entrée dans les journaux d'audit du projet de champ d'application. Pour que ces actions soient enregistrées dans le journal d'audit, activez la lecture de données pour l'API Cloud Resource Manager. Pour en savoir plus, consultez la page Configurer les journaux d'audit pour l'accès aux données.

Obtenir des informations sur un champ d'application des métriques

Cette section explique comment trouver des informations sur une portée de métriques spécifique.

gcloud

Pour obtenir des informations détaillées sur le champ d'application des métriques, exécutez la commande gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Avant d'exécuter la commande, saisissez le nom complet d'un champ d'application de métriques dans la variable METRICS_SCOPE_ID. Voici un exemple de nom complet:

locations/global/metricsScopes/012345012345

Voici un exemple de réponse. Dans cet exemple, le champ d'application des métriques contient un seul projet, et l'ID du champ d'application des métriques et du projet est le même:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

Pour identifier le projet Google Cloud à partir de son ID, exécutez la commande gcloud projects list et filtrez par ID de projet. Par exemple, pour obtenir le nom du projet 012345012345, exécutez la commande suivante:

gcloud projects list --filter="012345012345" --format="value(NAME)"

curl

Pour obtenir des informations sur le champ d'application des métriques, envoyez une requête GET au point de terminaison locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

Dans l'exemple précédent, la variable d'environnement SCOPING_PROJECT_ID_OR_NUMBER stocke l'ID du projet dont le champ d'application des métriques est interrogé.

Si l'opération réussit, la réponse est un objet MetricsScope.

Cette méthode ne génère pas l'écriture d'une entrée dans les journaux d'audit du projet de champ d'application. Pour que ces actions soient enregistrées dans le journal d'audit, activez la lecture de données pour l'API Cloud Resource Manager. Pour en savoir plus, consultez la page Configurer les journaux d'audit pour l'accès aux données.

Méthodes d'API asynchrones

Toutes les méthodes de champ d'application des métriques de l'API Cloud Monitoring qui modifient l'état du système, par exemple la commande permettant d'ajouter un projet surveillé, à un projet de champ d'application sont asynchrones. Pour ces commandes, la réponse de la commande est un objet Operation.

Les applications qui appellent une méthode API asynchrone doivent interroger le point de terminaison operation.get jusqu'à ce que la valeur du champ Operation.done soit true:

  • Lorsque l'état done est défini sur false, l'opération est en cours.

    Pour actualiser les informations d'état, envoyez une requête GET au point de terminaison operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}

    Dans la commande précédente, OPERATION_NAME est une variable d'environnement qui stocke la valeur du champ Operation.name.

  • Lorsque done est défini sur true, l'opération est terminée et le champ error ou response est défini:

    • error: si défini, l'opération asynchrone a échoué. La valeur de ce champ est un objet Status qui contient un code d'erreur gRPC et un message d'erreur.
    • response: si défini, l'opération asynchrone est terminée et la valeur reflète le résultat.

Configuration de la commande curl

Cette section décrit la configuration utilisée pour créer les commandes curl dans ce document. Chaque commande curl de cette page inclut un ensemble d'arguments, suivi de l'URL d'une ressource d'API:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Définissez ces variables d'environnement pour simplifier la création des commandes curl:

  1. Créez la variable d'environnement pour stocker l'ID ou le numéro du projet de champ d'application. Si vous utilisez App Hub, définissez cette variable sur l'ID de votre projet hôte App Hub ou sur l'ID du projet de gestion de votre dossier compatible avec les applications:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. Facultatif. Si vous envisagez d'ajouter ou de supprimer des projets surveillés, configurez la variable d'environnement avec l'ID ou le numéro de projet surveillé :

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. Authentifiez-vous sur Google Cloud CLI :

    gcloud auth login

  4. Facultatif. Pour éviter d'avoir à spécifier votre ID de projet avec chaque commande gcloud, définissez votre ID de projet par défaut à l'aide de gcloud CLI:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. Créez un jeton d'autorisation et placez-le dans une variable d'environnement.

    TOKEN=`gcloud auth print-access-token`

    Les jetons sont valides pendant une durée limitée. Si des commandes auparavant fonctionnelles indiquent soudainement que vous n'êtes pas authentifié, exécutez à nouveau cette commande.

  6. Pour vérifier que vous disposez bien d'un jeton d'accès, renvoyez la variable TOKEN :

    echo ${TOKEN}
ya29.GluiBj8o....

Vous devrez peut-être également spécifier d'autres arguments pour définir des éléments tels que le type de la requête HTTP (-X DELETE, par exemple). La requête par défaut est GET. Les exemples ne la spécifient donc pas.

Étape suivante

Pour en savoir plus sur l'utilisation de Google Cloud avec Terraform, consultez les ressources suivantes: