Trabalhar com a API

Este documento descreve como gerir serviços e objetivos de nível de serviço (SLOs) através da API Cloud Monitoring.

O Service Monitoring adiciona os seguintes recursos à API Monitoring:

Este documento refere-se a estas adições coletivamente como a API SLO e ilustra as utilizações principais. Para uma vista geral das estruturas na API SLO, consulte Construções na API. O material de referência abrangente é apresentado em API Cloud Monitoring v3.

Pode usar a API SLO para fazer o seguinte:

  • Crie e faça a gestão de serviços.

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

Identificadores válidos

Vários métodos na API SLO usam identificadores para diferentes elementos, especialmente identificadores para projetos e serviços. Estes IDs cumprem as seguintes regras:

  • Comprimento: 1 a 63 carateres
  • Carateres: apenas letras minúsculas, números e hífenes
  • Caráter inicial: letra minúscula
  • Caráter terminal: letra minúscula ou um número, mas não um hífen

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

Exemplos de utilização de curl

Esta secção descreve as convenções e a configuração usadas para invocar a API SLO através da ferramenta curl. Se estiver a usar esta API através de uma biblioteca cliente, pode ignorar esta secção.

Os exemplos nesta página acedem à API SLO através da ferramenta curl para enviar pedidos HTTP para pontos finais REST. Use as seguintes informações sobre a autenticação e sobre a invocação de curl para definir as variáveis usadas nas invocações.

Autenticação

  1. Crie uma variável de ambiente para guardar o ID do projeto de âmbito de um âmbito de métricas: estes exemplos usam PROJECT_ID:

    PROJECT_ID=my-test-service

  2. Autentique-se na CLI do Google Cloud:

    gcloud auth login

  3. Para evitar ter de especificar o ID do projeto com cada comando, defina-o como predefinição através da CLI gcloud:

    gcloud config set project ${PROJECT_ID}

  4. Crie um token de autorização e capture-o numa variável de ambiente. Estes exemplos chamam a variável ACCESS_TOKEN:

    ACCESS_TOKEN=`gcloud auth print-access-token`

    Tem de atualizar periodicamente o token de acesso. Se os comandos que funcionavam indicarem subitamente que não tem autenticação, reemita este comando.

  5. Para verificar se recebeu um token de acesso, repita a variável ACCESS_TOKEN:

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

A invocar curl

Cada invocação de curl inclui um conjunto de argumentos, seguido do URL de um recurso da API SLO. Os argumentos comuns incluem valores especificados pelas variáveis de ambiente PROJECT_ID e ACCESS_TOKEN. Também pode ter de especificar outros argumentos, por exemplo, para especificar o tipo de pedido HTTP (por exemplo, -X DELETE). O pedido predefinido é GET, pelo que os exemplos não o especificam.

Cada invocação de 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 seu projeto, emita o seguinte pedido:GET

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

Este pedido devolve uma matriz de descrições de serviços, com entradas como a seguinte, um serviço de carga de trabalho do GKE com o ID do serviço "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 este serviço, consulte o artigo Criar um serviço. Tenha em atenção que a estrutura gkeWorkload nesta ficha é derivada da estrutura basicService usada para criar o serviço. Consulte Service para mais informações sobre a estrutura de um serviço.

Gerir serviços

O recurso Service funciona como o elemento raiz para organizar os seus serviços. Os aspetos de um serviço específico, como os respetivos SLOs, por exemplo, estão organizados sob o nome do serviço. Estes são os tipos de serviços compatíveis:

  • Serviço do App Engine: APP_ENGINE
  • Serviço Cloud Endpoints: CLOUD_ENDPOINTS
  • Serviço Istio canónico: 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 os Tipos de serviços básicos ou os Tipos de serviços básicos do GKE.

Pode adicionar SLOs a qualquer serviço no seu projeto através da API. A secção Gerir SLOs aborda os comandos para manipular SLOs.

IDs dos serviços

Cada serviço tem um identificador totalmente qualificado denominado nome do recurso. Este identificador é 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",

O nome do recurso contém um ID mais curto para o serviço, a parte do nome do recurso após a subcadeia de carateres projects/PROJECT_NUMBER/services/

Se criou o seu próprio serviço com o nome do recurso projects/PROJECT_NUMBER/services/my-test-service, o ID do serviço é my-test-service.

Para brevidade e precisão, muitos curl exemplos partem do princípio de que o ID do serviço está na variável de ambiente SERVICE_ID, para que possa consultá-lo repetidamente.

Serviços de fichas

Para obter informações sobre todos os serviços no seu projeto, invoque o método services.list. Para obter informações sobre um serviço específico através do ID do serviço, use o método services.get:

Protocolo

Para listar informações sobre serviços através de curl, invoque o método services.list ou services.get enviando um pedido GET para:

  • 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, o pedido seguinte obtém 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}

Criar um serviço

Para criar um serviço, especifica uma representação do tipo de serviço e envia-a para o método services.create. Pode usar as estruturas de tipo de serviço descritas em Tipos de serviços básicos e Tipos de serviços básicos do GKE.

As estruturas variam, mas o processo de chamada da API é o mesmo. Tem de especificar um nome a apresentar para o serviço e um campo basicService que contenha a representação do serviço.

Opcionalmente, pode especificar o ID do serviço que quer que o serviço tenha. O exemplo seguinte mostra a criação de um serviço de carga de trabalho do {[gke_name_short}}:

Protocolo

Para criar o serviço através de curl, envie uma mensagem POST para o ponto final https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

  1. Se quiser fornecer um ID para o serviço, crie uma variável para o ID do serviço:

    SERVICE_ID=my-test-service

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

  2. Crie uma variável para conter o corpo do pedido 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 do pedido no ponto final e especifique o ID do serviço como o valor do parâmetro de consulta service_id:

    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 os tipos de serviços básicos ou os tipos de serviços básicos do GKE.

Eliminar um serviço

Para eliminar um serviço que criou, invoque o método services.delete e especifique o ID do serviço.

Protocolo

Para eliminar um serviço através do curl, envie um pedido DELETE para o ponto final https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID:

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

Gerir SLOs

Pode criar, eliminar e obter SLOs através da API SLO. Pode ter até 500 SLOs para cada serviço.

Para gerir SLOs de um serviço, tem de ter o ID do serviço. Os SLOs são denominados com base no serviço a que pertencem. Para ver informações sobre a identificação de IDs de serviços, consulte o artigo IDs de serviços.

SLOs de fichas

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

Protocolo

Para listar informações sobre serviços através de curl, invoque o método services.serviceLevelObjectives.list ou services.serviceLevelObjectives.get enviando um pedido 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 obter um SLO específico

Por exemplo, o pedido seguinte lista todos os SLOs associados ao ID do 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

Segue-se um SLO de disponibilidade obtido 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",
},

Este SLO baseia-se num SLI de disponibilidade, define um objetivo de desempenho de 98% e mede a conformidade ao longo de uma semana do calendário. Para mais informações sobre os INSs de disponibilidade, consulte o artigo Indicadores do nível de serviço.

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

Obter um SLO específico

Cada SLO tem um identificador exclusivo no serviço, que consiste na string que se segue a serviceLevelObjectives no campo name do SLO. No exemplo seguinte:

"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 obter informações sobre este SLO específico, peça o SLO por ID.

Protocolo

Para obter um SLO específico através de curl, invoque o método services.serviceLevelObjectives.get enviando um pedido GET para 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}

Criar um SLO

Para criar um SLO através da API SLO, tem de criar um objeto ServiceLevelObjective e transmiti-lo ao método serviceLevelObjectives.create.

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

  • Para a Cloud Service Mesh, o Istio no Google Kubernetes Engine e os serviços do App Engine, os SLIs estão predefinidos. Pode usar a consola do Cloud Service Mesh para criar SLOs. Só tem de especificar os objetivos de desempenho e os períodos de conformidade.

  • Para outros serviços, tem de definir os SLOs através da API SLO. Para especificar um SLO, também tem de criar um valor para o campo serviceLevelIndicator. Consulte o artigo Criar um indicador do nível de serviço para ver algumas técnicas e o artigo Criar INSs a partir de métricas para ver um conjunto de exemplos baseados em várias origens.

Também pode criar SLIs através da Google Cloud consola. Para mais informações, consulte o artigo Criar um SLO.

Esqueleto 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.
}

Tem de especificar o seguinte:

  • Nome a apresentar: uma descrição do SLO
  • Um indicador do nível de serviço, que é um dos três tipos:
  • O objetivo de desempenho (uma percentagem)
  • O período de conformidade, que é um de dois tipos:
    • Um período contínuo de determinada duração (em segundos)
    • Um período do calendário

Para mais informações acerca dos SLIs, dos objetivos de desempenho e dos períodos de conformidade, consulte o artigo Conceitos na monitorização de serviços.

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

Para outros serviços, tem de criar um SLI baseado em pedidos ou um SLI baseado em janelas. Consulte o artigo Criar um indicador de nível de serviço para conhecer algumas técnicas.

Exemplo

Depois de ter o SLI, pode criar o SLO. O exemplo seguinte define um SLO para um serviço que usa um SLI básico. Pode ter vários SLOs num único SLI, por exemplo, um para 95% de disponibilidade e outro para 99% de disponibilidade. O exemplo seguinte é um SLO para uma disponibilidade de 95% durante uma semana civil: 

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

Este exemplo especifica um SLO para 75% de disponibilidade durante um período contínuo de 3 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 através de curl, envie uma mensagem POST para o ponto final https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives

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

    SERVICE_ID=custom:my-test-service

  2. Crie uma variável para conter o corpo do pedido, 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 do pedido no ponto final:

    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

    Opcionalmente, também pode especificar um ID desejado 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}

Eliminar um SLO

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

Protocolo

Para eliminar um SLO através de curl, envie um pedido DELETE para o ponto final 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}

Aceder a intervalos temporais de SLO

Os dados de SLO são armazenados em séries cronológicas, pelo que pode usar o método timeSeries.list para os obter. No entanto, estes dados não são armazenados em tipos de métricas padrão, pelo que não pode usar o mecanismo padrão de especificação de um filtro de tipo de métrica no método timeSeries.list.

Em alternativa, as séries cronológicas de SLO são obtidas especificando outro tipo de filtro, um selector de séries cronológicas, para o método timeSeries.list no parâmetro filter. Consulte o artigo Obter dados de SLO para ver informações sobre a utilização destes seletores.

Também usa seletores de séries cronológicas para configurar políticas de alerta de forma programática. Consulte o artigo Alertas sobre a taxa de consumo para mais informações.