Configura un alcance de métricas con la API

En este documento, se describe cómo usar Google Cloud CLI o la API de Cloud Monitoring para configurar el permiso de métricas de un proyecto de Google Cloud . Esta página está dirigida a desarrolladores y administradores del sistema.

También puedes usar Terraform para configurar un permiso de métricas. Para obtener más información, consulta el registro de Terraform para google_monitoring_monitored_project.

Aplicaciones de App Hub y permisos de métricas

Administras el alcance de las métricas para los proyectos host de App Hub. Puedes administrar este alcance con la consola deGoogle Cloud o la API de Cloud Monitoring.

Google Cloud administra el alcance de las métricas para las carpetas habilitadas para la app, a menos que falle la adición de un proyecto al alcance de las métricas debido al agotamiento de la cuota del alcance de las métricas. En este caso, puedes solicitar un aumento de la cuota y, luego, agregar manualmente proyectos al permiso de métricas del proyecto de administración para la carpeta habilitada para la app. Para obtener más información, consulta Permisos de métricas para carpetas habilitadas para apps.

Antes de comenzar

  • Si no estás familiarizado con los términos alcance de las métricas y proyecto de alcance, consulta alcances de métricas.

  • Asegúrate de que tus roles de Identity and Access Management (IAM) en el proyecto de alcance y en cada proyecto que quieras agregar a un permiso de métricas o quitar de él incluyan todos los permisos del rol de administrador de Monitoring (roles/monitoring.admin). Para obtener más información, consulta Configuración de permisos de métricas.

  • Los métodos de alcance de métricas de la API de Cloud Monitoring que recuperan información son síncronos. Sin embargo, las API que cambian de estado son asíncronas. Los comandos de la CLI de Google Cloud se bloquean hasta que se completa la operación asíncrona. Para obtener información sobre cómo determinar cuándo se completa un método de API asíncrono y cómo determinar su estado, consulta Métodos de la API asíncronos.

  • Si planeas invocar la API de Cloud Monitoring con curl o si quieres usar los ejemplos de esta página, completa los pasos de configuración del comando curl.

Agrega un proyecto a un permiso de métricas

gcloud

Para agregar un proyecto Google Cloud a un permiso de métricas, ejecuta el 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 ejecutar el comando anterior, haz lo siguiente:

  • Ingresa el nombre o el ID del proyecto Google Cloud cuyo permiso de métricas se modificará en la variable SCOPING_PROJECT_ID_OR_NUMBER. Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración de la carpeta habilitada para la app.

  • Ingresa el identificador de tu proyecto supervisado en la variable MONITORED_PROJECT_ID_OR_NUMBER. El formato es projects/PROJECT_ID_OR_NUMBER.

Por ejemplo, el siguiente comando agrega el proyecto my-monitored-project al alcance de métricas del proyecto llamado my-staging-projects:

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

La respuesta al comando anterior proporciona la confirmación de que el comando se completó correctamente:

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

curl

Para agregar un proyecto Google Cloud a un permiso de métricas, envía una solicitud POST al extremolocations.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

En el ejemplo anterior, las variables de entorno se definen de la siguiente manera:

  • MONITORED_PROJECT_ID_OR_NUMBER almacena el ID del proyecto que se agregará al permiso de métricas.
  • SCOPING_PROJECT_ID_OR_NUMBER almacena el ID del proyecto cuyo permiso de métricas se está actualizando.

La respuesta de este método asíncrono es un objeto Operation.

Las aplicaciones que llaman a este método deben sondear el extremo operation.get hasta que el valor del campo Operation.done sea true. Cuando el campo Operation.done se establece en false, eso indica que la operación está en progreso. Para obtener más información, consulta Comandos de la API asíncronos.

El siguiente es un ejemplo de la respuesta cuando se agrega un proyecto supervisado:

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

En la respuesta anterior, el campo Operation.done se establece en true. Este valor indica que el comando está completo. Debido a que el comando se completó con éxito, el campo Operation.response se establece y su valor es un objeto MonitoredProject. El campo response.name incluye el identificador del proyecto de alcance y del proyecto supervisado. El campo providerAccountId muestra el nombre del proyecto supervisado.

Invocar este método da como resultado una entrada en los registros de auditoría del proyecto de alcance. La consola de Google Cloud no invoca este método de API. Por lo tanto, las modificaciones que se realizan a un permiso de métricas cuando se usa la consola deGoogle Cloud no se registran en los registros de auditoría.

Quita un proyecto de un permiso de métricas

gcloud

Para quitar un proyecto Google Cloud de un permiso de métricas, ejecuta el 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 ejecutar el comando anterior, haz lo siguiente:

  • Ingresa el nombre o el ID del proyecto Google Cloud cuyo permiso de métricas se modificará en la variable SCOPING_PROJECT_ID_OR_NUMBER. Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración de la carpeta habilitada para la app.

  • Ingresa el identificador de tu proyecto supervisado en la variable MONITORED_PROJECT_ID_OR_NUMBER. El formato es projects/PROJECT_ID_OR_NUMBER.

Por ejemplo, el siguiente comando quita el proyecto my-monitored-project del permiso de métricas del proyecto llamado my-staging-projects:

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

La respuesta al comando anterior proporciona la confirmación de que el comando se completó correctamente:

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

El siguiente error se informa cuando el proyecto de alcance no supervisa el proyecto especificado por la variable MONITORED_PROJECT_ID_OR_NUMBER:

NOT_FOUND: Requested entity was not found.

curl

Para quitar un proyecto Google Cloud de un permiso de métricas, envía una solicitud DELETE al extremolocations.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}

En el ejemplo anterior, las variables de entorno se definen de la siguiente manera:

  • MONITORED_PROJECT_ID_OR_NUMBER almacena el ID del proyecto que se quitará del permiso de métricas.
  • SCOPING_PROJECT_ID_OR_NUMBER almacena el ID del proyecto cuyo permiso de métricas se está actualizando.

La respuesta de este método asíncrono es un objeto Operation.

Las aplicaciones que llaman a este método deben sondear el extremo operation.get hasta que el valor del campo Operation.done sea true. Cuando el campo Operation.done se establece en false, eso indica que la operación está en progreso. Para obtener más información, consulta Comandos de la API asíncronos.

El siguiente es un ejemplo de la respuesta cuando la eliminación de un proyecto supervisado se realiza de forma correcta:

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

En la respuesta anterior, el campo Operation.done se establece en true. Este valor indica que el comando está completo. Debido a que el comando se completó con éxito, el campo Operation.response se establece y contiene un campo @type.

Invocar este método da como resultado una entrada en los registros de auditoría del proyecto de alcance. La consola de Google Cloud no invoca este método de API. Por lo tanto, las modificaciones que se realizan a un permiso de métricas cuando se usa la consola deGoogle Cloud no se registran en los registros de auditoría.

Enumera todos los permisos de las métricas que incluyen un proyecto

Si quieres saber qué recursos pueden ver los datos almacenados por un proyectoGoogle Cloud , puedes enumerar todos los alcances de métricas que incluyen el proyecto y, luego, buscar detalles sobre esos alcances. En esta sección, se proporciona información para enumerar los permisos de métricas que incluyen unGoogle Cloud proyecto específico.

gcloud

Para obtener una lista de los alcances de métricas que pueden ver las métricas de un proyectoGoogle Cloud , ejecuta el comando gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER

Antes de ejecutar el comando, ingresa el identificador de tu proyecto supervisado en la variable MONITORED_PROJECT_ID_OR_NUMBER. El formato es projects/PROJECT_ID_OR_NUMBER.

Por ejemplo, para enumerar los alcances de métricas que incluyen el proyecto my-project, ejecuta el siguiente comando:

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

La siguiente respuesta indica que el proyecto my-project se incluye en dos permisos 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 obtener información detallada sobre un permiso de métricas, ejecuta el comando gcloud beta monitoring metrics-scopes describe.

curl

Para obtener una lista de los alcances de métricas que pueden ver las métricas de un proyecto, envía una solicitud GET al extremo locations.global.metricsScopes.listMetricsScopesByMonitoredProject y, luego, incluye la consulta. que especifica el proyecto.

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

En el ejemplo anterior, la variable de entorno PROJECT_ID_OR_NUMBER almacena el ID del proyecto cuya inclusión en el permiso de métricas se consulta.

Cuando se ejecuta de forma correcta, la respuesta es un array de objetos MetricsScope.

Este método no hace que se escriba una entrada en los registros de auditoría del proyecto de alcance. Para registrar estas acciones en el registro de auditoría, habilita Lectura de datos en la API de Cloud Resource Manager. Para obtener más información, consulta el artículo Configuración de registros de auditoría de acceso a los datos.

Obtén detalles sobre un permiso de métricas

En esta sección, se muestra cómo encontrar detalles sobre un alcance de métricas específico.

gcloud

Para obtener información detallada sobre un alcance de métricas, ejecuta el comando gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Antes de ejecutar el comando, ingresa el nombre completamente calificado de un alcance de métricas en la variable METRICS_SCOPE_ID. A continuación, se muestra un ejemplo de un nombre completamente calificado:

locations/global/metricsScopes/012345012345

A continuación, se muestra un ejemplo de respuesta. En este ejemplo, el permiso de métricas contiene un proyecto, y el ID del permiso de métricas y el proyecto son los mismos:

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 el proyecto Google Cloud a partir de su ID, ejecuta el comandogcloud projects listy filtra por el ID del proyecto. Por ejemplo, para obtener el nombre del proyecto 012345012345, ejecuta el siguiente comando:

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

curl

Para obtener información sobre el alcance de una métrica, envía una solicitud GET al extremo locations.global.metricsScopes.get:

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

En el ejemplo anterior, la variable de entorno SCOPING_PROJECT_ID_OR_NUMBER almacena el ID del proyecto cuyo permiso de métricas se consulta.

Cuando se ejecuta de forma correcta, la respuesta es un objeto MetricsScope.

Este método no hace que se escriba una entrada en los registros de auditoría del proyecto de alcance. Para registrar estas acciones en el registro de auditoría, habilita Lectura de datos en la API de Cloud Resource Manager. Para obtener más información, consulta el artículo Configuración de registros de auditoría de acceso a los datos.

Métodos de la API asíncronos

Todos los métodos de alcance de métricas de la API de Cloud Monitoring que cambian el estado del sistema, por ejemplo, el comando para agregar un proyecto supervisado a un alcance de métricas, son asíncronos. Para estos comandos, la respuesta del comando es un objeto Operation.

Las aplicaciones que llaman a un método de API asíncrono deben sondear el extremo operation.get hasta que el valor del campo Operation.done sea true:

  • Cuando done está false, la operación está en progreso.

    Para actualizar la información de estado, envía una solicitud GET al extremo operation.get:

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

    En el comando anterior, OPERATION_NAME es una variable de entorno que almacena el valor del campo Operation.name.

  • Cuando done es true, la operación está completa y el campo error o response está configurado:

    • error: Cuando se configura, falla la operación asíncrona. El valor de este campo es un objeto Status que contiene un código de error de gRPC y un mensaje de error.
    • response: Cuando se establece, la operación asíncrona se completó de forma correcta y el valor refleja el resultado.

Configuración del comando curl

En esta sección, se describe la configuración que se usó para crear los comandos curl en este documento. Cada comando curl de esta página incluye un conjunto de argumentos, seguido de la URL de un recurso de la API:

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

Configura estas variables de entorno para simplificar la creación de los comandos curl:

  1. Crea la variable de entorno para almacenar el ID o el número del proyecto de alcance. Si usas App Hub, establece esta variable en el ID de tu proyecto host de App Hub o en el ID del proyecto de administración de tu carpeta habilitada para aplicaciones:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. Opcional. Si planeas agregar o quitar proyectos supervisados, configura la variable de entorno con el ID o el número del proyecto supervisado:

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. Autentica en la CLI de Google Cloud:

    gcloud auth login

  4. Opcional. Para evitar tener que especificar el ID del proyecto con cada comando gcloud, configúralo como predeterminado con gcloud CLI:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. Crea un token de autorización y captúralo en una variable de entorno:

    TOKEN=`gcloud auth print-access-token`

    Los tokens son válidos por tiempo limitado. Si los comandos que funcionaban de repente informan que no estás autenticado, entonces vuelve a emitir este comando.

  6. Para verificar que cuentas con un token de acceso, reproduce la variable TOKEN:

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

Es posible que también debas especificar otros argumentos, por ejemplo, el tipo de solicitud HTTP (por ejemplo, -X DELETE). La solicitud predeterminada es GET, por lo que los ejemplos no lo especifican.

¿Qué sigue?

Para obtener información sobre el uso de Google Cloud con Terraform, consulta los siguientes recursos: