Konstrukte in der API

In diesem Dokument werden die Strukturen zur Darstellung von Diensten und SLOs in der SLO API erläutert und den Konzepten zugeordnet, die unter Konzepte im Dienst-Monitoring allgemein beschrieben werden.

Mit der SLO API werden Service Level Objectives (SLOs) eingerichtet, mit denen der Status Ihrer Dienste überwacht werden kann.

Service Monitoring fügt der Monitoring API die folgenden Ressourcen hinzu:

Informationen zum Aufrufen der API finden Sie unter Arbeiten mit der API.

Dienste

Ein Dienst wird durch ein Service-Objekt dargestellt. Dieses Objekt enthält die folgenden Felder:

  • Einen Namen: ein vollständig qualifizierter Ressourcenname für diesen Dienst
  • Einen Anzeigenamen: Ein Label zur Verwendung in Konsolenkomponenten
  • Eine Struktur für einen der BasicService-Typen.
  • Ein vom System bereitgestelltes Telemetrie-Konfigurationsobjekt

Wenn Sie einen grundlegenden Dienst definieren möchten, geben Sie den Diensttyp und eine Reihe von dienstspezifischen Labels an, die den Dienst beschreiben:

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

Die folgenden Abschnitte enthalten Beispiele für jeden Diensttyp.

Grundlegende Diensttypen

Dieser Abschnitt enthält Beispiele für Dienstdefinitionen, die auf dem Typ BasicService basieren, wobei der Wert des Felds serviceType einer der folgenden ist:

  • APP_ENGINE
  • CLOUD_ENDPOINTS
  • CLUSTER_ISTIO
  • ISTIO_CANONICAL_SERVICE
  • CLOUD_RUN

Jeder dieser Diensttypen verwendet den Service Level Indicator 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"
          },
      },
    }

Kanonischer Istio-Dienst 

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

Grundlegende GKE-Diensttypen

Dieser Abschnitt enthält Beispiele für GKE-Dienstdefinitionen, die auf dem Typ BasicService basieren, wobei der Wert des Felds serviceType einer der folgenden ist:

  • GKE_NAMESPACE
  • GKE_WORKLOAD
  • GKE_SERVICE

Sie müssen SLIs für diese Diensttypen definieren. Es können keine BasicSli-SLIs (Service Level Indicators) verwendet werden. Weitere Informationen finden Sie unter Service Level Indicators.

GKE-Namespace 

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

GKE-Arbeitslast 

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

GKE-Dienst 

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

Benutzerdefinierte Dienste

Sie können benutzerdefinierte Dienste erstellen, wenn keiner der grundlegenden Diensttypen geeignet ist. Ein benutzerdefinierter Dienst sieht so aus:

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

Sie müssen SLIs für diese Diensttypen definieren. Es können keine BasicSli-SLIs (Service Level Indicators) verwendet werden. Weitere Informationen finden Sie unter Service Level Indicators.

Service Level Indicators

Ein Service Level Indicator (SLI) liefert ein Maß für die Leistung eines Dienstes. Ein SLI basiert auf dem vom Dienst erfassten Messwert. Die genaue Definition des SLI hängt vom Typ des Messwerts ab, der als Indikatormesswert verwendet wird. In der Regel wird er jedoch anhand eines Vergleichs zwischen akzeptablen Ergebnissen und Gesamtergebnissen ermittelt.

Ein SLI wird durch das Objekt ServiceLevelIndicator dargestellt. Dieses Objekt bietet die Möglichkeit, die drei unterstützten Arten von SLIs zusammengefasst zu referenzieren:

  • Ein grundlegender SLI, der automatisch für Instanzen des BasicService-Diensttyps erstellt wird. Dieser SLI-Typ wird unter Service Level Objectives beschrieben. Er wird durch das Objekt BasicSli dargestellt und misst die Verfügbarkeit oder Latenz.

  • Ein anfragebasierter SLI, mit dem Sie Ereignisse zählen können, die einen akzeptablen Dienst darstellen. Die Verwendung dieses SLI-Typs wird unter Anfragebasierte SLOs beschrieben und er wird durch ein Objekt RequestBasedSli dargestellt.

  • Ein Zeitfenster-SLI, mit dem Sie Zeiträume zählen können, die bestimmte Gütekriterien erfüllen. Die Verwendung dieses SLI-Typs wird unter zeitfensterbasierte SLOs beschrieben und er wird durch ein Objekt WindowsBasedSli dargestellt.

Nachstehend sehen Sie zum Beispiel einen grundlegenden Verfügbarkeits-SLI:

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

Strukturen anfragebasierter SLIs

Einem anfragebasierten SLI liegt ein Messwert zugrunde, der Diensteinheiten als Verhältnis zwischen einem bestimmten Ergebnis und dem Gesamtwert zählt. Wenn Sie beispielsweise einen Messwert verwenden, der Anfragen zählt, können Sie das Verhältnis zwischen der Anzahl der Anfragen, die erfolgreich verarbeitet werden, und der Gesamtzahl der Anfragen ermitteln.

Es gibt zwei Möglichkeiten, einen anfragebasierten SLI zu erstellen:

  • Als TimeSeriesRatio, wenn das Verhältnis zwischen erfolgreichen Dienstvorgängen und deren Gesamtzahl aus zwei Zeitachsen berechnet wird, deren Werte die Messwertart DELTA oder CUMULATIVE haben.
  • Als DistributionCut, wenn die Zeitreihe den Werttyp DISTRIBUTION hat und dessen Werte von der Messwertart DELTA oder CUMULATIVE sind. Der Wert der erfolgreichen Dienstvorgänge ist die Anzahl der Elemente, die in die Histogramm-Buckets eines bestimmten Bereichs fallen, und die Gesamtzahl ist die Anzahl aller Werte in der Verteilung.

Im Folgenden sehen Sie die JSON-Darstellung eines SLI, der auf einem Zeitachsenverhältnis beruht:

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

Die Zeitachsen in diesem Verhältnis werden anhand des Paares aus überwachtem Ressourcentyp und Messwerttyp ermittelt:

  • Ressource: https_lb_rule
  • Messwerttyp: loadbalancing.googleapis.com/https/request_count

Der Wert für totalServiceFilter wird durch das Paar aus Messwert und Ressourcentyp dargestellt. Der Wert für goodServiceFilter wird durch dasselbe Paar dargestellt, doch hat dabei ein Label einen bestimmten Wert. In diesem Fall hat das Label response_code_class den Wert 200.

Das Verhältnis zwischen den Filtern misst die Anzahl der Anfragen, die einen HTTP-Status "2xx" zurückgeben, gemessen an der Gesamtzahl der Anfragen.

Nachstehend sehen Sie die JSON-Darstellung eines SLI, der auf einem Verteilungsschnitt beruht:

{
  "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
      }
    }
  }
}

Die Zeitreihe wird durch den Typ der überwachten Ressource, den Messwerttyp und den Wert eines Messwertlabels identifiziert:

  • Ressource: https_lb_rule
  • Messwerttyp: loadbalancing.googleapis.com/https/backend_latencies
  • Label-Wert-Paar: response_code_class = 200

Der Bereich der als gut bewerteten Latenzen wird durch das Feld range definiert. Dieser SLI berechnet das Verhältnis der Latenzen von Antworten der 2x-Klasse unter 500 zu den Latenzen aller Antworten der 200er-Klasse.

Strukturen Zeitfenster-basierter SLIs

Dieser SLI zählt Zeitfenster, in denen der bereitgestellte Dienst als gut eingestuft wird. Das Kriterium zur Bestimmung, wie gut der Dienst ist, ist Teil der SLI-Definition.

Alle Windows-basierten SLIs enthalten einen Zeitraum von 60 bis 86.400 Sekunden (1 Tag).

Es gibt zwei Möglichkeiten, bei zeitfensterbasierten SLIs das Kriterium für die Dienstgüte festzulegen:

  • Erstellen Sie einen Filterstring, wie unter Monitoring-Filter erläutert, der eine Zeitreihe mit booleschen Werten zurückgibt. Ein Zeitfenster wird als gut erachtet, wenn der Wert für dieses Fenster true ist. Dieser Filter wird als goodBadMetricFilter bezeichnet.

  • Erstellen Sie ein PerformanceThreshold-Objekt, das einen Schwellenwert für eine akzeptable Leistung darstellt. Dieses Objekt wird als Wert von goodTotalRatioThreshold angegeben.

    Ein Objekt PerformanceThreshold gibt einen Grenzwert und einen Leistungs-SLI an. Wenn der Wert des Leistungs-SLI den Grenzwert erreicht oder überschreitet, wird das Zeitfenster als gut gewertet.

    Es gibt zwei Möglichkeiten zur Angabe von Leistungs-SLI:

Im Folgenden sehen Sie die JSON-Darstellung eines zeitfensterbasierten SLI, der auf dem Leistungsgrenzwert eines grundlegenden Verfügbarkeits-SLI beruht:

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

Dieser SLI definiert eine gute Leistung als 5-Minuten-Fenster, in dem die Verfügbarkeit 90 % oder mehr erreicht. Die Struktur eines grundlegenden SLI wird unter Service Level Indicators gezeigt.

Sie können auch einen anfragebasierten SLI in den zeitfensterbasierten SLI einbetten. Weitere Informationen zu eingebetteten Strukturen finden Sie unter Strukturen anfragebasierter SLIs.

Service Level Objectives

Ein Service Level Objective (SLO) wird durch ein Objekt ServiceLevelObjective dargestellt. Dieses Objekt enthält die folgenden Felder:

  • Einen Namen
  • Einen Anzeigenamen
  • Den Ziel-SLI; ein eingebettetes Objekt ServiceLevelIndicator
  • Das Leistungsziel für den SLI
  • Den Compliancezeitraum für den SLI

Im Folgenden sehen Sie die JSON-Darstellung eines SLO, das einen grundlegenden Verfügbarkeits-SLI als Wert für das Feld serviceLevelIndicator verwendet:

{
   "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"
}

Dieses SLO legt das Leistungsziel auf 98 % Verfügbarkeit über einen Zeitraum von einer Woche fest.