Construções na API

A API do Service Monitoring é usada para configurar os 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 do Monitoring:

Esta página apresenta as estruturas usadas para representar serviços e SLOs na API do Service Monitoring e as mapeia para os conceitos descritos em Conceitos no monitoramento de serviço.

Para obter 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
  • Um objeto de configuração de telemetria
  • Um indicador do tipo de serviço:
    • Um serviço do App Engine
    • Um serviço do Cloud Endpoints
    • Um Istio no serviço do Google Kubernetes Engine
    • Um serviço personalizado

O único tipo de serviço que você cria manualmente é um serviço personalizado. Os outros tipos são detectados automaticamente com base no seu ambiente.

Por exemplo, o exemplo a seguir mostra a representação JSON de um serviço do Istio:

    {
      "name": "projects/[PROJECT_NUMBER]/services/[PROJECT_ID]-zone-us-central1-c-csm-main-default-currencyservice",
      "displayName": "[PROJECT_ID]/us-central1-c/csm-main/default/currencyservice",
      "clusterIstio": {
        "location": "us-central1-c",
        "clusterName": "csm-main",
        "serviceNamespace": "default",
        "serviceName": "currencyservice"
      },
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/[PROJECT_ID]/zones/us-central1-c/clusters/csm-main/k8s/namespaces/default/services/currencyservice"
      }
    }
    

Este exemplo mostra a representação JSON de um serviço personalizado:

    {
      "name": "projects/[PROJECT_NUMBER]/services/-I6P_NufSzKiuvX1AYHE6Q",
      "displayName": "My Test Service",
      "custom": {},
      "telemetry": {}
    }
    

A telemetria está em desenvolvimento. O único valor significativo é o nome completo do recurso que define o serviço. O formato é descrito em Nomes de recursos.

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:

  • Uma SLI básica, que é criada automaticamente para um tipo de serviço conhecido. 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 é possível 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 cujos valores têm um tipo de métrica DELTA ou CUMULATIVE. O valor de serviço bom é a contagem de itens que se enquadram nos intervalos de histograma em um intervalo 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 [Monitoring filters][monfilters], 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][sli-perthreshold-apiref] 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.