Travailler avec l'API

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

Cette page décrit les principales utilisations des nouvelles ressources de l'API. Pour obtenir une présentation générale des structures utilisées ici, consultez la page Construire dans l'API. Un document de référence complet s'affiche sous API Cloud Monitoring v3.

Dans le présent document, ces ajouts sont collectivement appelés "API SLO".

Quand utiliser l'API ?

L'API SLO permet de gérer les services et les objectifs de niveau de service (SLO). Cette page traite des services et des indicateurs de niveau de service (SLI) personnalisés. Les services s'exécutant sur Anthos Service Mesh, Istio sur Google Kubernetes Engine et App Engine sont automatiquement détectés, et les SLI associés sont prédéfinis :

  • Pour définir des SLO pour les services Anthos Service Mesh, vous pouvez utiliser la console Anthos Service Mesh ou l'API SLO. Pour plus d'informations sur la création de SLO à l'aide du tableau de bord Anthos Service Mesh, consultez la documentation Anthos Service Mesh : Créer des SLO.

  • Pour les autres services et les services personnalisés, vous devez définir des SLO à l'aide de l'API SLO. Aucune assistance Google Cloud Console n'est actuellement disponible.

Les exemples présentés sur cette page concernent principalement les services personnalisés et les SLI.

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 espace de travail Cloud Monitoring. Ces exemples utilisent PROJECT_ID :

    PROJECT_ID=my-test-service
    
  2. Authentifiez-vous au SDK Cloud :

    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 du SDK Cloud :

    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 opération renvoie un tableau de descriptions de services contenant des entrées telles que les suivantes, qui montrent un service Istio appelé "currencyservice" :

{
  "services": [
    {
      "name": "projects/[PROJECT_NUMBER]/services/[PROJECT_ID]-zone-us-central1-c-csm-main-default-currencyservice",
      "displayName": "[PROJECT_ID]/us-central1-c/csm-main/default/currencyservice",
      "clusterIstio": {
        "location": "us-central1-c",
        "clusterName": "csm-main",
        "serviceNamespace": "default",
        "serviceName": "currencyservice"
      },
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/[PROJECT_ID]/zones/us-central1-c/clusters/csm-main/k8s/namespaces/default/services/currencyservice"
      }
    },
   ...
  ]
}

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 services sur Anthos Service Mesh, Istio sur Google Kubernetes Engine et App Engine sont créés automatiquement. Vous pouvez par exemple ajouter des SLO à ces services à l'aide de la console Anthos Service Mesh ou de l'API SLO.

Les services que vous créez manuellement sont appelés services personnalisés. Vous ne pouvez créer, supprimer, récupérer et mettre à jour des services personnalisés qu'à l'aide de l'API SLO.

Une fois que vous avez identifié ou créé un service, vous pouvez y ajouter des SLO. 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

Si vous n'utilisez pas un environnement dans lequel les services (Anthos Service Mesh, Istio sur Google Kubernetes Engine et App Engine) sont automatiquement créés, vous pouvez créer des services à l'aide de la commande services.create.

Si vous créez manuellement des services, vous devez ajouter manuellement les SLO et autres artefacts de surveillance de service à la structure de service à l'aide de l'API SLO. Pour obtenir une présentation de ces structures, consultez la page Construire dans l'API.

Pour créer un service, vous devez spécifier un nom à afficher pour le service et un champ nommé custom avec un objet vide. Vous pouvez éventuellement spécifier l'ID de service que vous souhaitez attribuer au service.

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 Service",
        "custom": {}
    }
    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}
    

Supprimer un service

Pour supprimer un service personnalisé, 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

Les SLO sont associés à des services. Vous pouvez créer des SLO à l'aide de la console Anthos Service Mesh pour Anthos Service Mesh, d'Istio sur Google Kubernetes Engine et d'App Engine, ou à l'aide de l'API SLO. Pour créer des SLO pour des services personnalisés, vous devez utiliser l'API SLO.

Vous pouvez également utiliser l'API SLO pour récupérer les SLO associés à un service et supprimer des SLO d'un service. 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. La section ID de service décrit comment reconnaître les 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 à l'aide de 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 Anthos 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 Anthos Service Mesh. Il vous suffit pour cela de spécifier les objectifs de performances et les périodes de conformité.

    Vous pouvez également définir des SLO à l'aide de l'API SLO.

  • Pour les services personnalisés, 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 en savoir plus.

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 continue 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 Anthos Service Mesh, Istio sur Google Kubernetes Engine et App Engine, le type de SLI est le SLI de base.

Pour les services personnalisés, 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.