Costrutti nell'API

Questo documento introduce le strutture utilizzate per rappresentare servizi e SLO nell'API SLO e le mappa ai concetti descritti generalmente in Concetti nel monitoraggio dei servizi.

L'API SLO viene utilizzata per configurare obiettivi del livello di servizio (SLO) che possono essere utilizzati per monitorare l'integrità dei servizi.

Service Monitoring aggiunge le seguenti risorse all'API Monitoring:

Per informazioni su come richiamare l'API, vedi Utilizzo dell'API.

Servizi

Un servizio è rappresentato da un oggetto Service. Questo oggetto include i seguenti campi:

  • Un nome: un nome completo della risorsa per questo servizio
  • Un nome visualizzato: un'etichetta da utilizzare nei componenti della console
  • Una struttura per uno dei tipi di BasicService.
  • Un oggetto di configurazione della telemetria fornito dal sistema

Per definire un servizio di base, specifica il tipo di servizio e fornisci un insieme di etichette specifiche per il servizio che lo descrivono:

{
   "serviceType": string,
   "serviceLabels": {
      string: string,
      ...
   }
}

Le seguenti sezioni forniscono esempi per ciascun tipo di servizio.

Tipi di servizi di base

Questa sezione fornisce esempi di definizioni di servizi basate sul tipo BasicService, dove il valore del campo serviceType è uno dei seguenti:

  • APP_ENGINE
  • CLOUD_ENDPOINTS
  • CLUSTER_ISTIO
  • ISTIO_CANONICAL_SERVICE
  • CLOUD_RUN

Ognuno di questi tipi di servizio utilizza l'indicatore del livello del servizio BasicSli.

App Engine 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "APP_ENGINE",
          "serviceLabels": {
            "module_id": "MODULE_ID"
          },
      },
    }

Cloud Endpoints 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_ENDPOINTS",
          "serviceLabels": {
            "service": "SERVICE"
          },
      },
    }

Istio per il cluster 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLUSTER_ISTIO",
          "serviceLabels": {
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "service_namespace": "SERVICE_NAMESPACE",
            "service_name": "SERVICE_NAME"
          },
      },
    }

Servizio canonico Istio 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "ISTIO_CANONICAL_SERVICE",
          "serviceLabels": {
            "mesh_uid": "MESH_UID",
            "canonical_service_namespace": "CANONICAL_SERVICE_NAMESPACE",
            "canonical_service": "CANONICAL_SERVICE"
          },
      },
    }

Cloud Run 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_RUN",
          "serviceLabels": {
            "service_name": "SERVICE_NAME",
            "location": "LOCATION"
          },
      },
    }

Tipi di servizio GKE di base

Questa sezione contiene esempi di definizioni dei servizi GKE basate sul tipo BasicService, dove il valore del campo serviceType è uno dei seguenti:

  • GKE_NAMESPACE
  • GKE_WORKLOAD
  • GKE_SERVICE

Devi definire gli SLI per questi tipi di servizi. Non possono utilizzare gli indicatori del livello del servizio di BasicSli. Per ulteriori informazioni, consulta la sezione Indicatori del livello del servizio.

Spazio dei nomi GKE 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_NAMESPACE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME"
          }
      },
    }

Carico di lavoro GKE 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_WORKLOAD",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "top_level_controller_type": "TOPLEVEL_CONTROLLER_TYPE",
            "top_level_controller_name": "TOPLEVEL_CONTROLLER_NAME",
          }
      },
    }

Servizio GKE 

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_SERVICE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "service_name": "SERVICE_NAME"
          }
      },
    }

Servizi personalizzati

Puoi creare servizi personalizzati se nessuno dei tipi di servizi di base è adatto. Un servizio personalizzato ha il seguente aspetto:

    {
      "displayName": "DISPLAY_NAME",
      "custom": {}
    }

Devi definire gli SLI per questi tipi di servizi. Non possono utilizzare gli indicatori del livello del servizio di BasicSli. Per ulteriori informazioni, consulta la sezione Indicatori del livello del servizio.

Indicatori del livello del servizio

Un indicatore del livello del servizio (SLI) fornisce una misura delle prestazioni di un servizio. Uno SLI si basa sulla metrica acquisita dal servizio. Il modo esatto in cui viene definito lo SLI dipende dal tipo di metrica utilizzata come metrica dell'indicatore, ma in genere si tratta di un confronto tra i risultati accettabili e i risultati totali.

Uno SLI è rappresentato dall'oggetto ServiceLevelIndicator. Questo oggetto è un modo collettivo per fare riferimento ai tre tipi di SLI supportati:

  • Uno SLI di base, creato automaticamente per le istanze del tipo di servizio BasicService. Questo tipo di SLI è descritto in Obiettivi a livello di servizio; è rappresentato da un oggetto BasicSli e misura la disponibilità o la latenza.

  • Uno SLI basato su richiesta, che puoi utilizzare per conteggiare gli eventi che rappresentano un servizio accettabile. L'uso di questo tipo di SLI è descritto in SLO basati su richiesta; è rappresentato da un oggetto RequestBasedSli.

  • Uno SLI basato su finestre, che puoi usare per conteggiare i periodi di tempo che soddisfano un criterio di idoneità. L'uso di questo tipo di SLI è descritto negli SLO basati su Windows; è rappresentato da un oggetto WindowsBasedSli.

Ad esempio, quanto segue mostra uno SLI con disponibilità di base: 

{
  "basicSli": {
    "availability": {},
    "location": [
      "us-central1-c"
    ]
  }
}

Strutture per SLI basati su richiesta

Uno SLI basato su richiesta si basa su una metrica che conteggia le unità di servizio come rapporto tra un determinato risultato e il totale. Ad esempio, se utilizzi una metrica che conteggia le richieste, puoi creare il rapporto tra il numero di richieste che restituiscono un esito positivo e il numero totale di richieste.

Esistono due modi per creare uno SLI basato su richiesta:

  • Come TimeSeriesRatio, quando il rapporto tra servizio buono e servizio totale viene calcolato da due serie temporali i cui valori hanno un tipo di metrica DELTA o CUMULATIVE.
  • Come DistributionCut, quando la serie temporale ha il tipo di valore DISTRIBUTION e i cui valori hanno un tipo di metrica DELTA o CUMULATIVE. Il valore di servizio buono è il conteggio degli elementi che rientrano nei bucket degli istogrammi in un intervallo specificato e il totale è il conteggio di tutti i valori nella distribuzione.

Di seguito è riportata la rappresentazione JSON di uno SLI che utilizza un rapporto delle serie temporali: 

{
  "requestBased": {
    "goodTotalRatio": {
      "totalServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count"",
      "goodServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count" metric.label.response_code_class=200",
    }
  }
}

Le serie temporali in questo rapporto sono identificate dalla coppia di tipo risorsa monitorata e tipo di metrica:

  • Risorsa: https_lb_rule
  • Tipo di metrica: loadbalancing.googleapis.com/https/request_count

Il valore di totalServiceFilter è rappresentato dalla coppia di metrica e tipo di risorsa. Il valore di goodServiceFilter è rappresentato dalla stessa coppia, ma dove un'etichetta ha un valore particolare; in questo caso, quando il valore dell'etichetta response_code_class è 200.

Il rapporto tra i filtri misura il numero di richieste che restituiscono uno stato HTTP 2xx rispetto al numero totale di richieste.

Di seguito è riportata la rappresentazione JSON di uno SLI che utilizza un taglio di distribuzione: 

{
  "requestBased": {
    "distribution_cut": {
      "distribution_filter": "resource.type=https_lb_rule  metric.type="loadbalancing.googleapis.com/https/backend_latencies" metric.label.response_code_class=200",
      "range": {
        "min": "-Infinity",
        "max": 500.0
      }
    }
  }
}

La serie temporale è identificata dal tipo di risorsa monitorata, dal tipo di metrica e dal valore di un'etichetta della metrica:

  • Risorsa: https_lb_rule
  • Tipo di metrica: loadbalancing.googleapis.com/https/backend_latencies
  • Coppia etichetta-valore: response_code_class = 200

L'intervallo di latenze considerate buone è indicato dal campo range. Questo SLI calcola il rapporto tra le latenze delle risposte di classe 2xx inferiori a 500 e le latenze di tutte le risposte di classe 200.

Strutture per SLI basati su finestre

Uno SLI basato su finestre conteggia le finestre temporali in cui il servizio fornito viene considerato buono. Il criterio per determinare se un buon servizio è parte della definizione SLI.

Tutti gli SLI basati su Windows includono un periodo di finestra, 60-86.400 secondi (1 giorno).

Esistono due modi per specificare il criterio di buon servizio per uno SLI basato su Windows:

  • Crea una stringa di filtro, descritta nella sezione Filtri di monitoraggio, che restituisca una serie temporale con valori booleani. Una finestra è buona se il relativo valore è true. Questo filtro è chiamato goodBadMetricFilter.

  • Crea un oggetto PerformanceThreshold che rappresenta una soglia di prestazioni accettabili. Questo oggetto è specificato come valore di goodTotalRatioThreshold.

    Un oggetto PerformanceThreshold specifica un valore di soglia e uno SLI delle prestazioni. Se il valore dello SLI delle prestazioni soddisfa o supera il valore della soglia, la finestra temporale viene conteggiata come buona.

    Esistono due modi per specificare lo SLI delle prestazioni:

Di seguito è riportata la rappresentazione JSON di uno SLI basato su finestre basato su una soglia di prestazioni per uno SLI di disponibilità di base:

{
  "windowsBased": {
     "goodTotalRatioThreshold": {
       "threshold": 0.9,
       "basicSliPerformance": {
         "availability": {},
         "location": [
           "us-central1-c"
         ]
       }
     },
     "windowPeriod": "300s"
   }
}

Questo SLI specifica prestazioni buone come una finestra di 5 minuti in cui la disponibilità raggiunge il 90% o più. La struttura di uno SLI di base è mostrata in Indicatori del livello di servizio.

Puoi anche incorporare uno SLI basato su richiesta nello SLI basato su Windows. Per ulteriori informazioni sulle strutture incorporate, consulta Strutture per SLI basati su richiesta.

Obiettivi del livello di servizio

Un obiettivo del livello di servizio (SLO) è rappresentato da un oggetto ServiceLevelObjective. Questo oggetto include i seguenti campi:

  • Nome
  • Un nome visualizzato
  • Lo SLI di destinazione; un oggetto ServiceLevelIndicator incorporato
  • L'obiettivo di prestazioni per lo SLI
  • Il periodo di conformità per lo SLI

Di seguito è riportata la rappresentazione JSON di uno SLO che utilizza uno SLI di disponibilità di base come valore del campo serviceLevelIndicator: 

{
   "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
   "serviceLevelIndicator": {
     "basicSli": {
       "availability": {},
       "location": [
         "us-central1-c"
       ]
     }
   },
   "goal": 0.98,
   "calendarPeriod": "WEEK",
   "displayName": "98% Availability in Calendar Week"
}

Questo SLO imposta l'obiettivo di prestazioni al 98% di disponibilità in un periodo di una settimana.