Como trabalhar com a API

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

Esta página 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.

É possível usar a API SLO para gerenciar serviços e objetivos de nível de serviço (SLOs, na sigla em inglês). Nesta página, o foco está nos serviços personalizados e nos indicadores de nível de serviço (SLIs, na sigla em inglês). Os serviços executados no Anthos Service Mesh, no Istio do Google Kubernetes Engine e no App Engine são detectados automaticamente, e os SLIs deles são predefinidos:

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

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.

Autenticação

  1. Crie uma variável de ambiente para conter o ID do projeto de escopo de um escopo de métrica ou do projeto host do Workspace. Estes exemplos usam PROJECT_ID:

    PROJECT_ID=my-test-service
    
  2. Faça a autenticação no SDK do Cloud:

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

    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

Ela retorna uma matriz de descrições de serviço com as entradas do tipo a seguir, incluindo um serviço do Istio chamado "currencyservice":

{
  "services": [
    {
      "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"
      }
    },
   ...
  ]
}

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 componentes de um serviço específico, como os SLOs, são organizados de acordo com o nome do serviço.

Os serviços no Anthos Service Mesh, no Istio do Google Kubernetes Engine e no App Engine são criados automaticamente. É possível adicionar SLOs a esses serviços usando o console Anthos Service Mesh ou a API SLO.

Os serviços criados manualmente são chamados de personalizados. É possível criar, excluir, recuperar e atualizar serviços personalizados somente por meio da API SLO.

Depois de identificar ou criar um serviço, adicione SLOs a ele. Consulte Como gerenciar SLOs para acessar os comandos relacionados.

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

Se você não estiver usando um ambiente em que os serviços são criados automaticamente (ou seja, o Anthos Service Mesh, o Istio no Google Kubernetes Engine e o App Engine), será possível criar os serviços usando o metodo services.create.

Se você criar serviços por conta própria, será necessário adicionar manualmente os SLOs e outros artefatos de monitoramento de serviço à estrutura do serviço. Para isso, use a API SLO. Para uma visão geral dessas estruturas, consulte Construções na API.

Para criar um serviço, você precisa especificar um nome de exibição e um campo chamado custom com um objeto vazio. Se preferir, especifique o ID que você quer atribuir ao serviço.

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 Service",
        "custom": {}
    }
    EOF
    )
    
  3. Publique o corpo da solicitação no endpoint 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}
    

Exclusão de um serviço

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

Protocolo

Para excluir um serviço usando o curl, envie uma solicitação DELETE ao endpoint 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}

Como gerenciar SLOs

Os SLOs estão associados aos serviços. Para criá-los, use o console do Anthos Service Mesh para o Anthos Service Mesh, o Istio no Google Kubernetes Engine e o App Engine ou a API SLO. Você precisa usar essa API para criar SLOs de serviços personalizados.

Também é possível utilizar essa API para recuperar e excluir os SLOs associados a um serviço. É possível 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. Consulte esta seção para saber como reconhecer 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 o método services.serviceLevelObjectives.list ou services.serviceLevelObjectives.get. Basta enviar uma solicitação GET a:

  • 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

Veja 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 Anthos Service Mesh, Istio no Google Kubernetes Engine e App Engine, os SLIs são predefinidos. Use o console do Anthos Service Mesh para criar SLOs. Você só precisa especificar as metas de desempenho e os períodos de conformidade.

    Também é possível definir SLOs usando a API SLO.

  • Nos serviços personalizados, você precisa usar a API SLO para definir SLOs. Para especificar um SLO, você também precisa criar um valor para o campo serviceLevelIndicator. Consulte Como criar um indicador de nível de serviço para algumas técnicas.

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 Anthos Service Mesh, o Istio no Google Kubernetes Engine e os serviços do App Engine, o tipo SLI é o SLI básico.

Nos serviços personalizados, 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"
}

Veja 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.