Questo documento descrive come gestire i servizi e gli obiettivi del livello di servizio (SLO) utilizzando l'API Cloud Monitoring.
Service Monitoring aggiunge le seguenti risorse all'API Monitoring:
Questo documento fa riferimento a queste aggiunte collettivamente come API SLO e illustra gli utilizzi principali. Per una panoramica generale delle strutture nell'API SLO, consulta Costrutti nell'API. Il materiale di riferimento completo è disponibile in API Cloud Monitoring v3.
Puoi utilizzare l'API SLO per:
Creare e gestire i servizi.
Crea obiettivi del livello di servizio (SLO) in base a indicatori del livello del servizio (SLI) personalizzati o predefiniti per tutti i tuoi servizi.
Identificatori validi
Diversi metodi nell'API SLO utilizzano identificatori per elementi diversi, in particolare per progetti e servizi. Questi ID rispettano le seguenti regole:
- Lunghezza: 1-63 caratteri
- Caratteri: solo lettere minuscole, numeri e trattini
- Carattere iniziale: lettera minuscola
- Carattere terminale: lettera minuscola o un numero, ma non un trattino
L'espressione regolare per queste regole è la seguente:
[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?
Esempi che utilizzano curl
Questa sezione descrive le convenzioni e la configurazione utilizzate per richiamare l'API SLO mediante lo strumento curl
. Se usi quest'API tramite una libreria client, puoi saltare questa sezione.
Gli esempi in questa pagina accedono all'API SLO utilizzando lo
strumento curl
per inviare richieste HTTP agli endpoint REST. Utilizza le seguenti informazioni sull'autenticazione e sul richiamo di curl
per impostare le variabili utilizzate nelle chiamate.
Autenticazione
Crea una variabile di ambiente che contenga l'ID del progetto di ambito di un ambito delle metriche. In questi esempi viene utilizzato
PROJECT_ID
:PROJECT_ID=my-test-service
Esegui l'autenticazione in Google Cloud CLI:
gcloud auth login
Per evitare di dover specificare l'ID progetto con ciascun comando, impostalo come valore predefinito utilizzando gcloud CLI:
gcloud config set project ${PROJECT_ID}
Creare un token di autorizzazione e acquisirlo in una variabile di ambiente. Questi esempi chiamano la variabile
ACCESS_TOKEN
:ACCESS_TOKEN=`gcloud auth print-access-token`
Devi aggiornare periodicamente il token di accesso. Se i comandi che hanno funzionato improvvisamente segnalano che non hai eseguito l'autenticazione, invia di nuovo questo comando.
Per verificare di aver ricevuto un token di accesso, esegui l'eco della variabile
ACCESS_TOKEN
:echo ${ACCESS_TOKEN} ya29.GluiBj8o....
Richiamo di curl
in corso...
Ogni chiamata a curl
include un set di argomenti,
seguito dall'URL di una risorsa dell'API SLO. Gli argomenti comuni includono i valori specificati dalle variabili di ambiente PROJECT_ID
e ACCESS_TOKEN
.
Potresti anche dover specificare altri argomenti, ad esempio per specificare il tipo
di richiesta HTTP (ad esempio, -X DELETE
). La richiesta predefinita è GET
,
quindi gli esempi non la specificano.
Ogni chiamata curl
ha questa struttura generale:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
Ad esempio, per elencare tutti i servizi nel tuo progetto, invia la seguente richiesta GET
:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services
Questa richiesta restituisce un array di descrizioni dei servizi, con voci come la seguente: un servizio per carichi di lavoro GKE con ID servizio "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" } }, ... ] }
Per visualizzare la configurazione utilizzata per creare questo servizio, consulta Creazione di un servizio. Tieni presente che la struttura gkeWorkload
in questa scheda
deriva dalla struttura basicService
utilizzata per creare il servizio.
Consulta Service
per ulteriori informazioni sulla struttura di un servizio.
Gestione dei servizi
La risorsa Service
funge da elemento principale per l'organizzazione
dei servizi. Gli aspetti di un particolare servizio, come ad esempio i relativi SLO, sono organizzati sotto il nome del servizio. Sono supportati i seguenti tipi di servizi:
- Servizio App Engine:
APP_ENGINE
- Servizio Cloud Endpoints:
CLOUD_ENDPOINTS
- Servizio Istio canonico:
ISTIO_CANONICAL_SERVICE
- Servizio Istio del cluster:
CLUSTER_ISTIO
- Servizio Cloud Run:
CLOUD_RUN
- Un insieme di servizi basati su Google Kubernetes Engine:
- Servizio GKE:
GKE_SERVICE
- Spazio dei nomi GKE:
GKE_NAMESPACE
- Carico di lavoro GKE:
GKE_WORKLOAD
- Servizio GKE:
- Servizi personalizzati:
CUSTOM
Per ulteriori informazioni, consulta Tipi di servizi di base o Tipi di servizi GKE di base.
Puoi aggiungere SLO a qualsiasi servizio nel tuo progetto utilizzando l'API. La gestione degli SLO copre i comandi per manipolare gli SLO.
ID servizio
Ogni servizio ha un identificatore completo denominato nome risorsa. Questo identificatore è archiviato nel campo name
della descrizione del servizio, ad esempio:
"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",
Incorporato nel nome della risorsa è un ID più breve per il servizio, la parte del nome della risorsa dopo la sottostringa
projects/PROJECT_NUMBER/services/
Se hai creato il tuo servizio con il nome risorsa
projects/PROJECT_NUMBER/services/my-test-service
, l'ID servizio è
my-test-service
.
Per brevità e precisione, molti esempi di curl
presuppongono che l'ID servizio sia mantenuto nella variabile di ambiente SERVICE_ID
, in modo da potervi far riferimento ripetutamente.
Elenco dei servizi
Per recuperare informazioni su tutti i servizi nel tuo progetto, richiama
il metodo services.list
. Per recuperare le informazioni su un servizio specifico in base all'ID servizio, utilizza il metodo services.get
:
Protocollo
Per elencare le informazioni sui servizi utilizzandocurl
, richiama il metodo services.list
o services.get
inviando una richiesta GET
a:
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
per elencare tutti i servizihttps://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID
per usufruire di un servizio specifico
Ad esempio, la seguente richiesta recupera informazioni sul servizio identificato dal valore archiviato nella variabile di ambiente SERVICE_ID
:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}
crea un servizio
Per creare un servizio, devi specificare una rappresentazione del tipo di servizio e inviarla al metodo services.create
.
Puoi utilizzare le strutture del tipo di servizio descritte in Tipi di servizi di base e Tipi di servizi GKE di base.
Le strutture variano, ma il processo per chiamare l'API è lo stesso.
Devi specificare un nome visualizzato per il servizio e un campo basicService
contenente la rappresentazione del servizio.
Facoltativamente, puoi specificare l'ID servizio che vuoi assegnare al servizio. L'esempio seguente mostra la creazione di un servizio per i carichi di lavoro {[gke_name_short}}:
Protocollo
Per creare il servizio utilizzando curl
, invia un messaggio POST
all'endpoint
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
:
Se vuoi fornire un ID per il servizio, crea una variabile per l'ID servizio:
SERVICE_ID=my-test-service
Questo valore viene fornito nel parametro di query dell'URL
service_id
.Crea una variabile in cui inserire il corpo della richiesta che descrive il servizio:
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 )
Pubblica il corpo della richiesta nell'endpoint e specifica l'ID servizio come valore del parametro di query
service_id
: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}
Per esempi delle strutture associate ad altri servizi, consulta Tipi di servizi di base o Tipi di servizi GKE di base.
Eliminazione di un servizio
Per eliminare un servizio che hai creato, richiama il metodo services.delete
e specifica l'ID servizio.
Protocollo
Per eliminare un servizio utilizzandocurl
, invia una richiesta DELETE
all'endpoint
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID
:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}
Gestione degli SLO
Puoi creare, eliminare e recuperare gli SLO utilizzando l'API SLO. Puoi avere fino a 500 SLO per ogni servizio.
Per gestire gli SLO per un servizio, devi avere l'ID servizio. Gli SLO vengono denominati in base al servizio a cui appartengono. Per informazioni sull'identificazione degli ID servizio, consulta ID servizio.
SLO della scheda
Per recuperare le informazioni su tutti gli SLO associati a un servizio, richiama
il metodo services.serviceLevelObjectives.list
.
Per recuperare le informazioni su uno SLO specifico in base al nome, utilizza il metodo services.serviceLevelObjectives.get
:
Protocollo
Per elencare le informazioni sui servizi utilizzandocurl
, richiama il metodo services.serviceLevelObjectives.list
o services.serviceLevelObjectives.get
inviando una richiesta GET
a:
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives
per elencare tutti gli SLOhttps://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID
per ottenere uno SLO specifico
Ad esempio, la seguente richiesta elenca tutti gli SLO associati all'ID servizio archiviato nella variabile di ambiente SERVICE_ID
:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives
Di seguito è riportato uno SLO di disponibilità recuperato dal servizio "currencyservice":
{ "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", },
Questo SLO è basato su uno SLI di disponibilità, imposta un obiettivo di prestazioni target del 98% e misura la conformità nell'arco di una settimana di calendario. Per ulteriori informazioni sugli SLI di disponibilità, consulta Indicatori del livello del servizio.
Per ulteriori informazioni sulla struttura degli SLO, consulta ServiceLevelObjective
.
Recupero di uno SLO specifico
Ogni SLO ha un identificatore univoco all'interno del servizio, costituito dalla stringa che segue
serviceLevelObjectives
nel campo name
dello SLO. Nell'esempio seguente:
"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
l'ID SLO è la stringa 3kavNVTtTMuzL7KcXAxqCQ
.
Per recuperare informazioni su questo particolare SLO, richiedi lo SLO per ID.
Protocollo
Per ottenere uno SLO specifico utilizzandocurl
, richiama il metodo services.serviceLevelObjectives.get
inviando una richiesta GET
a 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}
Creazione di uno SLO
Per creare uno SLO utilizzando l'API SLO, devi creare un oggetto ServiceLevelObjective
e passarlo al metodo serviceLevelObjectives.create
.
La struttura di uno SLO ha molte strutture incorporate, inclusa una per il valore del campo serviceLevelIndicator
.
Per i servizi Cloud Service Mesh, Istio su Google Kubernetes Engine e App Engine, gli SLI sono predefiniti. Puoi utilizzare la console di Cloud Service Mesh per creare gli SLO; non devi fare altro che specificare gli obiettivi di prestazioni e i periodi di conformità.
Per gli altri servizi, devi definire gli SLO utilizzando l'API SLO. Per specificare uno SLO, devi anche creare un valore per il campo
serviceLevelIndicator
. Consulta Creazione di un indicatore del livello del servizio per alcune tecniche e Creazione di SLI dalle metriche per un insieme di esempi basati su varie origini.
Puoi creare SLI anche utilizzando la console Google Cloud. Per maggiori informazioni, consulta la pagina Creazione di uno SLO.
Scheletro di uno SLO
Lo scheletro di base per creare lo SLO è il seguente:
{ "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. }
Devi specificare quanto segue:
- Nome visualizzato: una descrizione dello SLO
- Un indicatore del livello del servizio, che è uno dei tre tipi:
- L'obiettivo di rendimento (una percentuale)
- Il periodo di conformità, uno dei due tipi seguenti:
- Un periodo continuativo di una certa durata (in secondi)
- Un periodo di calendario
Per ulteriori informazioni su SLI, obiettivi di prestazioni e periodi di conformità, consulta Concetti nel monitoraggio dei servizi.
Per i servizi Cloud Service Mesh, Istio su Google Kubernetes Engine e App Engine, il tipo SLI è lo SLI di base.
Per gli altri servizi, devi creare uno SLI basato su richiesta o uno SLI basato su Windows. Per alcune tecniche, consulta la pagina Creazione di un indicatore del livello del servizio.
Esempio
Una volta ottenuto lo SLI, puoi creare lo SLO. L'esempio seguente definisce uno SLO per un servizio che utilizza uno SLI di base. Potresti avere diversi SLO su un singolo SLI, ad esempio, uno per la disponibilità del 95% e uno per la disponibilità del 99%. L'esempio seguente è uno SLO per la disponibilità del 95% su una settimana di calendario:
{ "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.95, "calendarPeriod": "WEEK", "displayName": "95% Availability in Calendar Week" }
Questo esempio specifica uno SLO per una disponibilità del 75% su un periodo continuativo di 3 giorni:
{ "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.75, "rollingPeriod": "259200s", "displayName": "75% Availability in Rolling 3 Days" }
Protocollo
Per creare uno SLO utilizzandocurl
, invia un messaggio POST
all'endpoint
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives
:
Crea una variabile per l'ID servizio:
SERVICE_ID=custom:my-test-service
Crea una variabile per contenere il corpo della richiesta, un'istanza dell'oggetto
ServiceLevelObjective
. Questo esempio utilizza uno degli SLO descritti in precedenza: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 )
Pubblica il corpo della richiesta nell'endpoint:
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
Facoltativamente, puoi anche specificare un ID desiderato per lo SLO come valore del parametro di query
service_level_objective_id
: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}
Eliminazione di uno SLO
Per eliminare uno SLO, richiama il metodo services.serviceLevelObjectives.delete
e specifica l'ID dello SLO nel tuo progetto:
Protocollo
Per eliminare uno SLO utilizzandocurl
, invia una richiesta DELETE
all'endpoint
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}
Accesso alle serie temporali dello SLO
I dati degli SLO vengono archiviati in serie temporali, quindi puoi utilizzare il metodo timeSeries.list
per recuperarli.
Tuttavia, questi dati non vengono archiviati nei tipi di metriche standard, quindi non puoi utilizzare il meccanismo standard di specificare un filtro di tipo metrica per il metodo timeSeries.list
.
Le serie temporali dello SLO vengono invece recuperate specificando un altro tipo di filtro, un selettore di serie temporali, per il metodo timeSeries.list
nel parametro filter
.
Consulta Recupero dei dati dello SLO per informazioni sull'uso di questi selettori.
Puoi anche utilizzare i selettori delle serie temporali per configurare i criteri di avviso in modo programmatico. Per ulteriori informazioni, consulta Avvisi sul tasso di combustione.