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

Ce document explique comment utiliser la Google Cloud CLI ou la 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 Configurations des champs 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 de la Google Cloud CLI sont bloquées jusqu'à ce que l'opération asynchrone. Pour savoir comment déterminer lorsqu'une méthode API asynchrone est terminée et comment déterminer son état, consultez la page Méthodes 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, puis effectuez étapes 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 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 répertorier 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 des métriques, exécutez la 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 détails 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 le champ d'application des métriques dans la variable METRICS_SCOPE_ID. Les éléments suivants : est 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 projet. L'ID du champ d'application et du projet des métriques correspond identique:

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 les données par ID de projet. Par exemple, pour Obtenez 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

gcloud

Pour ajouter un conteneur de ressources, tel qu'un projet Google Cloud, à un champ d'application de 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 est être remplacée par 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 à le 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 terminée avec succès:

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 des métriques lors de l'utilisation la console Google Cloud ne sont pas enregistrés dans les journaux d'audit.

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

gcloud

Pour supprimer un conteneur de ressources, tel qu'un projet Google Cloud, d'un champ d'application des métriques, exécutez 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 est être remplacée par 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 terminée avec succès:

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

L'erreur suivante est signalée lorsque le projet de définition de la portée 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 des métriques lors de l'utilisation la console Google Cloud ne sont pas enregistrés 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 de suivis 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 l'ID de votre projet avec chaque gcloud , définissez votre ID de projet comme ID par défaut à l'aide de la 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 aussi spécifier d'autres arguments, par exemple pour spécifier le Type de la requête HTTP (par exemple, -X DELETE). La requête par défaut étant GET, les exemples ne le spécifient pas.

Étape suivante

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