Utilizzo dell'API

Questo documento descrive come gestire i servizi e gli obiettivi del livello di servizio (SLO) mediante 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 del Per l'API SLO, consulta la sezione Costrutti nell'API. Completi il materiale di riferimento è disponibile nell'API Cloud Monitoring v3.

Puoi utilizzare l'API SLO per:

  • Creare e gestire i servizi.

  • Creare obiettivi del livello di servizio (SLO) in base a valori personalizzati o predefiniti per ciascuno dei tuoi servizi.

Identificatori validi

Diversi metodi nell'API SLO usano identificatori per elementi diversi, in particolare per gli identificatori di progetti e servizi. Questi ID rispettano le 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 il l'API SLO mediante lo strumento curl. Se utilizzi questa API tramite un client puoi saltare questa sezione.

Gli esempi in questa pagina accedono all'API SLO utilizzando il comando curl per inviare richieste HTTP agli endpoint REST. Utilizza quanto segue informazioni sull'autenticazione e sul richiamo di curl per impostare le variabili utilizzato nelle chiamate.

Autenticazione

  1. Crea una variabile di ambiente in cui inserire l'ID del tuo progetto di definizione dell'ambito di un ambito delle metriche. Questi esempi utilizzano PROJECT_ID:

    PROJECT_ID=my-test-service

  2. Esegui l'autenticazione in Google Cloud CLI:

    gcloud auth login

  3. Per evitare di dover specificare l'ID progetto con ogni comando, impostalo predefinita mediante gcloud CLI:

    gcloud config set project ${PROJECT_ID}

  4. 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 segnala improvvisamente che non sei autenticato, emetti di nuovo questo comando.

  5. 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 insieme di argomenti, seguito dall'URL di una risorsa API SLO. Gli argomenti più comuni includono specificati dalle variabili di ambiente PROJECT_ID e ACCESS_TOKEN. Potresti anche dover specificare altri argomenti, ad esempio per specificare il tipo della richiesta HTTP (ad esempio, -X DELETE). La richiesta predefinita è GET, quindi gli esempi non lo 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 il seguente codice: GET richiesta:

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 seguente, un servizio per i carichi di lavoro 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 conoscere la configurazione utilizzata per creare questo servizio, consulta Creazione di un Google Cloud. 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 i tuoi servizi. Aspetti di un particolare servizio, come ad esempio gli SLO, sono e organizzarli sotto il nome del servizio. I seguenti tipi di servizi sono supportati:

  • 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
  • Servizi personalizzati: CUSTOM

Per ulteriori informazioni, vedi 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 viene archiviato nel campo name della descrizione del servizio, per 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, 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, così potrai farvi riferimento ripetutamente.

Elenco dei servizi

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

Protocollo

Per elencare le informazioni sui servizi utilizzando curl, richiama il services.list oppure services.get inviando una richiesta GET 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 usufruire di un servizio specifico

Ad esempio, la seguente richiesta recupera informazioni il 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}

crea un servizio

Per creare un servizio, devi specificare una rappresentazione del tipo di servizio. e invialo al metodo services.create. Puoi utilizzare le strutture di tipo 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 carico di lavoro {[gke_name_short}} servizio:

Protocollo

Per creare il servizio utilizzando curl, invia un messaggio POST al Endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

  1. 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.

  2. 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
)

  3. 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 di strutture associate ad altri servizi, vedi 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 utilizzando curl, invia una richiesta DELETE al 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 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 Metodo services.serviceLevelObjectives.get:

Protocollo

Per elencare le informazioni sui servizi utilizzando curl, richiama il services.serviceLevelObjectives.list oppure services.serviceLevelObjectives.get inviando un Richiesta di GET a:

  • Da https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives a elenca tutti gli SLO
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID per ottenere uno SLO specifico

Ad esempio, nella richiesta seguente sono elencati tutti gli SLO associati 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 dalla 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 target dell'obiettivo di prestazioni del 98% e misura la conformità su un calendario settimana. Per ulteriori informazioni sugli SLI di disponibilità, consulta Indicatori del livello di servizio.

Consulta ServiceLevelObjective per ulteriori informazioni su la struttura degli SLO.

Recupero di uno SLO specifico

Ogni SLO ha un identificatore univoco all'interno del servizio, composto 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 utilizzando curl, richiama il metodo services.serviceLevelObjectives.get inviando un 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 e passalo all'oggetto serviceLevelObjectives.create.

La struttura di uno SLO ha molte strutture incorporate, tra cui uno 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 SLO; devi solo specificare gli obiettivi di rendimento periodi di conformità.

  • Per gli altri servizi, devi definire gli SLO utilizzando l'API SLO. Per specificare uno SLO, devi creare un valore per serviceLevelIndicator . Consulta la sezione Creazione di un indicatore del livello del servizio per alcune tecniche e Creazione di SLI dalle metriche per un insieme di esempio basati su varie fonti.

Puoi creare SLI anche utilizzando la console Google Cloud. Per ulteriori informazioni, consulta la sezione 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 conformità consulta Concetti di 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 basato su Windows. Consulta la sezione Creazione di un indicatore del livello del servizio per alcune tecniche.

Esempio

Una volta ottenuto lo SLI, puoi creare lo SLO. Nell'esempio che segue definisce uno SLO per un servizio che utilizza uno SLI di base. Potresti avere più SLO su un singolo SLI, ad esempio uno per la disponibilità del 95% e una per una disponibilità del 99%. L'esempio seguente è uno SLO per 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 utilizzando curl, invia un messaggio POST al https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives endpoint:

  1. Crea una variabile per l'ID servizio:

    SERVICE_ID=custom:my-test-service

  2. Crea una variabile che contenga il corpo della richiesta, un'istanza del ServiceLevelObjective oggetto. 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
)

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

Protocollo

Per eliminare uno SLO utilizzando curl, invia una richiesta DELETE al 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 dello SLO

I dati degli SLO vengono archiviati in serie temporali, quindi puoi utilizzare timeSeries.list per recuperarlo. Tuttavia, questi dati non vengono archiviati nei tipi di metriche standard, non puoi utilizzare il meccanismo standard di specificare un tipo di metrica applica un filtro al metodo timeSeries.list.

Le serie temporali dello SLO vengono recuperate specificando un altro tipo di un selettore di serie temporali, al metodo timeSeries.list in il parametro filter. Consulta Recupero dei dati dello SLO per informazioni sull'uso di questi selettori.

Puoi utilizzare anche i selettori delle serie temporali per configurare i criteri di avviso in modo programmatico. Consulta Avvisi sul tasso di combustione per ulteriori informazioni informazioni.