Construções na API

Neste documento, apresentamos as estruturas usadas para representar serviços e SLOs na API SLO e as mapeamos para os conceitos descritos em Conceitos no monitoramento de serviço.

A API SLO é usada para configurar objetivos de nível de serviço (SLOs) que podem ser usados para monitorar a integridade de seus serviços.

O Service Monitoring inclui os recursos a seguir na API Monitoring:

Para mais informações sobre como invocar a API, consulte Como trabalhar com a API.

Serviços

Um serviço é representado por um objeto Service. Este objeto inclui os seguintes campos:

  • Um nome: um nome de recurso totalmente qualificado para este serviço
  • Um nome de exibição: um rótulo para uso em componentes do console
  • Uma estrutura para um dos tipos de BasicService.
  • Um objeto de configuração de telemetria fornecido pelo sistema

Para definir um serviço básico, você especifica o tipo de serviço e apresenta um conjunto de rótulos específicos ao serviço que descrevem o serviço:

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

As seções a seguir mostram exemplos de cada tipo de serviço.

Tipos de serviço básicos

Nesta seção, apresentamos exemplos de definições de serviços criados no tipo BasicService, em que o valor do campo serviceType é um dos seguintes:

  • APP_ENGINE
  • CLOUD_ENDPOINTS
  • CLUSTER_ISTIO
  • ISTIO_CANONICAL_SERVICE
  • CLOUD_RUN

Cada um desses tipos de serviço usa o indicador de nível de serviço 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 do cluster 

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

Serviço canônico do 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"
          },
      },
    }

Tipos básicos de serviço do GKE

Nesta seção, você verá exemplos de definições de serviços do GKE criadas no tipo BasicService, em que o valor do campo serviceType é um dos seguintes:

  • GKE_NAMESPACE
  • GKE_WORKLOAD
  • GKE_SERVICE

É necessário definir um SLIs para esses tipos de serviço. Eles não podem usar indicadores de nível de serviço BasicSli. Para mais informações, consulte Indicadores de nível de serviço.

Namespace do GKE 

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

Carga de trabalho do 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",
          }
      },
    }

Serviço do 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"
          }
      },
    }

Serviços personalizados

Será possível criar serviços personalizados se nenhum dos tipos básicos de serviço for adequado. Um serviço personalizado tem a seguinte aparência:

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

É necessário definir um SLIs para esses tipos de serviço. Eles não podem usar indicadores de nível de serviço BasicSli. Para mais informações, consulte Indicadores de nível de serviço.

Indicadores de nível de serviço

Um indicador de nível de serviço (SLI) fornece uma medida do desempenho de um serviço. Um SLI é baseado na métrica capturada pelo serviço. O modo como o SLI é definido depende do tipo de métrica usado como métrica do indicador, mas geralmente há uma comparação entre resultados aceitáveis e resultados totais.

Uma SLI é representada pelo objeto ServiceLevelIndicator. Este objeto é uma forma coletiva de indicar os três tipos de SLIs suportados:

  • Um SLI básico, criado automaticamente para instâncias do tipo de serviço BasicService. Este tipo de SLI é descrito em Objetivos de nível de serviço. Ele é representado por um objeto BasicSli e mede a disponibilidade ou a latência.

  • Uma SLI baseada em solicitação, que você pode usar para contar eventos que representam serviço aceitável. O uso desse tipo de SLI é descrito em SLOs baseados em solicitação; é representado por um objeto RequestBasedSli.

  • Uma SLI baseada em janela, que pode ser usada para contar períodos que atendem a algum critério de qualidade. O uso desse tipo de SLI é descrito em SLOs baseados em janelas; é representado por um objeto WindowsBasedSli.

Por exemplo, o exemplo a seguir mostra uma SLI com disponibilidade básica:

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

Estruturas para SLIs baseadas em solicitação

Uma SLI baseada em solicitação tem base em uma métrica que conta as unidades de serviço como a proporção entre um resultado específico e o total. Por exemplo, se você usar uma métrica que conta as solicitações, poderá criar a proporção entre o número de solicitações que retornam sucesso e o número total de solicitações.

Há duas maneiras de criar uma SLI com base em solicitação:

  • Como TimeSeriesRatio, quando a relação entre o serviço bom e o serviço total é calculada a partir de duas séries temporais cujos valores têm um tipo de métrica DELTA ou CUMULATIVE.
  • Como DistributionCut, quando a série temporal tem um tipo de valor DISTRIBUTION e valores com um tipo de métrica DELTA ou CUMULATIVE. O valor de serviço bom é a contagem de itens que se enquadram nos buckets de histograma em um bucket especificado, e o total é a contagem de todos os valores na distribuição.

Veja a seguir a representação JSON de uma SLI que usa uma proporção de série temporal:

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

As séries temporais nessa proporção são identificadas pelo par de tipo de recurso monitorado e por tipo de métrica:

  • Recurso: https_lb_rule
  • Tipo de métrica: loadbalancing.googleapis.com/https/request_count

O valor de totalServiceFilter é representado pelo par de métrica e tipo de recurso. O valor de goodServiceFilter é representado pelo mesmo par, mas em que algum rótulo tem um valor específico. Nesse caso, quando o valor do rótulo response_code_class é 200.

A proporção entre os filtros mede o número de solicitações que retornam um status HTTP 2xx em relação ao número total de solicitações.

Veja a seguir a representação JSON de uma SLI que usa um corte de distribuição: 

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

A série temporal é identificada pelo tipo de recurso monitorado, pelo tipo de métrica e pelo valor de um rótulo de métrica:

  • Recurso: https_lb_rule
  • Tipo de métrica: loadbalancing.googleapis.com/https/backend_latencies
  • Par de rótulo e valor: response_code_class = 200

O intervalo de latências consideradas boas é designado pelo campo range. Essa SLI calcula a proporção de latências de respostas de classe 2xx abaixo de 500 para as latências de todas as respostas de classe 200.

Estruturas para SLIs baseadas em janelas

Uma SLI baseada em janelas conta janelas de tempo em que o serviço fornecido é considerado bom. O critério para determinar como um bom serviço faz parte da definição de SLI.

Todos os SLIs baseados em janelas incluem um período de janela, de 60 a 86.400 segundos (um dia).

Há duas maneiras de especificar o critério de serviço bom para uma SLI baseada em janelas:

  • Crie uma string de filtro, descrita em Filtros do Monitoring, que retorna uma série temporal com valores booleanos. Uma janela é válida se o valor dessa janela for true. Esse filtro é chamado de goodBadMetricFilter.

  • Crie um objeto PerformanceThreshold que represente um limite de desempenho aceitável. Este objeto é especificado como o valor de goodTotalRatioThreshold.

    Um objeto PerformanceThreshold especifica um valor limite e uma SLI de desempenho. Se o valor da SLI de desempenho atingir ou exceder o valor limite, a janela de tempo será considerada válida.

    Há duas maneiras de especificar a SLI de desempenho:

Veja a seguir a representação JSON de uma SLI baseada em janelas criada em um limite de desempenho para uma SLI básica de disponibilidade:

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

Essa SLI especifica um bom desempenho como uma janela de cinco minutos em que a disponibilidade atinge 90% ou mais. A estrutura de uma SLI básica é mostrada em indicadores de nível de serviço.

Você também pode incorporar uma SLI baseada em solicitação na SLI baseada em janelas. Para obter mais informações sobre as estruturas incorporadas, consulte Estruturas para SLIs baseadas em solicitação.

Objetivos de nível de serviço

Um objetivo de nível de serviço (SLO) é representado por um objeto ServiceLevelObjective. Este objeto inclui os seguintes campos:

  • Um nome
  • Um nome de exibição
  • A SLI desejada, um objeto ServiceLevelIndicator incorporado.
  • A meta de desempenho para a SLI
  • O período de conformidade para a SLI

A tabela a seguir mostra a representação JSON de um SLO que usa uma SLI de disponibilidade básica como o valor do 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"
}

Esse SLO define a meta de desempenho com 98% de disponibilidade em um período de uma semana.