Costrutti nell'API

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

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

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

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

Servizi

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

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

Per definire un servizio di base, devi specificare il tipo di servizio e fornire un insieme di etichette specifiche del servizio che lo descrivono:

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

Le sezioni seguenti forniscono esempi per ogni tipo di servizio.

Tipi di servizi di base

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

  • APP_ENGINE
  • CLOUD_ENDPOINTS
  • CLUSTER_ISTIO
  • ISTIO_CANONICAL_SERVICE
  • CLOUD_RUN

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

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"
          },
      },
    }

Cluster Istio 

    {
      "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 servizi GKE di base

Questa sezione contiene esempi di definizioni di servizi GKE basati sul tipo BasicService, in cui 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 di servizio BasicSli. Per saperne di più, consulta Indicatori del livello di 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"
          }
      },
    }

Workload 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

Se nessuno dei tipi di servizi di base è adatto, puoi creare servizi personalizzati. 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 di servizio BasicSli. Per saperne di più, consulta Indicatori del livello di servizio.

Indicatori del livello di servizio

Un indicatore del livello di servizio (SLI) fornisce una misura delle prestazioni di un servizio. Uno SLI si basa sulla metrica acquisita dal servizio. La definizione esatta dello SLI dipende dal tipo di metrica utilizzata come metrica indicatore, ma in genere si tratta di un confronto tra i risultati accettabili e i risultati totali.

Uno SLI è rappresentato dall' ServiceLevelIndicator oggetto. 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 del 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'utilizzo di questo tipo di SLI è descritto in SLO basati su richiesta; è rappresentato da un oggetto RequestBasedSli.

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

Ad esempio, di seguito è riportato uno SLI di disponibilità di base: 

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

Strutture per gli SLI basati su richiesta

Uno SLI basato su richiesta si basa su una metrica che conteggia le unità di servizio come rapporto tra un risultato specifico 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 risultato positivo e il numero totale di richieste.

Esistono due modi per creare uno SLI basato su richiesta:

  • Come TimeSeriesRatio, quando il rapporto tra il servizio idoneo e il 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 del servizio idoneo è il conteggio degli elementi che rientrano nei bucket dell'istogramma in un intervallo specificato, mentre il totale è il conteggio di tutti i valori nella distribuzione.

Di seguito è riportata la rappresentazione JSON di uno SLI che utilizza un rapporto tra 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 di 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 tipo di metrica e risorsa. Il valore di goodServiceFilter è rappresentato dalla stessa coppia, ma in cui un'etichetta ha un valore specifico; 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 sul 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 considerato idoneo è 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 gli SLI basati su finestre

Uno SLI basato su finestre conteggia le finestre temporali in cui il servizio fornito è considerato idoneo. Il criterio per determinare l'idoneità del servizio fa parte della definizione dello SLI.

Tutti gli SLI basati su finestre includono un periodo di finestra compreso tra 60 e 86.400 secondi (1 giorno).

Esistono due modi per specificare il criterio di servizio idoneo per uno SLI basato su finestre:

  • Crea una stringa di filtro, descritta in Filtri di monitoraggio, che restituisce una serie temporale con valori booleani. Una finestra è idonea se il valore per quella finestra è true. Questo filtro è denominato goodBadMetricFilter.

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

    Un oggetto PerformanceThreshold specifica un valore di soglia e uno SLI di prestazioni. Se il valore dello SLI di prestazioni soddisfa o supera il valore di soglia, la finestra temporale viene considerata idonea.

    Esistono due modi per specificare lo SLI di prestazioni:

    • Come oggetto BasicSli nel campo basicPerformanceSli.
    • Come oggetto RequestBasedSli nel campo performance. Se utilizzi uno SLI basato su richiesta, il tipo di metrica dello SLI deve essere DELTA o CUMULATIVE. Non puoi utilizzare le metriche GAUGE negli SLI basati su richiesta.

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 idonee 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 finestre. Per saperne di più sulle strutture incorporate, consulta Strutture per gli SLI basati su richiesta.

Obiettivi del livello di servizio

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

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 rendimento al 98% di disponibilità per un periodo di una settimana.