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 désignés par le nom API Service Monitoring.

Quand utiliser l'API ?

L'API Service Monitoring 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 App Engine, Istio sur Google Kubernetes Engine et Cloud Endpoints sont automatiquement détectés, et les SLI associés sont prédéfinis. Pour définir des SLO, vous pouvez utiliser la console Anthos Service Mesh ou l'API Service Monitoring. 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.

Vous pouvez également définir vos propres services et leurs SLO, mais vous devez utiliser l'API Service Monitoring. Aucune assistance Google Cloud Console n'est disponible.

Les exemples décrits sur cette page couvrent principalement les services et les SLI personnalisés.

Identifiants valides

Plusieurs méthodes de l'API Service Monitoring 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 employées pour appeler l'API Service Monitoring à l'aide de l'outil curl. Si vous utilisez cette API via une bibliothèque cliente, vous pouvez ignorer cette section.

Pour les exemples de cette page, vous accédez à l'API Service Monitoring via l'outil curl pour envoyer des requêtes HTTP aux points de terminaison REST. Utilisez les informations suivantes sur l'authentification et sur l'invocation de curl pour définir les variables utilisées dans les invocations.

Authentication

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

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 Service Monitoring.

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 sont automatiquement créés (c'est-à-dire, App Engine, Istio sur Google Kubernetes Engine ou Cloud Endpoints), vous pouvez créer des services à l'aide de la méthode services.create.

Si vous créez manuellement des services, vous devez ajouter manuellement les SLO et autres artefacts de surveillance à la structure du service à l'aide de l'API Service Monitoring. 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 App Engine, Istio sur Google Kubernetes Engine et Cloud Endpoints, ou à l'aide de l'API Service Monitoring. Pour créer des SLO pour des services personnalisés, vous devez utiliser l'API Service Monitoring.

Vous pouvez également exploiter l'API Service Monitoring pour récupérer ou supprimer les SLO associés à un 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 Service Monitoring, vous devez créer un objet ServiceLevelObjective et le transmettre à la méthode serviceLevelObjectives.create.

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

  • Pour les services App Engine, Istio sur Google Kubernetes Engine et Cloud Endpoints, 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 Service Monitoring.

  • Pour les services personnalisés, vous devez définir des SLO à l'aide de l'API Service Monitoring. 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 Concepts de la surveillance des services.

Pour les services App Engine, Istio sur Google Kubernetes Engine et Cloud Endpoints, le type 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.