Travailler avec l'API

Ce document explique comment gérer les services et les objectifs de niveau de service (SLO) en utilisant l'API Cloud Monitoring.

Service Monitoring ajoute les ressources suivantes à l'API Monitoring :

Ces ajouts sont collectivement appelés "API SLO" dans le présent document, qui en illustre les utilisations principales. Pour en savoir plus sur les structures de l'API SLO, consultez la page Structures dans l'API. Un document de référence complet s'affiche sous API Cloud Monitoring v3.

Vous pouvez utiliser l'API SLO pour effectuer les opérations suivantes :

  • Créer et gérer des services.

  • Créez des objectifs de niveau de service (SLO) basés sur des indicateurs de niveau de service (SLI) personnalisés ou prédéfinis pour l'un de vos services.

Identifiants valides

Dans l'API SLO, plusieurs méthodes utilisent des identifiants pour différents éléments, en particulier des identifiants pour le projet et les services. Ces identifiants doivent respecter les règles suivantes :

  • Longueur : 1 à 63 caractères
  • Caractères : lettres minuscules, chiffres et traits d'union uniquement
  • Caractère initial : lettre minuscule
  • Caractère final : lettre minuscule ou chiffre, mais pas un trait d'union

L'expression régulière de ces règles est la suivante : [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

Exemples utilisant curl

Cette section décrit les conventions et la configuration utilisées pour appeler l'API SLO à l'aide de l'outil curl. Si vous utilisez cette API via une bibliothèque cliente, vous pouvez ignorer cette section.

Les exemples de cette page accèdent à l'API SLO à l'aide de l'outil curl pour envoyer des requêtes HTTP aux points de terminaison REST. Utilisez les informations suivantes sur l'authentification et sur l'appel de curl pour définir les variables utilisées dans les appels.

Authentification

  1. Créez une variable d'environnement destinée à contenir l'ID de votre projet de champ d'application d'un champ d'application des métriques. Ces exemples utilisent PROJECT_ID :

    PROJECT_ID=my-test-service

  2. Authentifiez-vous sur Google Cloud CLI :

    gcloud auth login

  3. Pour éviter d'avoir à spécifier votre ID de projet dans chaque commande, définissez-le en tant qu'ID par défaut à l'aide de gcloud CLI :

    gcloud config set project ${PROJECT_ID}

  4. Créez un jeton d'autorisation et placez-le dans une variable d'environnement. Ces exemples appellent la variable ACCESS_TOKEN :

    ACCESS_TOKEN=`gcloud auth print-access-token`

    Vous devez actualiser régulièrement le jeton d'accès. Si des commandes auparavant fonctionnelles indiquent soudainement que vous n'êtes pas authentifié, exécutez à nouveau cette commande.

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

    echo ${ACCESS_TOKEN}
ya29.GluiBj8o....

Appeler curl

Chaque appel curl inclut un ensemble d'arguments, suivi de l'URL d'une ressource de l'API SLO. Les valeurs spécifiées par les variables d'environnement PROJECT_ID et ACCESS_TOKEN constituent des arguments courants. 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.

Chaque appel curl possède la structure générale suivante :

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Par exemple, pour répertorier tous les services de votre projet, exécutez la requête GET ci-dessous :

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services

Cette requête renvoie un tableau de descriptions de services contenant des entrées telles que les suivantes, qui montrent un service de charge de travail GKE portant l'ID de service "my-test-service" :

{
  "services": [
    {
      "name": "projects/PROJECT_NUMBER/services/my-test-service",
      "displayName": "My Test GKE Workload Service",
      "basicService": {
        "serviceType": "GKE_WORKLOAD",
        "serviceLabels": {
          "cluster_name": "workload-test",
          "location": "us-central1-c",
          "namespace_name": "kube-system",
          "project_id": "lesser-weevil",
          "top_level_controller_name": "gke-metrics-controller",
          "top_level_controller_type": "DaemonSet"
        }
      },
      "gkeWorkload": {
        "projectId": "lesser-weevil",
        "location": "us-central1-c",
        "clusterName": "workload-test",
        "namespaceName": "kube-system",
        "topLevelControllerType": "DaemonSet",
        "topLevelControllerName": "gke-metrics-controller"
      },
      "source": "USER",
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller"
      }
    },
   ...
  ]
}

Pour voir la configuration utilisée pour créer ce service, consultez Créer un service. Notez que la structure gkeWorkload de cette liste est dérivée de la structure basicService utilisée pour créer le service. Pour en savoir plus sur la structure d'un service, consultez la documentation de la ressource Service.

Gérer les services

La ressource Service sert d'élément racine pour l'organisation de vos services. Les aspects d'un service spécifique, comme ses SLO, sont organisés sous le nom du service. Les types de services suivants sont compatibles :

  • Service App Engine : APP_ENGINE
  • Service Cloud Endpoints : CLOUD_ENDPOINTS
  • Service Istio canonique : ISTIO_CANONICAL_SERVICE
  • Service Istio du cluster : CLUSTER_ISTIO
  • Service Cloud Run : CLOUD_RUN
  • Un ensemble de services basés sur Google Kubernetes Engine :
    • Service GKE : GKE_SERVICE
    • Espace de noms GKE : GKE_NAMESPACE
    • Charge de travail GKE : GKE_WORKLOAD
  • Services personnalisés : CUSTOM

Pour en savoir plus, consultez Types de services de base ou Types de services GKE de base.

Vous pouvez ajouter des SLO à n'importe quel service de votre projet en utilisant l'API. La section Gérer les SLO fournit des commandes permettant de manipuler les SLO.

ID de service

Chaque service est associé à un identifiant complet appelé nom de ressource. Cet identifiant est stocké dans le champ name de la description du service. Par exemple :

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",

Le nom de la ressource est intégré dans un ID plus court du service, qui correspond au nom de la ressource après la sous-chaîne projects/PROJECT_NUMBER/services/.

Si vous avez créé votre propre service avec le nom de ressource projects/PROJECT_NUMBER/services/my-test-service, l'ID de service est my-test-service.

Par souci de concision et d'exactitude, de nombreux exemples curl partent du principe que l'ID de service se trouve dans la variable d'environnement SERVICE_ID.

Répertorier les services

Pour obtenir des informations sur tous les services de votre projet, appelez la méthode services.list. Pour obtenir des informations sur un service spécifique par ID de service, utilisez la méthode services.get :

Protocole

Pour obtenir des informations sur les services à l'aide de curl, appelez la méthode services.list ou services.get en envoyant une requête GET à :

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services pour répertorier tous les services ;
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID pour obtenir un service spécifique.

Par exemple, la requête suivante récupère des informations sur le service identifié par la valeur stockée dans la variable d'environnement SERVICE_ID :

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

Créer un service

Pour créer un service, vous devez spécifier une représentation du type de service et l'envoyer à la méthode services.create. Vous pouvez utiliser les structure de types de services décrites dans Types de services de base et Types de services GKE de base.

Les structures varient, mais le processus d'appel de l'API est le même. Vous devez spécifier un nom à afficher pour le service ainsi qu'un champ basicService contenant la représentation du service.

Vous pouvez éventuellement spécifier l'ID de service que vous souhaitez attribuer au service. L'exemple suivant illustre la création d'un service de charge de travail {[gke_name_short}} :

Protocole

Pour créer le service à l'aide de curl, envoyez un message POST au point de terminaison https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services :

  1. Si vous souhaitez fournir un ID au service, créez une variable pour l'ID de service :

    SERVICE_ID=my-test-service

    Cette valeur est fournie dans le paramètre de requête d'URL service_id.

  2. Créez une variable destinée à contenir le corps de la requête décrivant le service :

    CREATE_SERVICE_POST_BODY=$(cat <<EOF
{
  "displayName": "My Test GKE Workload Service",
  "basicService": {
    "serviceType": "GKE_WORKLOAD",
    "serviceLabels": {
      "cluster_name": "workload-test",
      "location": "us-central1-c",
      "namespace_name": "kube-system",
      "project_id": "PROJECT_ID",
      "top_level_controller_name": "gke-metrics-controller",
      "top_level_controller_type": "DaemonSet"
    }
  }
}
EOF
)

  3. Publiez le corps de la requête sur le point de terminaison et spécifiez l'ID de service en tant que valeur du paramètre de requête service_id :

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}

Pour obtenir des exemples de structures associées à d'autres services, consultez Types de services de base ou Types de services GKE de base.

Supprimer un service

Pour supprimer un service que vous avez créé, appelez la méthode services.delete et spécifiez l'ID de service.

Protocole

Pour supprimer un service à l'aide de curl, envoyez une requête DELETE au point de terminaison https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID :

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

Gérer les SLO

Vous pouvez créer, supprimer et récupérer des SLO à l'aide de l'API SLO. Vous pouvez avoir jusqu'à 500 SLO pour chaque service.

Pour gérer les SLO d'un service, vous devez disposer de l'ID de service. Les SLO sont nommés en fonction du service auquel ils appartiennent. Pour plus d'informations sur l'identification des ID de service, consultez la section ID de service.

Répertorier les SLO

Pour obtenir des informations sur tous les SLO associés à un service, appelez la méthode services.serviceLevelObjectives.list. Pour obtenir des informations sur un SLO spécifique par nom, utilisez la méthode services.serviceLevelObjectives.get :

Protocole

Pour obtenir des informations sur les services en utilisant curl, appelez la méthode services.serviceLevelObjectives.list ou services.serviceLevelObjectives.get en envoyant une requête GET à :

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives pour répertorier tous les SLO.
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID pour obtenir un SLO spécifique.

Par exemple, la requête suivante répertorie tous les SLO associés à l'ID de service stocké dans la variable d'environnement SERVICE_ID :

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

Voici un SLO de disponibilité obtenu à partir du service “currencyservice" :

{
  "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
  "displayName": "98% Availability in Calendar Week"
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.98,
  "calendarPeriod": "WEEK",
},

Ce SLO est basé sur un SLI de disponibilité. Il définit un objectif de performances cible de 98 % et mesure la conformité sur une semaine calendaire. Pour en savoir plus sur les SLI de disponibilité, consultez la section Indicateurs au niveau du service.

Pour en savoir plus sur la structure des SLO, consultez la documentation de la ressource ServiceLevelObjective.

Récupérer un SLO spécifique

Chaque SLO dispose d'un identifiant unique au sein du service, constitué de la chaîne suivant serviceLevelObjectives dans le champ name du SLO. Dans l'exemple suivant :

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",

L'ID du SLO correspond à la chaîne 3kavNVTtTMuzL7KcXAxqCQ.

Pour obtenir des informations sur ce SLO spécifique, exécutez une requête en spécifiant son ID.

Protocole

Pour obtenir un SLO spécifique à l'aide de curl, appelez la méthode services.serviceLevelObjectives.get en envoyant une requête GET à https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID :

SLO_ID=dhefHDM4TwSRZEKIV4ZYEg

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

Créer un SLO

Pour créer un SLO à l'aide de l'API SLO, vous devez créer un objet ServiceLevelObjective et le transmettre à la méthode serviceLevelObjectives.create.

La structure d'un SLO comprend de nombreuses structures intégrées, dont une pour la valeur du champ serviceLevelIndicator.

  • Pour les services Cloud Service Mesh, Istio sur Google Kubernetes Engine et App Engine, les SLI sont prédéfinis. Vous pouvez créer des SLO à l'aide de la console Cloud Service Mesh. Il vous suffit pour cela de spécifier les objectifs de performances et les périodes de conformité.

  • Pour les autres services, vous devez définir des SLO à l'aide de l'API SLO. Pour spécifier un SLO, vous devez également créer une valeur pour le champ serviceLevelIndicator. Consultez la page Créer un indicateur de niveau de service pour découvrir certaines techniques, et la page Créer des SLI à partir de métriques pour obtenir un ensemble d'exemples basés sur diverses sources.

Vous pouvez également créer des SLI à l'aide de la console Google Cloud. Pour en savoir plus, consultez la page Créer un SLO.

Squelette d'un SLO

Le squelette de base pour la création du SLO se présente comme suit :

{
  "displayName": string,
  "serviceLevelIndicator": {
    object (ServiceLevelIndicator)
  },
  "goal": number,

  // Union field period can be only one of the following:
  "rollingPeriod": string,
  "calendarPeriod": enum (CalendarPeriod)
  // End of list of possible types for union field period.
}

Vous devez spécifier les éléments suivants :

  • Un nom à afficher décrivant le SLO
  • Un indicateur de niveau de service parmi les trois types suivants :
  • Un objectif de performances (en pourcentage)
  • Une période de conformité, qui peut être :
    • Une période glissante d'une certaine durée (en secondes) ;
    • une période calendaire.

Pour plus d'informations sur les SLI, les objectifs de performances et les périodes de conformité, consultez la section Concepts de la surveillance des services.

Pour les services Cloud Service Mesh, Istio sur Google Kubernetes Engine et App Engine, le type de SLI est le SLI de base.

Pour les autres services, vous devez créer un SLI basé sur les requêtes ou basé sur les périodes. Consultez la page Créer un indicateur de niveau de service pour en savoir plus.

Exemple

Une fois que vous disposez du SLI, vous pouvez créer le SLO. L'exemple suivant définit un SLO pour un service qui utilise un SLI de base. Vous pouvez spécifier plusieurs SLO pour un même SLI. Par exemple, un SLO associé à une disponibilité de 95 % et un autre à une disponibilité de 99 %. L'exemple suivant décrit un SLO de disponibilité de 95 % sur une semaine calendaire : 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.95,
  "calendarPeriod": "WEEK",
  "displayName": "95% Availability in Calendar Week"
}

L'exemple ci-dessous décrit un SLO de disponibilité de 75 % sur une période de trois jours consécutifs : 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}

Protocole

Pour créer un SLO à l'aide de curl, envoyez un message POST au point de terminaison https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives :

  1. Créez une variable pour l'ID de service :

    SERVICE_ID=custom:my-test-service

  2. Créez une variable destinée à contenir le corps de la requête, une instance de l'objet ServiceLevelObjective. Cet exemple utilise l'un des SLO décrits précédemment :

    CREATE_SLO_POST_BODY=$(cat <<EOF
{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}
EOF
)

  3. Publiez le corps de la requête sur le point de terminaison :

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

    De plus, vous pouvez éventuellement spécifier l'ID souhaité pour le SLO en tant que valeur du paramètre de requête service_level_objective_id :

    SLO_ID=test-slo-id

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}

Supprimer un SLO

Pour supprimer un SLO, appelez la méthode services.serviceLevelObjectives.delete et spécifiez l'ID du SLO dans votre projet :

Protocole

Pour supprimer un SLO à l'aide de curl, envoyez une requête DELETE au point de terminaison https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID :

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

Accéder aux séries temporelles d'un SLO

Les données de SLO sont stockées dans des séries temporelles. Vous pouvez les récupérer à l'aide de la méthode timeSeries.list. Toutefois, ces données ne sont pas stockées dans des types de métriques standards. Vous ne pouvez donc pas utiliser le mécanisme standard permettant de spécifier un filtre de type métrique pour la méthode timeSeries.list.

Pour récupérer les séries temporelles d'un SLO, vous devez à la place spécifier un autre type de filtre, un sélecteur de séries temporelles, dans le paramètre filter de la méthode timeSeries.list. Pour en savoir plus sur l'utilisation de ces sélecteurs, consultez la section Obtenir les données de SLO.

Vous pouvez également utiliser des sélecteurs de séries temporelles pour configurer des règles d'alerte par programmation. Pour en savoir plus, consultez la page Obtenir des alertes concernant votre taux d'utilisation.