Configurar um escopo de métricas usando a API

Neste documento, descrevemos como usar a Google Cloud CLI ou a API Cloud Monitoring para configurar o escopo de métricas de um projeto Google Cloud . Esta página é destinada a desenvolvedores e administradores de sistemas.

Também é possível usar o Terraform para configurar um escopo de métricas. Para mais informações, consulte o registro do Terraform para google_monitoring_monitored_project.

Escopos de métricas e aplicativos do App Hub

Você gerencia o escopo das métricas para projetos host do App Hub. É possível gerenciar esse escopo usando o console doGoogle Cloud ou a API Cloud Monitoring.

Google Cloud gerencia o escopo de métricas para pastas habilitadas para apps, a menos que a adição de um projeto ao escopo de métricas falhe devido ao esgotamento da cota do escopo de métricas. Nesse caso, você pode solicitar um aumento de cota e adicionar manualmente projetos ao escopo de métricas do projeto de gerenciamento da pasta ativada para apps. Para saber mais, consulte Escopos de métricas para pastas habilitadas para apps.

Antes de começar

  • Se você não estiver familiarizado com os termos escopo das métricas e projeto do escopo, consulte Noções básicas sobre escopos de métricas.

  • Verifique se os papéis do Identity and Access Management (IAM) no projeto de escopo e em cada projeto que você quer adicionar ou remover de um escopo de métricas incluem todas as permissões no papel de administrador do Monitoring (roles/monitoring.admin). Para mais informações, consulte Configurações de escopo de métricas.

  • Os métodos de escopo das métricas da API Cloud Monitoring que recuperam informações são síncronos; No entanto, as APIs que alteram o estado são assíncronas. Os comandos da CLI do Google Cloud são bloqueados até que a operação assíncrona seja concluída. Para informações sobre como determinar quando um método de API assíncrono é concluído e como determinar o status dele, consulte Métodos de API assíncronos.

  • Se você planeja invocar a API Cloud Monitoring usando curl ou se quiser usar os exemplos nesta página, conclua as etapas de configuração do comando curl.

Adicionar um projeto a um escopo de métricas

gcloud

Para adicionar um projeto Google Cloud a um escopo de métricas, execute o comando gcloud beta monitoring metrics-scopes create:

gcloud beta monitoring metrics-scopes create MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

Antes de executar o comando anterior, faça o seguinte:

  • Insira o nome ou ID do projeto Google Cloud cujo escopo de métricas será modificado na variável SCOPING_PROJECT_ID_OR_NUMBER. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

  • Insira o identificador do projeto monitorado na variável MONITORED_PROJECT_ID_OR_NUMBER. O formato é projects/PROJECT_ID_OR_NUMBER.

Por exemplo, o comando a seguir adiciona o projeto my-monitored-project ao escopo de métricas do projeto chamado my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

A resposta ao comando anterior confirma que ele foi concluído com sucesso:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

Para adicionar um projeto Google Cloud a um escopo de métricas, envie uma solicitação POST para o endpoint locations.global.metricsScopes.projects.create:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

No exemplo anterior, as variáveis de ambiente são definidas da seguinte maneira:

  • MONITORED_PROJECT_ID_OR_NUMBER armazena o ID do projeto a ser adicionado ao escopo de métricas.
  • SCOPING_PROJECT_ID_OR_NUMBER armazena o ID do projeto cujo escopo de métricas está sendo atualizado.

A resposta desse método assíncrono é um objeto Operation.

Os aplicativos que chamam esse método precisam pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true. Quando o campo Operation.done está definido como false, isso indica que a operação está em andamento. Para mais informações, consulte Comandos de API assíncronas.

Veja a seguir um exemplo de resposta ao adicionar um projeto monitorado:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

Na resposta anterior, o campo Operation.done está definido como true. Esse valor indica que o comando foi concluído. Como o comando foi concluído com sucesso, o campo Operation.response está definido e o valor é um objeto MonitoredProject. O campo response.name inclui o identificador do projeto de escopo e do projeto monitorado. O campo providerAccountId lista o nome do projeto monitorado.

Invocar esse método resulta em uma entrada nos registros de auditoria do projeto do escopo. O console Google Cloud não invoca esse método de API. Portanto, as modificações feitas em um escopo de métricas ao usar o consoleGoogle Cloud não são registradas nos registros de auditoria.

Remover um projeto do escopo de métricas

gcloud

Para remover um projeto Google Cloud de um escopo de métricas, execute o comandogcloud beta monitoring metrics-scopes delete:

gcloud beta monitoring metrics-scopes delete MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

Antes de executar o comando anterior, faça o seguinte:

  • Insira o nome ou ID do projeto Google Cloud cujo escopo de métricas será modificado na variável SCOPING_PROJECT_ID_OR_NUMBER. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

  • Insira o identificador do projeto monitorado na variável MONITORED_PROJECT_ID_OR_NUMBER. O formato é projects/PROJECT_ID_OR_NUMBER.

Por exemplo, o comando a seguir remove o projeto my-monitored-project do escopo de métricas do projeto chamado my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

A resposta ao comando anterior confirma que ele foi concluído com sucesso:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

O seguinte erro é informado quando o projeto de escopo não está monitorando o projeto especificado pela variável MONITORED_PROJECT_ID_OR_NUMBER:

NOT_FOUND: Requested entity was not found.

curl

Para remover um projeto Google Cloud de um escopo de métricas, envie uma solicitação DELETE para o endpoint locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

No exemplo anterior, as variáveis de ambiente são definidas da seguinte maneira:

  • MONITORED_PROJECT_ID_OR_NUMBER armazena o ID do projeto a ser removido do escopo de métricas.
  • SCOPING_PROJECT_ID_OR_NUMBER armazena o ID do projeto cujo escopo de métricas está sendo atualizado.

A resposta a esse método assíncrono é um objeto Operation.

Os aplicativos que chamam esse método precisam pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true. Quando o campo Operation.done está definido como false, isso indica que a operação está em andamento. Para mais informações, consulte Comandos de API assíncronas.

Veja a seguir um exemplo de resposta quando a remoção de um projeto monitorado é bem-sucedida:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Na resposta anterior, o campo Operation.done está definido como true. Esse valor indica que o comando foi concluído. Como o comando foi concluído com sucesso, o campo Operation.response está definido e contém um campo @type.

Invocar esse método resulta em uma entrada nos registros de auditoria do projeto do escopo. O console Google Cloud não invoca esse método de API. Portanto, as modificações feitas em um escopo de métricas ao usar o consoleGoogle Cloud não são registradas nos registros de auditoria.

Listar todos os escopos de métricas que incluem um projeto

Se você quiser saber quais recursos podem acessar os dados armazenados por um projetoGoogle Cloud , liste todos os escopos de métricas que incluem o projeto e encontre detalhes sobre eles. Nesta seção, você vai encontrar informações sobre como listar o escopo de métricas que inclui um projeto específico doGoogle Cloud .

gcloud

Para uma lista de escopos de métricas que podem ver as métricas de um projetoGoogle Cloud , execute o comando gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER

Antes de executar o comando, insira o identificador do projeto monitorado na variável MONITORED_PROJECT_ID_OR_NUMBER. O formato é projects/PROJECT_ID_OR_NUMBER.

Por exemplo, para listar os escopos de métricas que incluem o projeto my-project, execute o seguinte comando:

gcloud beta monitoring metrics-scopes list projects/my-project

A resposta a seguir indica que o projeto my-project está incluído em dois escopos de métricas:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

Para informações detalhadas sobre um escopo de métricas, execute o comando gcloud beta monitoring metrics-scopes describe.

curl

Para uma lista de escopos de métricas que podem ver as métricas de um projeto, envie uma solicitação GET para o endpoint locations.global.metricsScopes.listMetricsScopesByMonitoredProject e inclua a consulta. que especifica o projeto.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

No exemplo anterior, a variável de ambiente PROJECT_ID_OR_NUMBER armazena o ID do projeto cuja inclusão no escopo de métricas está sendo consultada.

Quando bem-sucedida, a resposta é uma matriz de objetos MetricsScope.

Esse método não faz com que uma entrada seja gravada nos registros de auditoria do projeto de escopo. Para registrar essas ações no registro de auditoria, ative a Leitura de dados para a API Cloud Resource Manager. Para mais informações, veja Como configurar os registros de auditoria de acesso a dados.

Receber detalhes sobre um escopo de métricas

Esta seção mostra como encontrar detalhes sobre um escopo de métricas específico.

gcloud

Para informações detalhadas sobre um escopo de métricas, execute o comando gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Antes de executar o comando, insira o nome totalmente qualificado de um escopo de métricas na variável METRICS_SCOPE_ID. Confira um exemplo de nome totalmente qualificado:

locations/global/metricsScopes/012345012345

Confira a seguir um exemplo de resposta. Neste exemplo, o escopo de métricas contém um projeto, e o ID do escopo de métricas e do projeto são os mesmos:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

Para identificar o projeto Google Cloud pelo ID, execute o comando gcloud projects list e filtre pelo ID do projeto. Por exemplo, para receber o nome do projeto 012345012345, execute o seguinte comando:

gcloud projects list --filter="012345012345" --format="value(NAME)"

curl

Para informações sobre um escopo de métricas, envie uma solicitação GET para o endpoint locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

No exemplo anterior, a variável de ambiente SCOPING_PROJECT_ID_OR_NUMBER armazena o ID do projeto cujo escopo de métricas está sendo consultado.

Quando bem-sucedida, a resposta é um objeto MetricsScope.

Esse método não faz com que uma entrada seja gravada nos registros de auditoria do projeto de escopo. Para registrar essas ações no registro de auditoria, ative a Leitura de dados para a API Cloud Resource Manager. Para mais informações, veja Como configurar os registros de auditoria de acesso a dados.

Métodos de API assíncronos

Todos os métodos de escopo de métricas da API Cloud Monitoring que alteram o estado do sistema, por exemplo, o comando para adicionar um projeto de métricas a um escopo de métricas, são assíncronos. Para esses comandos, a resposta ao comando é um objeto Operation.

Os aplicativos que chamam um método de API assíncrono devem pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true:

  • Quando done é false, a operação está em andamento.

    Para atualizar as informações de status, envie uma solicitação GET para o endpoint operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}

    No comando anterior, OPERATION_NAME é uma variável de ambiente que armazena o valor do campo Operation.name.

  • Quando done é true, a operação é concluída e o campo error ou response está definido:

    • error: quando definida, a operação assíncrona falha. O valor desse campo é um objeto Status que contém um código de erro do gRPC e uma mensagem de erro.
    • response: quando definido, a operação assíncrona é concluída e o valor reflete o resultado.

Configuração do comando curl

Nesta seção, descrevemos a configuração usada para criar os comandos curl neste documento. Cada comando curl nesta página inclui um conjunto de argumentos, seguido pelo URL de um recurso da API:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Defina essas variáveis de ambiente para simplificar a criação de comandos curl:

  1. Crie a variável de ambiente para armazenar o ID ou o número do projeto de escopo. Se você estiver usando o App Hub, defina essa variável como o ID do projeto host do App Hub ou o ID do projeto de gerenciamento da pasta ativada por apps:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. Opcional. Se você planeja adicionar ou remover projetos monitorados, configure a variável de ambiente com o ID ou o número do projeto monitorado:

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

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

    gcloud auth login

  4. Opcional. Para evitar a necessidade de especificar o ID do projeto com cada comando gcloud, defina o ID do projeto como padrão usando a CLI gcloud:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. Crie um token de autorização e colete-o em uma variável de ambiente.

    TOKEN=`gcloud auth print-access-token`

    Os tokens são válidos por um tempo limitado. Se algum comando parar de funcionar com um erro de falta de autenticação, será necessário emiti-lo novamente.

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

    echo ${TOKEN}
ya29.GluiBj8o....

Talvez você também precise especificar outros argumentos, 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.

A seguir

Para informações sobre como usar Google Cloud com o Terraform, consulte os seguintes recursos: