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.

Les commandes de cette page font référence à un conteneur de ressources, qui est toujours un projet Google Cloud.

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

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

gcloud

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

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

Avant d'exécuter la commande, saisissez l'identifiant du conteneur de ressources dans la variable MONITORED_RESOURCE_CONTAINER_NAME. Lorsque le conteneur de ressources est un projet Google Cloud, saisissez 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}

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

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}

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.

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

Si vous utilisez App Hub, pour afficher les métriques système à partir d'App Hub, vous devez configurer à la fois le projet hôte App Hub et le champ d'application des métriques. L'ajout d'un projet de service App Hub à un projet hôte App Hub ne modifie pas le champ d'application des métriques du projet. De même, ajouter un projet à un champ d'application des métriques ne modifie pas la liste des projets de service App Hub associés au projet hôte App Hub. Pour en savoir plus sur la configuration d'un projet hôte App Hub, consultez Ajouter ou supprimer des projets de service.

gcloud

Pour ajouter un conteneur de ressources, tel qu'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_RESOURCE_CONTAINER_NAME --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.

  • Saisissez l'identifiant de votre conteneur de ressources dans la variable MONITORED_RESOURCE_CONTAINER_NAME. Lorsque le conteneur de ressources est un projet Google Cloud, saisissez 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. Dans l'exemple suivant, le projet identifié par la variable d'environnement MONITORED_PROJECT_ID_OR_NUMBER est ajouté en tant que projet surveillé:

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

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

Si vous utilisez App Hub, avant de supprimer un projet du champ d'application des métriques, assurez-vous qu'il n'est pas utilisé par une application App Hub. La suppression du projet du champ d'application des métriques n'aura aucun impact sur l'application. Toutefois, vous ne pourrez pas afficher les métriques système de cette application à partir du contexte du projet hôte App Hub. Pour en savoir plus sur la configuration d'un projet hôte App Hub, consultez Ajouter ou supprimer des projets de service.

gcloud

Pour supprimer un conteneur de ressources, tel qu'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_RESOURCE_CONTAINER_NAME --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.

  • Saisissez l'identifiant de votre conteneur de ressources dans la variable MONITORED_RESOURCE_CONTAINER_NAME. Lorsque le conteneur de ressources est un projet Google Cloud, saisissez 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_RESOURCE_CONTAINER_NAME:

NOT_FOUND: Requested entity was not found.

curl

Pour supprimer un projet Google Cloud 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}

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.

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:

    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 :