Como trabalhar com a API

Este documento descreve como gerenciar serviços e objetivos de nível de serviço (SLOs) usando a API Cloud Monitoring.

O Serviço de monitoramento inclui os recursos a seguir na API Monitoring:

Este documento se refere a essas adições coletivamente como a API SLO e ilustra os principais usos. Para uma visão geral das estruturas na API SLO, consulte Construções na API. Materiais de referência abrangentes são exibidos na API do Cloud Monitoring v3.

Você pode usar a API SLO para fazer o seguinte:

  • Criar e gerenciar serviços.

  • Criar objetivos de nível de serviço (SLOs) com base em indicadores de nível de serviço (SLIs) personalizados ou predefinidos para qualquer um dos seus serviços.

Identificadores válidos

Vários métodos na API SLO usam identificadores para elementos diferentes, especialmente identificadores para projeto e serviços. Esses códigos atendem aos requisitos a seguir:

  • Comprimento: 1 a 63 caracteres
  • Caracteres: apenas letras minúsculas, números e hifens
  • Caractere inicial: letra minúscula
  • Caractere final: letra minúscula ou número, não pode ser um hífen

A expressão regular para essas regras é a seguinte: [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

Exemplos usando o curl

Esta seção descreve as convenções e configurações usadas para invocar a API SLO usando a ferramenta curl. Se você usa a API por meio de uma biblioteca de cliente, ignore esta seção.

Com os exemplos desta página, você acessa a API SLO usando a ferramenta curl para enviar solicitações HTTP a endpoints REST. Use as seguintes informações sobre autenticação e sobre como invocar curl para definir as variáveis usadas nas invocações.

Authentication

  1. Crie uma variável de ambiente para manter o ID do projeto de escopo de um escopo de métricas. Estes exemplos usam PROJECT_ID:

    PROJECT_ID=my-test-service

  2. Faça a autenticação na Google Cloud CLI:

    gcloud auth login

  3. Para que você não precise especificar o ID do projeto com cada comando, defina-o como padrão usando a CLI gcloud:

    gcloud config set project ${PROJECT_ID}

  4. Crie um token de autorização e colete-o em uma variável de ambiente. Nestes exemplos, a variável ACCESS_TOKEN é chamada:

    ACCESS_TOKEN=`gcloud auth print-access-token`

    É necessário atualizar o token de acesso periodicamente. Se algum comando parar de funcionar com um erro de falta de autenticação, será necessário emiti-lo novamente.

  5. Para verificar se você recebeu um token de acesso, faça o echo da variável ACCESS_TOKEN:

    echo ${ACCESS_TOKEN}
ya29.GluiBj8o....

Como invocar o curl

Cada invocação curl inclui um conjunto de argumentos, seguido pelo URL de um recurso da API SLO. Os argumentos comuns incluem valores especificados pelas variáveis de ambiente PROJECT_ID e ACCESS_TOKEN. Talvez você também precise especificar outros argumentos para elementos diferentes, como o tipo da solicitação HTTP. Por exemplo, -X DELETE. Como a solicitação padrão é GET, os exemplos não fazem essa especificação.

Cada invocação do curl tem esta estrutura geral:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Por exemplo, para listar todos os serviços no projeto, faça a solicitação GET a seguir:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services

Essa solicitação retorna uma matriz de descrições de serviço, com entradas do tipo a seguir, incluindo um serviço de carga de trabalho do GKE com o ID "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"
      }
    },
   ...
  ]
}

Para ver a configuração usada para criar esse serviço, consulte Como criar um serviço. A estrutura gkeWorkload desta lista é derivada da estrutura basicService usada para criar o serviço. Consulte Service para mais informações sobre a estrutura de um serviço.

Como gerenciar serviços

O recurso Service funciona como o elemento raiz da organização dos seus serviços. Os aspectos de um serviço específico, como os SLOs, são organizados de acordo com o nome do serviço. Os seguintes tipos de serviço são compatíveis:

  • Serviço do App Engine: APP_ENGINE
  • Serviço do Cloud Endpoints: CLOUD_ENDPOINTS
  • Serviço canônico do Istio: ISTIO_CANONICAL_SERVICE
  • Serviço Istio do cluster: CLUSTER_ISTIO
  • Serviço do Cloud Run: CLOUD_RUN
  • Um conjunto de serviços baseados no Google Kubernetes Engine:
    • Serviço do GKE: GKE_SERVICE
    • Namespace do GKE: GKE_NAMESPACE
    • Carga de trabalho do GKE: GKE_WORKLOAD
  • Serviços personalizados: CUSTOM

Para mais informações, consulte Tipos de serviço básicos ou Tipos básicos de serviço do GKE.

Você pode adicionar SLOs a qualquer serviço em seu projeto usando a API. Como gerenciar SLOs apresenta os comandos para manipular SLOs..

IDs de serviço

Cada serviço tem um identificador totalmente qualificado chamado de nome do recurso. Ele é armazenado no campo name da descrição do serviço. Por exemplo:

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",

Um ID abreviado do serviço fica incorporado ao nome de recurso após a substring projects/PROJECT_NUMBER/services/.

Se você criou o próprio serviço com o nome de recurso projects/PROJECT_NUMBER/services/my-test-service, o ID do serviço será my-test-service.

Em muitos exemplos do curl, o ID de serviço é armazenado na variável de ambiente SERVICE_ID, garantindo precisão e simplicidade. Assim, é possível sempre consultar esse ID.

Como listar serviços

Para recuperar informações sobre todos os serviços no projeto, chame o método services.list. Para recuperar informações sobre um serviço específico pelo ID, use o método services.get:

Protocolo

Para listar informações sobre os serviços usando o curl, invoque o método services.list ou services.get. Basta enviar uma solicitação GET a:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services para listar todos os serviços;
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID para receber um serviço específico.

Por exemplo, com a solicitação a seguir, você recupera informações sobre o serviço identificado pelo valor armazenado na variável de ambiente SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

Como criar um serviço

Para criar um serviço, especifique uma representação do tipo de serviço e a envie ao método services.create. Veja as estruturas de tipo de serviço descritas em Tipos de serviço básicos e Tipos básicos de serviço do GKE.

As estruturas variam, mas o processo para chamar a API é o mesmo. Especifique um nome de exibição para o serviço e um campo basicService contendo a representação do serviço.

Como opção, especifique o ID que você quer atribuir ao serviço. O exemplo a seguir mostra a criação de um serviço de carga de trabalho {[gke_name_short}}:

Protocolo

Para criar o serviço usando o curl, envie uma mensagem POST ao endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

  1. Se você quiser fornecer um ID de serviço, crie uma variável para ele:

    SERVICE_ID=my-test-service

    Esse valor é fornecido no parâmetro de consulta de URL service_id.

  2. Crie uma variável para armazenar o corpo da solicitação que descreve o serviço:

    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. Publique o corpo da solicitação no endpoint e especifique o ID do serviço como o valor do service_idparâmetro de consulta:

    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}

Para ver exemplos das estruturas associadas a outros serviços, consulte Tipos de serviço básicos ou Tipos básicos de serviço do GKE.

Excluindo um serviço

Para excluir um serviço criado, invoque o método services.delete e especifique o ID do serviço.

Protocolo

Para excluir um serviço usando o curl, envie DELETEuma solicitação ao https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_IDendpoint:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

Como gerenciar SLOs

Você pode criar, excluir e recuperar SLOs usando a API SLO. Você pode ter até 500 SLOs para cada serviço.

Para gerenciar SLOs de um serviço, você precisa ter o ID dele. Os SLOs são nomeados com base no serviço a que eles pertencem. Para informações sobre como identificar IDs de serviço, consulte IDs de serviço.

Como listar SLOs

Para recuperar informações sobre todos os SLOs associados a um serviço, invoque o método services.serviceLevelObjectives.list. Para recuperar informações sobre um SLO específico pelo nome, use o método services.serviceLevelObjectives.get:

Protocolo

Para listar informações sobre os serviços usando o curl, invoque os métodos services.serviceLevelObjectives.list ou services.serviceLevelObjectives.get. Basta enviar uma solicitação GET para:

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives para listar todos os SLOs
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID para receber um SLO específico

Por exemplo, com a solicitação a seguir, você lista todos os SLOs associados ao ID de serviço armazenado na variável de ambiente SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

Confira a seguir um SLO de disponibilidade recuperado do serviço "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",
},

Esse SLO é baseado em um SLI de disponibilidade, define uma meta de desempenho de 98% e avalia a conformidade durante uma semana. Para mais informações sobre os SLIs de disponibilidade, consulte Indicadores de nível de serviço.

Consulte ServiceLevelObjective para mais informações sobre a estrutura dos SLOs.

Como recuperar um SLO específico

Cada SLO tem um identificador exclusivo no serviço que é a string após serviceLevelObjectives no campo name do SLO. No exemplo a seguir:

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",

o ID do SLO é a string 3kavNVTtTMuzL7KcXAxqCQ.

Para recuperar informações sobre esse SLO específico, faça uma solicitação pelo ID.

Protocolo

Para receber um SLO específico usando o curl, invoque o método services.serviceLevelObjectives.get. Basta enviar uma solicitação GET 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}

Como criar um SLO

Para criar um SLO usando a API SLO, crie um objeto ServiceLevelObjective e passe-o ao método serviceLevelObjectives.create.

A estrutura de um SLO tem muitas estruturas incorporadas, incluindo uma para o valor do campo serviceLevelIndicator.

  • Para os serviços do Cloud Service Mesh, Istio no Google Kubernetes Engine e App Engine, os SLIs são predefinidos. Use o console do Cloud Service Mesh para criar SLOs. Você só precisa especificar as metas de desempenho e os períodos de compliance.

  • Para os serviços personalizados, você precisa definir SLOs usando a API SLO. Para especificar um SLO, você também precisa criar um valor para o campo serviceLevelIndicator. Consulte Criar um indicador de nível de serviço para algumas técnicas e Como criar SLIs de métricas para um conjunto de exemplos com base em várias fontes.

Também é possível criar SLIs usando o console do Google Cloud. Para mais informações, consulte Como criar um SLO.

A estrutura de um SLO

A estrutura básica para criar o SLO é a seguinte:

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

Você deve especificar o seguinte:

  • Nome de exibição: uma descrição do SLO.
  • Um indicador de nível de serviço, que pode ser de um destes três tipos:
  • A meta de desempenho, que é uma porcentagem.
  • O período de conformidade, que pode ser de um destes dois tipos:
    • Um período contínuo em segundos.
    • Um intervalo de datas.

Para mais informações sobre SLIs, metas de desempenho e períodos de conformidade, consulte Conceitos em monitoramento de serviços.

Para o Cloud Service Mesh, o Istio no Google Kubernetes Engine e os serviços do App Engine, o tipo SLI é o SLI básico.

Para outros serviços, você precisa criar um SLI baseado em solicitações ou janelas. Consulte Como criar um indicador de nível de serviço para algumas técnicas.

Exemplo

Depois de criar o SLI, é possível gerar o SLO. Com o exemplo a seguir, você define um SLO de um serviço que usa um SLI básico. É possível ter vários SLOs em um único SLI. Por exemplo, um com disponibilidade de 95% e outro de 99%. O exemplo a seguir é um SLO com 95% de disponibilidade durante uma semana: 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.95,
  "calendarPeriod": "WEEK",
  "displayName": "95% Availability in Calendar Week"
}

Confira neste exemplo um SLO com 75% de disponibilidade durante um período de três dias: 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}

Protocolo

Para criar um SLO usando o curl, envie uma mensagem POST ao endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives:

  1. Crie uma variável para o ID de serviço:

    SERVICE_ID=custom:my-test-service

  2. Crie uma variável para armazenar o corpo da solicitação, uma instância do objeto ServiceLevelObjective. Este exemplo usa um dos SLOs descritos anteriormente:

    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. Publique o corpo da solicitação no 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

    Se preferir, especifique um ID pretendido para o SLO como o valor do parâmetro de consulta 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}

Como excluir um SLO

Para excluir um SLO, invoque o método services.serviceLevelObjectives.delete e especifique o ID do SLO no projeto:

Protocolo

Para excluir um SLO usando o curl, envie uma solicitação DELETE ao endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

Como acessar a série temporal do SLO

Os dados do SLO são armazenados em séries temporais. Assim, é possível usar o método timeSeries.list para recuperá-los. No entanto, o armazenamento desses dados não é feito em tipos de métrica padrão. Por isso, não é possível usar o processo padrão de especificar um filtro de tipo de métrica para o método timeSeries.list.

Na verdade, as séries temporais do SLO são recuperadas ao especificar outro tipo de filtro, um seletor de série temporal, para o método timeSeries.list no parâmetro filter. Consulte Como recuperar dados do SLO para mais informações sobre como usar esses seletores.

Também é possível usar seletores de série temporal para configurar políticas de alertas com programação. Consulte Como receber alertas sobre a taxa de gravação para mais informações.