Neste documento, descrevemos como usar a Google Cloud CLI ou a A API Cloud Monitoring para configurar o escopo de métricas de um projeto do Google Cloud. Esta página é destinada a desenvolvedores e administradores de sistemas.
Os comandos nesta página se referem a um contêiner de recursos, que é sempre um projeto do Google Cloud.
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 as funções de gerenciamento de identidade e acesso (IAM) no projeto de escopo e em cada projeto que você quer adicionar como um projeto monitorado incluem todas as permissões na função de administrador de monitoramento (
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íncrona.
Se você planeja invocar a API Cloud Monitoring usando
curl
ou se quiser usar os exemplos desta página, conclua as etapas de configuração do comandocurl
.
Listar todos os escopos de métricas que incluem um projeto
gcloud
Para obter uma lista de escopos de métricas que podem exibir as métricas de um
contêiner de recursos, como um projeto do Google Cloud, executam
Comando gcloud beta monitoring metrics-scopes list
:
gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME
Antes de executar o comando, digite o identificador do
contêiner de recursos para a variável MONITORED_RESOURCE_CONTAINER_NAME.
Quando o contêiner de recursos for um projeto do Google Cloud,
digite projects/PROJECT_ID_OR_NUMBER
.
Por exemplo, para listar os escopos de métricas que incluem o escopo
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 conferir 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}
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.
Mais detalhes sobre um escopo de métricas
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, digite o nome totalmente qualificado de um escopo de métricas para a variável METRICS_SCOPE_ID. Confira a seguir um exemplo de nome totalmente qualificado:
locations/global/metricsScopes/012345012345
Veja 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 é o mesmo:
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 do Google Cloud pelo ID, execute o comando gcloud projects list
e filtre pelo ID do projeto. Por exemplo, para
encontrar 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}
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.
Adicionar um projeto a um escopo de métricas
Se você estiver usando o App Hub, para conferir as métricas do sistema do App Hub, é preciso configurar Projeto host do App Hub e o escopo de métricas. A adição de um Projeto de serviço do App Hub para um projeto host do App Hub não modifique o escopo das métricas do projeto. Da mesma forma, adicionar um projeto a um o escopo de métricas não modifica a lista de Projetos de serviço do App Hub anexados ao o projeto host do App Hub. Para informações sobre como configurar um projeto host do App Hub, consulte Adicionar ou remover projetos de serviço.
gcloud
Para adicionar um contêiner de recursos, como um projeto do Google Cloud, a um escopo de métricas:
executar gcloud beta monitoring metrics-scopes create
comando:
gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER
Antes de executar o comando anterior, faça o seguinte:
Insira o nome ou o ID do projeto do Google Cloud cujo escopo de métricas será modificado na variável SCOPING_PROJECT_ID_OR_NUMBER.
Insira o identificador do contêiner de recursos na variável MONITORED_RESOURCE_CONTAINER_NAME: Quando o contêiner de recursos for um projeto do Google Cloud, digite
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 concluído com sucesso:
Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].
curl
Para adicionar um projeto do Google Cloud a um escopo de métricas,
envie uma solicitação POST
para o
endpoint
locations.global.metricsScopes.projects.create
. No exemplo a seguir, o projeto identificado pela variável de ambiente MONITORED_PROJECT_ID_OR_NUMBER
é adicionado como projeto monitorado:
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
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": "GCP", "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 do Google Cloud não invoca esse método de API. Portanto, as modificações feitas em um escopo de métricas ao usar o Console do Google Cloud não são registradas nos registros de auditoria.
Remover um projeto do escopo de métricas
Se você estiver usando o App Hub, antes de remover de um projeto do escopo das métricas garantem que o projeto não esteja sendo usado um aplicativo do App Hub. Remover o projeto da escopo de métricas não afetará o aplicativo. No entanto, você não poderá para visualizar as métricas do sistema desse aplicativo no contexto da projeto host do App Hub. Para informações sobre como configurar um projeto host do App Hub, consulte Adicionar ou remover projetos de serviço.
gcloud
Para remover um contêiner de recursos, como um projeto do Google Cloud, faça o seguinte:
de um escopo de métricas, execute
Comando gcloud beta monitoring metrics-scopes delete
:
gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER
Antes de executar o comando anterior, faça o seguinte:
Insira o nome ou o ID do projeto do Google Cloud cujo escopo de métricas será modificado na variável SCOPING_PROJECT_ID_OR_NUMBER.
Insira o identificador do contêiner de recursos na variável MONITORED_RESOURCE_CONTAINER_NAME: Quando o o contêiner de recursos é um projeto do Google Cloud, digite
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 concluído com sucesso:
Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].
O erro a seguir é informado quando o projeto de escopo não está monitorando o projeto especificado pela variável MONITORED_RESOURCE_CONTAINER_NAME:
NOT_FOUND: Requested entity was not found.
curl
Para remover um projeto do 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}
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 do Google Cloud não invoca esse método de API. Portanto, as modificações feitas em um escopo de métricas ao usar o console do Google Cloud não são incluídos nos registros de auditoria.
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 endpointoperation.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 campoOperation.name
.Quando
done
étrue
, a operação é concluída e o campoerror
ouresponse
está definido:error
: quando definida, a operação assíncrona falha. O valor desse campo é um objetoStatus
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
:
Crie a variável de ambiente para armazenar o ID ou o número do projeto de escopo:
SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER
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
Faça a autenticação na Google Cloud CLI:
gcloud auth login
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}
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.
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 tenha que especificar outros argumentos, por exemplo, para especificar o
tipo da solicitação HTTP (por exemplo, -X DELETE
). A solicitação padrão
é GET
, então os exemplos não o especificam.
A seguir
Para informações sobre como usar o Google Cloud com o Terraform, consulte os seguintes recursos: