Service Monitoring fügt der Monitoring API die folgenden Ressourcen hinzu:
Auf dieser Seite 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 können Sie Dienste und Service Level Objectives (SLOs) verwalten. Auf dieser Seite geht es um benutzerdefinierte Dienste und Service-Level-Indikatoren (SLIs). Dienste in Anthos Service Mesh, in Istio in Google Kubernetes Engine und in App Engine werden automatisch erkannt. Die SLIs dafür sind vordefiniert.
Sie können SLIs auch mithilfe der Google Cloud Console erstellen. Weitere Informationen finden Sie unter SLO erstellen.
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, die die ID des Hostprojekts Ihres Arbeitsbereichs enthält. 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 Methodeservices.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 aufzulistenhttps://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 eineDELETE
-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 Methodeservices.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 aufzulistenhttps://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 Methodeservices.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 einePOST
-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 mitcurl
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.