Construire dans l'API

Ce document présente les structures utilisées pour représenter les services et les SLO dans l'API SLO, et les associe aux concepts décrits de manière générale sur la page Concepts de surveillance des services.

L'API SLO permet de configurer des objectifs de niveau de service (SLO) qui permettent de surveiller l'état de vos services.

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

• services
• services.serviceLevelObjectives

Pour plus d'informations sur l'appel de l'API, consultez la page Travailler avec l'API.

Services

Un service est représenté par un objet Service. Cet objet inclut les champs suivants :

• Un nom : nom de ressource complet pour ce service
• Un nom à afficher : étiquette à utiliser dans les composants de la console
• La structure de l'un des types BasicService
• Un objet de configuration de la télémétrie fourni par le système

Pour définir un service de base, vous devez spécifier le type de service et fournir un ensemble de libellés spécifiques au service décrivant le service :

{
   "serviceType": string,
   "serviceLabels": {
      string: string,
      ...
   }
}

Les sections suivantes fournissent des exemples pour chaque type de service.

Types de services de base

Cette section fournit des exemples de définitions de service basées sur le type BasicService, où la valeur du champ serviceType est l'une des suivantes :

• APP_ENGINE
• CLOUD_ENDPOINTS
• CLUSTER_ISTIO
• ISTIO_CANONICAL_SERVICE
• CLOUD_RUN

Chacun de ces types de service utilise l'indicateur de niveau de service BasicSli.

App Engine

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "APP_ENGINE",
          "serviceLabels": {
            "module_id": "MODULE_ID"
          },
      },
    }

Cloud Endpoints

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_ENDPOINTS",
          "serviceLabels": {
            "service": "SERVICE"
          },
      },
    }

Cluster Istio

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLUSTER_ISTIO",
          "serviceLabels": {
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "service_namespace": "SERVICE_NAMESPACE",
            "service_name": "SERVICE_NAME"
          },
      },
    }

Istio Canonical Service

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "ISTIO_CANONICAL_SERVICE",
          "serviceLabels": {
            "mesh_uid": "MESH_UID",
            "canonical_service_namespace": "CANONICAL_SERVICE_NAMESPACE",
            "canonical_service": "CANONICAL_SERVICE"
          },
      },
    }

Cloud Run

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_RUN",
          "serviceLabels": {
            "service_name": "SERVICE_NAME",
            "location": "LOCATION"
          },
      },
    }

Types de services GKE de base

Cette section contient des exemples de définitions de service GKE basées sur le type BasicService, où la valeur du champ serviceType est l'une des suivantes :

• GKE_NAMESPACE
• GKE_WORKLOAD
• GKE_SERVICE

Vous devez définir des SLI pour ces types de services. Ils ne peuvent pas utiliser d'indicateurs de niveau du service BasicSli. Pour en savoir plus, consultez Indicateurs de niveau du service.

Espace de noms GKE

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_NAMESPACE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME"
          }
      },
    }

Charge de travail GKE

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_WORKLOAD",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "top_level_controller_type": "TOPLEVEL_CONTROLLER_TYPE",
            "top_level_controller_name": "TOPLEVEL_CONTROLLER_NAME",
          }
      },
    }

Service GKE

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_SERVICE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "service_name": "SERVICE_NAME"
          }
      },
    }

Services personnalisés

Vous pouvez créer des services personnalisés si aucun des types de services de base ne convient. Un service personnalisé se présente comme suit :

    {
      "displayName": "DISPLAY_NAME",
      "custom": {}
    }

Vous devez définir des SLI pour ces types de services. Ils ne peuvent pas utiliser d'indicateurs de niveau du service BasicSli. Pour en savoir plus, consultez Indicateurs de niveau du service.

Indicateurs de niveau de service

Un indicateur de niveau de service (SLI, Service Level Indicator) permet de mesurer les performances d'un service. Il repose sur la métrique recueillie par le service. La façon exacte dont le SLI est défini dépend du type de métrique utilisé pour celui-ci, mais il s'agit généralement d'une comparaison entre les résultats acceptables et le total des résultats.

Un SLI est représenté par l'objet ServiceLevelIndicator. Cet objet permet de désigner de manière collective les trois types de SLI acceptés :

• Un SLI de base, créé automatiquement pour les instances du type de service BasicService. Ce type de SLI est décrit dans la section Objectifs de niveau de service. Il est représenté par un objet BasicSli, et mesure la disponibilité ou la latence.

• Un SLI basé sur des requêtes, que vous pouvez utiliser pour comptabiliser les événements représentant un service acceptable. Ce type de SLI, qui est décrit dans la section SLO basés sur des requêtes, est représenté par un objet RequestBasedSli.

• Un SLI basé sur des fenêtres, que vous pouvez utiliser pour comptabiliser les périodes répondant à un critère de satisfaction. Ce type de SLI, qui est décrit dans la section SLO basés sur des fenêtres, est représenté par un objet WindowsBasedSli.

Par exemple, voici un SLI de disponibilité de base :

{
  "basicSli": {
    "availability": {},
    "location": [
      "us-central1-c"
    ]
  }
}

Structures des SLI basés sur des requêtes

Un SLI basé sur des requêtes repose sur une métrique qui comptabilise les unités de service sous la forme d'un ratio entre un résultat particulier et une valeur totale. Par exemple, si vous utilisez une métrique qui comptabilise des requêtes, vous pouvez établir le ratio entre le nombre de requêtes qui affichent un état de réussite et le nombre total de requêtes.

Il existe deux façons de créer un SLI basé sur des requêtes :

• En tant que TimeSeriesRatio, lorsque le ratio entre service satisfaisant et service total est calculé à partir de deux séries temporelles dont les valeurs ont le type de métrique DELTA ou CUMULATIVE.
• En tant que DistributionCut, lorsque le type de valeur de la série temporelle est DISTRIBUTION et que le type de métrique des valeurs est DELTA ou CUMULATIVE. La valeur indiquant un service satisfaisant correspond au nombre d'éléments compris dans les buckets d'histogrammes d'une plage spécifiée. Le total correspond au nombre total de valeurs dans la distribution.

Vous trouverez ci-dessous la représentation JSON d'un SLI utilisant un ratio de séries temporelles :

{
  "requestBased": {
    "goodTotalRatio": {
      "totalServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count"",
      "goodServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count" metric.label.response_code_class=200",
    }
  }
}

Les séries temporelles dans ce ratio sont identifiées par une paire de valeurs composée du type de ressource surveillée et du type de métrique :

• Ressource : https_lb_rule
• Type de métrique : loadbalancing.googleapis.com/https/request_count

La valeur de totalServiceFilter est représentée par la paire métrique - type de ressource. La valeur de goodServiceFilter est représentée par la même paire, mais dans laquelle une étiquette a une valeur particulière ; dans ce cas, lorsque la valeur de l'étiquette response_code_class est 200.

Le rapport entre les filtres mesure le nombre de requêtes qui renvoient un état HTTP 2xx par rapport au nombre total de requêtes.

Vous trouverez ci-dessous la représentation JSON d'un SLI utilisant une coupe de distribution :

{
  "requestBased": {
    "distribution_cut": {
      "distribution_filter": "resource.type=https_lb_rule  metric.type="loadbalancing.googleapis.com/https/backend_latencies" metric.label.response_code_class=200",
      "range": {
        "min": "-Infinity",
        "max": 500.0
      }
    }
  }
}

La série temporelle est identifiée par le type de ressource surveillée, le type de métrique et la valeur d'une étiquette de métrique :

• Ressource : https_lb_rule
• Type de métrique : loadbalancing.googleapis.com/https/backend_latencies
• Paire étiquette-valeur : response_code_class = 200

La plage de latences considérée comme correcte est indiquée par le champ range. Ce SLI calcule le ratio entre les latences des réponses de classe 2xx inférieures à 500 et les latences de toutes les réponses de classe 200.

Structures des SLI basés sur des fenêtres

Un SLI basé sur des fenêtres comptabilise les périodes pendant lesquelles le service fourni est considéré comme satisfaisant. Le critère permettant de déterminer si un service est satisfaisant fait partie de la définition du SLI.

Tous les SLI Windows incluent une période de 60 à 86 400 secondes (1 jour).

Il existe deux façons de spécifier le critère de service satisfaisant pour un SLI basé sur des fenêtres :

• Créez une chaîne de filtre, décrite sur la page Filtres de surveillance, qui renvoie une série temporelle avec des valeurs booléennes. Une fenêtre est correcte si sa valeur est true. Ce filtre s'appelle goodBadMetricFilter.

• Créez un objet PerformanceThreshold qui représente un seuil de performances acceptables. Cet objet est spécifié en tant que valeur de goodTotalRatioThreshold.

  Un objet PerformanceThreshold spécifie une valeur de seuil et un SLI de performances. Si la valeur du SLI de performances est supérieure ou égale à la valeur de seuil, la période est considérée comme correcte.

  Il existe deux façons de spécifier le SLI de performances :

  • En tant qu'objet BasicSli dans le champ basicPerformanceSli
  • En tant qu'objet RequestBasedSli dans le champ performance Si vous utilisez un SLI basé sur des requêtes, le genre de métrique de votre SLI doit être DELTA ou CUMULATIVE. Vous ne pouvez pas utiliser de métriques GAUGE dans les SLI basés sur les requêtes.

Voici la représentation JSON d'un SLI basé sur des fenêtres qui repose sur un seuil de performances pour un SLI de disponibilité de base :

{
  "windowsBased": {
     "goodTotalRatioThreshold": {
       "threshold": 0.9,
       "basicSliPerformance": {
         "availability": {},
         "location": [
           "us-central1-c"
         ]
       }
     },
     "windowPeriod": "300s"
   }
}

Ce SLI indique des performances satisfaisantes sous la forme d'une période de cinq minutes au cours de laquelle la disponibilité atteint ou dépasse 90 %. La structure d'un SLI de base est présentée dans la section Indicateurs de niveau de service.

Vous pouvez également intégrer un SLI basé sur des requêtes dans le SLI basé sur des fenêtres. Pour plus d'informations sur les structures intégrées, consultez la section Structures des SLI basés sur des requêtes.

Objectifs de niveau de service

Un objectif de niveau de service (SLO, Service Level Objective) est représenté par un objet ServiceLevelObjective. Cet objet inclut les champs suivants :

• Un nom
• Un nom à afficher
• Le SLI cible (un objet ServiceLevelIndicator intégré)
• L'objectif de performances pour le SLI
• La période de conformité pour le SLI

Voici la représentation JSON d'un SLO qui utilise un SLI de disponibilité de base comme valeur du champ serviceLevelIndicator :

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

Ce SLO définit l'objectif de performances sur une disponibilité de 98 % au cours d'une période d'une semaine.