Mit der API arbeiten

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

Auf dieser Seite wird die primäre Verwendung der neuen API-Ressourcen dargestellt. Einen allgemeinen Überblick über die hier verwendeten Strukturen finden Sie unter Konstrukte in der API. Umfassendes Referenzmaterial finden Sie unter Cloud Monitoring API v3.

In diesem Dokument werden die Ergänzungen insgesamt als SLO API bezeichnet.

Wann sollte die API verwendet werden?

Mit der SLO API können Dienste und Service Level Objectives (SLOs) verwaltet werden. Auf dieser Seite geht es um benutzerdefinierte Dienste und Service-Level-Indikatoren (SLIs). Dienste in Anthos Service Mesh, Istio in Google Kubernetes Engine und App Engine werden automatisch erkannt. Die SLIs dafür sind vordefiniert:

Zum Definieren von SLOs für Anthos Service Mesh-Dienste können Sie die Anthos Service Mesh-Konsole oder die SLO API verwenden. Weitere Informationen zum Erstellen von SLOs mit dem Anthos Service Mesh-Dashboard finden Sie in der Anthos Service Mesh-Dokumentation: SLOs erstellen.
Für andere Dienste und für benutzerdefinierte Dienste müssen Sie SLOs mithilfe der SLO API definieren. Derzeit wird die Google Cloud Console nicht unterstützt.

Die Beispiele auf dieser Seite beziehen sich hauptsächlich auf benutzerdefinierte Dienste und SLIs.

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.

Authentication

Erstellen Sie eine Umgebungsvariable für die ID Ihres Cloud Monitoring-Arbeitsbereichs. In diesen Beispielen wird PROJECT_ID verwendet:
```
PROJECT_ID=my-test-service
```
Authentifizieren Sie sich beim Cloud SDK:
```
gcloud auth login
```
Damit Sie nicht bei jedem Befehl Ihre Projekt-ID angeben müssen, legen Sie sie mit dem Cloud SDK 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, der ein Istio-Dienst mit dem Namen "currencyservice" ist:

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

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.

Dienste in Anthos Service Mesh, Istio in Google Kubernetes Engine und App Engine werden automatisch erstellt. Sie können diesen Diensten SLOs mithilfe der Anthos Service Mesh-Konsole oder der SLO API hinzufügen.

Dienste, die Sie manuell erstellen, werden als benutzerdefinierte Dienste bezeichnet. Benutzerdefinierte Dienste können nur mithilfe der SLO API erstellt, gelöscht, abgerufen und aktualisiert werden.

Nachdem Sie einen Dienst identifiziert oder erstellt haben, können Sie ihm SLOs zuweisen. 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

Wenn Sie keine Umgebung verwenden, in der Dienste automatisch erstellt werden (also Anthos Service Mesh, Istio in Google Kubernetes Engine und App Engine), können Sie Dienste mit der Methode services.create anlegen.

Wenn Sie Dienste manuell erstellen, müssen Sie die SLOs und andere Dienst-Monitoring-Artefakte manuell in die Dienststruktur einfügen. Dazu verwenden Sie die SLO API. Einen Überblick über diese Strukturen finden Sie unter Konstrukte in der API.

Sie müssen einen Anzeigenamen für den Dienst und ein Feld mit dem Namen custom mit einem leeren Objekt angeben, um einen Dienst zu erstellen. Sie können optional die Dienst-ID angeben, die der Dienst haben soll.

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

Dienst löschen

Rufen Sie die Methode services.delete auf und geben Sie die Dienst-ID an, um einen benutzerdefinierten 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 sind mit Diensten verknüpft. Sie können SLOs mithilfe der Anthos Service Mesh-Konsole für Anthos Service Mesh, Istio in Google Kubernetes Engine und App Engine oder mithilfe der SLO API erstellen. SLOs für benutzerdefinierte Dienste können nur mit der SLO API erstellt werden.

Die SLO API bietet auch die Möglichkeit, die mit einem Dienst verknüpften SLOs abzurufen und SLOs aus einem Dienst zu löschen. 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. Unter Dienst-IDs wird beschrieben, wie Sie Dienst-IDs erkennen.

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 Anthos Service Mesh, Istio in Google Kubernetes Engine und App Engine-Dienste sind die SLIs vordefiniert. Sie können SLOs mit der Anthos Service Mesh-Konsole erstellen. Sie müssen lediglich die Leistungsziele und Compliance-Zeiträume angeben.

SLOs lassen sich auch mithilfe der SLO API definieren.
Für benutzerdefinierte 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.

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 Anthos Service Mesh, Istio in Google Kubernetes Engine und App Engine-Diensten ist der SLI-Typ der grundlegende SLI.

Für benutzerdefinierte 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

Wann sollte die API verwendet werden?

Gültige Kennzeichnungen

Beispiele mit curl

Authentication

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