Mit der API arbeiten

In diesem Dokument wird beschrieben, wie Sie Dienste und Service Level Objectives (SLOs) mithilfe der Cloud Monitoring API verwalten.

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

In diesem Dokument werden diese Hinzufügungen insgesamt als SLO API bezeichnet und es wird deren primäre Verwendung veranschaulicht. Eine allgemeine Übersicht über die Strukturen der SLO API finden Sie unter Konstrukte in der API. Umfassendes Referenzmaterial finden Sie unter Cloud Monitoring API v3.

Mit der SLO API haben Sie folgende Möglichkeiten:

Dienste erstellen und verwalten.
Erstellen Sie Service Level Objectives (SLOs) basierend auf benutzerdefinierten oder vordefinierten Service Level Indicators (SLIs) für jeden Ihrer Dienste.

Gültige Kennzeichnungen

Einige Methoden in der SLO API verwenden Kennzeichnungen für verschiedene Elemente, insbesondere IDs für Projekt und Dienste. Diese IDs unterliegen den folgenden Regeln:

Länge: 1–63 Zeichen
Zeichen: nur Kleinbuchstaben, Ziffern und Bindestriche
Anfangszeichen: Kleinbuchstabe
Letztes Zeichen: Kleinbuchstabe oder Ziffer, aber kein Bindestrich

Der reguläre Ausdruck für diese Regeln lautet: [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

Beispiele mit `curl`

In diesem Abschnitt werden die Konventionen und die Einrichtung für das Aufrufen der SLO API mithilfe des curl-Tools erläutert. Wenn Sie diese API über eine Clientbibliothek verwenden, können Sie diesen Abschnitt überspringen.

In den Beispielen auf dieser Seite wird über das curl-Tool auf die SLO API zugegriffen, um HTTP-Anfragen an REST-Endpunkte zu senden. Verwenden Sie die folgenden Informationen zur Authentifizierung und zum Aufrufen von curl, um die in den Aufrufen verwendeten Variablen festzulegen.

Authentifizierung

Erstellen Sie eine Umgebungsvariable, die die ID Ihres Scoping-Projekts eines Messwertbereichs enthält. In diesen Beispielen wird PROJECT_ID verwendet:
```
PROJECT_ID=my-test-service
```
Authentifizieren Sie sich in der Google Cloud CLI:
```
gcloud auth login
```
Damit Sie nicht bei jedem Befehl Ihre Projekt-ID angeben müssen, legen Sie sie mit der gcloud CLI als Standard-ID fest:
```
gcloud config set project ${PROJECT_ID}
```
Erstellen Sie ein Autorisierungstoken und erfassen Sie es in einer Umgebungsvariablen. In diesen Beispielen wird die Variable ACCESS_TOKEN aufgerufen:
```
ACCESS_TOKEN=`gcloud auth print-access-token`
```
Sie müssen das Zugriffstoken regelmäßig aktualisieren. Wenn zuvor funktionierende Befehle plötzlich melden, dass Sie nicht authentifiziert sind, führen Sie diesen Befehl noch einmal aus.
Bestätigen Sie, dass Sie ein Zugriffstoken erhalten haben. Geben Sie dazu die Variable ACCESS_TOKEN zurück:
```
echo ${ACCESS_TOKEN}
ya29.GluiBj8o....
```

`curl` aufrufen

Jeder curl-Aufruf umfasst eine Reihe von Argumenten, gefolgt von der URL einer SLO API-Ressource. Zu den häufig verwendeten Argumenten gehören Werte, die durch die Umgebungsvariablen PROJECT_ID und ACCESS_TOKEN angegeben werden. Möglicherweise müssen Sie auch andere Argumente angeben, um beispielsweise den Typ der HTTP-Anfrage anzugeben (z. B. -X DELETE). Die Standardanfrage ist GET. Daher wird sie in den Beispielen nicht angegeben.

Jeder curl-Aufruf hat diese allgemeine Struktur:

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

Wenn Sie beispielsweise alle Dienste in Ihrem Projekt auflisten möchten, senden Sie die folgende GET-Anfrage:

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

Dadurch wird ein Array von Dienstbeschreibungen mit Einträgen wie dem folgenden zurückgegeben: ein GKE-Arbeitslastdienst mit der Dienst-ID "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"
      }
    },
   ...
  ]
}

Die Konfiguration zum Erstellen dieses Dienstes finden Sie unter Dienst erstellen. Die Struktur gkeWorkload in dieser Liste wird von der Struktur basicService abgeleitet, die zum Erstellen des Dienstes verwendet wird. Weitere Informationen über die Struktur eines Dienstes finden Sie unter Service.

Dienste verwalten

Die Ressource Service fungiert als Stammelement für die Organisation Ihrer Dienste. Aspekte eines bestimmten Dienstes, z. B. dessen SLOs, werden unter dem Namen des Dienstes organisiert. Folgende Diensttypen werden unterstützt:

App Engine-Dienst: APP_ENGINE
Cloud Endpoints-Dienst: CLOUD_ENDPOINTS
Kanonischer Istio-Dienst: ISTIO_CANONICAL_SERVICE
Cluster-Istio-Dienst: CLUSTER_ISTIO
Cloud Run-Dienst: CLOUD_RUN
Eine Reihe an Google Kubernetes Engine-basierten Diensten:
- GKE-Dienst: GKE_SERVICE
- GKE-Namespace: GKE_NAMESPACE
- GKE-Arbeitslast: GKE_WORKLOAD
Benutzerdefinierte Dienste: CUSTOM

Weitere Informationen finden Sie unter Grundlegende Diensttypen oder Grundlegende GKE-Diensttypen.

Mit der API können Sie jedem Dienst in Ihrem Projekt SLOs hinzufügen. Die Verwaltung von SLOs umfasst Befehle zur Bearbeitung von SLOs.

Dienst-IDs

Jeder Dienst hat eine vollständig qualifizierte Kennzeichnung, die als Ressourcenname bezeichnet wird. Diese Kennzeichnung wird im Feld name der Dienstbeschreibung gespeichert. Beispiel:

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

In den Ressourcennamen ist eine kürzere ID für den Dienst eingebettet, der Teil des Ressourcennamens nach dem Teilstring projects/PROJECT_NUMBER/services/ ist.

Wenn Sie Ihren eigenen Dienst mit dem Ressourcennamen projects/PROJECT_NUMBER/services/my-test-service erstellt haben, lautet die Dienst-ID my-test-service.

Um es kurz zu halten und Fehlerquellen zu minimieren, wird bei vielen curl-Beispielen davon ausgegangen, dass die Dienst-ID in der Umgebungsvariablen SERVICE_ID enthalten ist, sodass Sie wiederholt darauf verweisen können.

Dienste auflisten

Rufen Sie die Methode services.list auf, um Informationen über alle Dienste in Ihrem Projekt abzurufen. Verwenden Sie die Methode services.get, um Informationen zu einem bestimmten Dienst anhand der Dienst-ID abzurufen:

Protokoll

Rufen Sie die Methode services.list oder services.get auf, um Informationen zu Diensten mithilfe von curl aufzulisten. Senden Sie dazu eine GET-Anfrage an:

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services, um alle Dienste aufzulisten
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID, um einen bestimmten Dienst zu erhalten

Die folgende Anfrage ruft beispielsweise Informationen über den Dienst ab, der durch den in der Umgebungsvariablen SERVICE_ID gespeicherten Wert identifiziert wurde:

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

Dienst erstellen

Geben Sie zum Erstellen eines Dienstes eine Darstellung des Diensttyps an und senden Sie ihn an die Methode services.create. Sie können die unter Grundlegende Diensttypen und Grundlegende GKE-Diensttypen beschriebenen Dienststrukturen nutzen.

Die Strukturen variieren, aber der Aufruf der API ist identisch. Sie müssen einen Anzeigenamen für den Dienst und ein basicService-Feld mit der Dienstdarstellung angeben.

Sie können optional die Dienst-ID angeben, die der Dienst haben soll. Das folgende Beispiel zeigt die Erstellung eines {[gke_name_short]}-Arbeitslastdienstes:

Protokoll

Senden Sie eine POST-Nachricht an den Endpunkt https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services, um den Dienst mithilfe von curl zu erstellen:

Wenn Sie eine ID für den Dienst angeben möchten, erstellen Sie eine Variable für die Dienst-ID:
```
SERVICE_ID=my-test-service
```
Dieser Wert wird im URL-Abfrageparameter service_id angegeben.

Erstellen Sie eine Variable, die den Anfragetext enthält, der den Dienst beschreibt:

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
)

Senden Sie den Anfragetext an den Endpunkt und geben Sie die Dienst-ID als Wert des Abfrageparameters service_id an:

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}

Beispiele für die Strukturen anderer Dienste finden Sie unter Einfache Diensttypen und Einfache GKE-Diensttypen.

Dienst löschen

Rufen Sie die services.delete-Methode auf und geben Sie die Dienst-ID an, um einen von Ihnen erstellten Dienst zu löschen.

Protokoll

Senden Sie eine DELETE-Anfrage an den Endpunkt https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID, um einen Dienst mithilfe von curl zu löschen:

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

SLOs verwalten

SLOs lassen sich mit der SLO API erstellen, löschen und abrufen. Für jeden Dienst sind bis zu 500 SLOs zulässig.

Sie benötigen die Dienst-ID, um SLOs für einen Dienst zu verwalten. SLOs werden in Anlehnung an den Dienst benannt, zu dem sie gehören. Informationen zur Identifizierung von Dienst-IDs finden Sie unter Dienst-IDs.

SLOs auflisten

Rufen Sie die Methode services.serviceLevelObjectives.list auf, um Informationen über alle SLOs abzurufen, die mit einem Dienst verknüpft sind. Verwenden Sie die Methode services.serviceLevelObjectives.get, um Informationen zu einem bestimmten SLO anhand des Namens abzurufen:

Protokoll

Rufen Sie die Methode services.serviceLevelObjectives.list oder services.serviceLevelObjectives.get auf, um Informationen zu Diensten mithilfe von curl aufzulisten. Senden Sie dazu eine GET-Anfrage an:

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives, um alle SLOs aufzulisten
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID, um ein bestimmtes SLO zu erhalten

Die folgende Anfrage listet beispielsweise alle SLOs auf, die der in der Umgebungsvariablen SERVICE_ID gespeicherten Dienst-ID zugeordnet sind:

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

Folgendes ist ein Verfügbarkeits-SLO, das vom Dienst "currencyservice" abgerufen wurde:

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

Dieses SLO basiert auf einem Verfügbarkeits-SLI, legt ein Leistungsziel von 98 % fest und misst die Compliance über eine Kalenderwoche hinweg. Weitere Informationen zu Verfügbarkeits-SLIs finden Sie unter Service Level Indicators.

Weitere Informationen über die Struktur von SLOs finden Sie unter ServiceLevelObjective.

Bestimmtes SLO abrufen

Jedes SLO hat eine eindeutige Kennzeichnung innerhalb des Dienstes, die aus dem String besteht, der im Feld name des SLO auf serviceLevelObjectives folgt. Im folgenden Beispiel gilt:

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

Die SLO-ID ist der String 3kavNVTtTMuzL7KcXAxqCQ.

Fragen Sie das SLO anhand der ID an, um Informationen zu diesem bestimmten SLO abzurufen.

Protokoll

Rufen Sie die Methode services.serviceLevelObjectives.get auf, um ein bestimmtes SLO mithilfe von curl zu erhalten. Senden Sie dazu eine GET-Anfrage an 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}

SLO erstellen

Zum Erstellen eines SLO mit der SLO API müssen Sie ein ServiceLevelObjective-Objekt anlegen und an die Methode serviceLevelObjectives.create übergeben.

Die Struktur eines SLO enthält viele eingebettete Strukturen, darunter eine für den Wert des Felds serviceLevelIndicator.

Für Cloud Service Mesh, Istio in Google Kubernetes Engine und App Engine-Dienste sind die SLIs vordefiniert. Sie können SLOs mit der Cloud Service Mesh-Konsole erstellen. Sie müssen lediglich die Leistungsziele und Compliance-Zeiträume angeben.
Für andere Dienste können SLOs nur mithilfe der SLO API erstellt werden. Um ein SLO anzugeben, müssen Sie auch einen Wert für das Feld serviceLevelIndicator erstellen. Informationen zu einigen Verfahren finden Sie unter Service Level Indicator erstellen und unter SLIs aus Messwerten erstellen finden Sie eine Reihe von Beispielen, die auf verschiedenen Quellen basieren.

Sie können SLIs auch mithilfe der Google Cloud Console erstellen. Weitere Informationen finden Sie unter SLO erstellen.

Layout eines SLO

Das grundlegende Layout zum Erstellen des SLO sieht so aus:

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

Sie müssen Folgendes angeben:

Den Anzeigenamen: eine Beschreibung des SLO
Einen Service Level Indicator, der zu einem der folgenden drei Typen gehört:
Das Leistungsziel (ein Prozentsatz)
Den Compliance-Zeitraum, der zu einem der beiden folgenden Typen gehört:
- Ein rollierender Zeitraum einer bestimmten Länge (in Sekunden)
- Ein Kalenderzeitraum

Weitere Informationen zu SLIs, Leistungszielen und Compliancezeiträumen finden Sie unter Konzepte im Service Monitoring.

Bei Cloud Service Mesh, Istio in Google Kubernetes Engine und App Engine-Diensten ist der SLI-Typ der grundlegende SLI.

Für weitere Dienste müssen Sie einen anfragebasierten oder Windows-basierten SLI erstellen. Informationen zu einigen Verfahren finden Sie unter Service Level Indicator erstellen.

Beispiel

Nachdem Sie den SLI erstellt haben, können Sie das SLO erstellen. Im folgenden Beispiel wird ein SLO für einen Dienst definiert, der einen grundlegenden SLI verwendet. Möglicherweise gibt es mehrere SLOs für einen einzelnen SLI, z. B. einen für 95 % Verfügbarkeit und einen für 99 % Verfügbarkeit. Das folgende Beispiel zeigt ein SLO für eine Verfügbarkeit von 95 % innerhalb einer Kalenderwoche:

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

Dieses Beispiel zeigt ein SLO für eine Verfügbarkeit von 75 % über einen rollierenden Zeitraum von drei Tagen:

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

Protokoll

Senden Sie eine POST-Nachricht an den Endpunkt https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives, um ein SLO mithilfe von curl zu erstellen:

Variable für die Dienst-ID erstellen:
```
SERVICE_ID=custom:my-test-service
```

Erstellen Sie eine Variable, die den Anfragetext enthält, der eine Instanz des Objekts ServiceLevelObjective ist. In diesem Beispiel wird eines der zuvor beschriebenen SLOs verwendet:

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
)

Senden Sie den Anfragetext an den Endpunkt:

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

Optional können Sie auch eine gewünschte ID für das SLO als Wert des Abfrageparameters service_level_objective_id angeben:

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}

SLO löschen

Um ein SLO zu löschen, rufen Sie die Methode services.serviceLevelObjectives.delete auf und geben Sie die ID des SLO in Ihrem Projekt an:

Protokoll

Wenn Sie ein SLO mit curl löschen möchten, senden Sie eine DELETE-Anfrage an den Endpunkt 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}

Auf SLO-Zeitachsen zugreifen

SLO-Daten werden in Zeitachsen gespeichert, sodass Sie sie mit der Methode timeSeries.list abrufen können. Diese Daten werden jedoch nicht in standardmäßigen Messwerttypen gespeichert. Sie können also nicht den Standardmechanismus zur Angabe eines Messwertfilters für die Methode timeSeries.list verwenden.

Stattdessen werden SLO-Zeitachsen durch Angabe eines anderen Filtertyps, eines Zeitachsenselektors, für die Methode timeSeries.list im Parameter filter abgerufen. Informationen zur Verwendung dieser Selektoren finden Sie unter SLO-Daten abrufen.

Außerdem verwenden Sie Zeitachsenselektoren, um programmatisch Benachrichtigungsrichtlinien einzurichten. Weitere Informationen finden Sie unter Benachrichtigung über Ihre Brennrate.

Mit der API arbeiten

Gültige Kennzeichnungen

Beispiele mit curl

Authentifizierung

curl aufrufen

Dienste verwalten

Dienst-IDs

Dienste auflisten

Protokoll

Dienst erstellen

Protokoll

Dienst löschen

Protokoll

SLOs verwalten

SLOs auflisten

Protokoll

Bestimmtes SLO abrufen

Protokoll

SLO erstellen

Layout eines SLO

Beispiel

Protokoll

SLO löschen

Protokoll

Auf SLO-Zeitachsen zugreifen

Beispiele mit `curl`

`curl` aufrufen