Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Utilizza l'API

Questo documento descrive come gestire i servizi e gli obiettivi del livello di servizio (SLO) utilizzando l'API Cloud Monitoring.

Il monitoraggio dei servizi aggiunge le seguenti risorse all'API Monitoring:

Questo documento si riferisce a queste aggiunte collettivamente come API SLO e ne 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.
Creare obiettivi del livello di servizio (SLO) basati su indicatori del livello del servizio (SLI) personalizzati o predefiniti per uno qualsiasi dei tuoi servizi.

Identificatori validi

Diversi metodi nell'API SLO utilizzano identificatori per diversi elementi, in particolare identificatori per progetti e servizi. Questi ID rispettano le seguenti regole:

Lunghezza: da 1 a 63 caratteri
Caratteri: solo lettere minuscole, numeri e trattini
Carattere iniziale: lettera minuscola
Carattere finale: 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 utilizzando lo strumento curl. Se utilizzi questa 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 sulla chiamata di curl per impostare le variabili utilizzate nelle chiamate.

Autenticazione

Crea una variabile di ambiente per contenere l'ID del progetto di scoping di un ambito delle metriche: questi esempi utilizzano PROJECT_ID:
```
PROJECT_ID=my-test-service
```
Esegui l'autenticazione con Google Cloud CLI:
```
gcloud auth login
```
Per evitare di dover specificare l'ID progetto con ogni comando, impostalo come predefinito utilizzando gcloud CLI:
```
gcloud config set project ${PROJECT_ID}
```
Crea un token di autorizzazione e acquisiscilo 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 funzionavano improvvisamente segnalano che non hai eseguito l'autenticazione, esegui 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....
```

Chiamata di `curl`

Ogni chiamata curl include un insieme 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 simili alla seguente, un servizio di workload GKE con l'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 questo elenco deriva dalla struttura basicService utilizzata per creare il servizio. Per saperne di più sulla struttura di un servizio, consulta Service.

Gestione dei servizi

La risorsa Service funge da elemento principale per organizzare i servizi. Gli aspetti di un determinato servizio, ad esempio i relativi SLO, sono organizzati in base al 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
- Workload GKE: GKE_WORKLOAD
Servizi personalizzati: CUSTOM

Per saperne di più, 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 sezione Gestione degli SLO illustra i comandi per manipolare gli SLO.

ID servizio

Ogni servizio ha un identificatore completo chiamato nome della risorsa. Questo identificatore è memorizzato 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",

Nel nome della risorsa è incorporato 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 della risorsa projects/PROJECT_NUMBER/services/my-test-service, l'ID servizio è my-test-service.

Per brevità e accuratezza, molti esempi di curl presuppongono che l'ID servizio sia contenuto nella variabile di ambiente SERVICE_ID, in modo da poterlo fare riferimento ripetutamente.

Schede dei servizi

Per recuperare informazioni su tutti i servizi nel tuo progetto, richiama il services.list metodo. Per recuperare informazioni su un servizio specifico in base all'ID servizio, utilizza il services.get metodo:

Ad esempio, per elencare le informazioni sui servizi utilizzando curl, richiama il services.list o services.get metodo inviando una GET richiesta a:

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services per elencare tutti i servizi
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID per ottenere un servizio specifico

Ad esempio, la seguente richiesta recupera informazioni sul servizio identificato dal valore memorizzato 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}

Creazione di un servizio

Per creare un servizio, devi specificare una rappresentazione del tipo di servizio e inviarla al services.create metodo. 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 la procedura per chiamare l'API è la stessa. 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 che il servizio abbia. L'esempio seguente mostra la creazione di un servizio di workload GKE:

Ad esempio, 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 per contenere 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 services.delete metodo e specifica l'ID servizio.

Ad esempio, per eliminare un servizio utilizzando curl, invia una richiesta DELETE all' endpointhttps://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.

Elenco degli SLO

Per recuperare informazioni su tutti gli SLO associati a un servizio, richiama il services.serviceLevelObjectives.list metodo. Per recuperare informazioni su uno SLO specifico in base al nome, utilizza il services.serviceLevelObjectives.get metodo:

Per elencare le informazioni sui servizi utilizzando curl, richiama il services.serviceLevelObjectives.list o services.serviceLevelObjectives.get metodo inviando una GET richiesta a:

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives per elencare tutti gli SLO
https://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 memorizzato 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 si basa su uno SLI di disponibilità, imposta un obiettivo di rendimento target del 98% e misura la conformità in una settimana di calendario. Per saperne di più sugli SLI di disponibilità, consulta Indicatori del livello del servizio.

Per saperne di più sulla struttura degli SLO, consulta ServiceLevelObjective per ulteriori informazioni sulla struttura degli SLO.

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. Nel seguente esempio:

"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 SLO specifico, richiedi lo SLO per ID.

Ad esempio, per ottenere uno SLO specifico utilizzando curl, richiama il services.serviceLevelObjectives.get metodo inviando una GET richiesta 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 ServiceLevelObjective oggetto e passarlo al serviceLevelObjectives.create metodo.

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 Cloud Service Mesh per creare gli SLO; devi solo specificare gli obiettivi di rendimento e i periodi di conformità.
Per 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 una serie di esempi basati su varie fonti.

Puoi anche creare SLI utilizzando la Google Cloud console. Per saperne di più, consulta Creazione di uno SLO.

Struttura di uno SLO

La struttura di base per la creazione dello SLO è la 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à, che è uno dei due tipi:
- Un periodo mobile di una certa durata (in secondi)
- Un periodo di calendario

Per saperne di più su SLI, obiettivi di rendimento 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 di SLI è lo SLI di base.

Per altri servizi, devi creare uno SLI basato su richieste o uno SLI basato su finestre. Consulta Creazione di un indicatore del livello del servizio per alcune tecniche.

Esempio

Dopo aver creato 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% in 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 la disponibilità del 75% in un periodo mobile di 3 giorni:

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

Ad esempio, per creare uno SLO utilizzando curl, invia un messaggio POST all' https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives endpoint:

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 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 services.serviceLevelObjectives.delete metodo e specifica l'ID dello SLO nel tuo progetto:

Ad esempio, per eliminare uno SLO utilizzando curl, invia una richiesta DELETE all' https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID endpoint:

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 SLO

I dati SLO vengono archiviati nelle serie temporali, quindi puoi utilizzare il timeSeries.list metodo 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 di metrica per il metodo timeSeries.list.

Le serie temporali SLO vengono invece recuperate specificando un altro tipo di filtro, un selettore di serie temporali, al timeSeries.list metodo nel parametro filter. Per informazioni sull'utilizzo di questi selettori, consulta Recupero dei dati SLO.

Utilizzi anche i selettori di serie temporali per configurare le policy di avviso in modo programmatico. Per saperne di più, consulta Avvisi sul burn rate per altre informazioni.

Utilizza l'API Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.