使用 API 配置指标范围

本文档介绍如何使用 Google Cloud CLI 或 Cloud Monitoring API 配置 Google Cloud 项目的指标范围。本页面适用于开发者和系统管理员。

此页面上的命令引用“资源容器”。虽然资源容器可以是组织、文件夹或项目,但本页面介绍的命令仅支持 Google Cloud 项目。

准备工作

  • 如果您不熟悉术语“指标范围”和“范围项目”,请参阅指标范围

  • 确保范围项目以及要添加为受监控项目的每个项目上的 Identity and Access Management (IAM) 角色包含 Monitoring Admin (roles/monitoring.admin) 角色中的所有权限。如需了解详情,请参阅指标范围配置

  • Cloud Monitoring API 中检索信息的指标作用域方法是同步的;但是,更改状态的 API 是异步的。Google Cloud CLI 命令会阻塞,直到异步操作完成。如需了解如何确定异步 API 方法何时完成以及如何确定其状态,请参阅异步 API 方法

  • 如果您计划使用 curl 调用 Cloud Monitoring API,或者希望使用本页面上的示例,请完成 curl 命令设置步骤。

列出包含项目的所有指标范围

gcloud

如需获取指标范围列表,以便查看资源容器(如 Google Cloud 项目)的指标,请运行 gcloud beta monitoring metrics-scopes list 命令:

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

在运行该命令之前,请在变量 MONITORED_RESOURCE_CONTAINER_NAME 中输入资源容器的标识符。如果资源容器是 Google Cloud 项目,请输入 projects/PROJECT_ID_OR_NUMBER

例如,如需列出包含项目 my-project 的指标范围,请运行以下命令:

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

以下响应表明项目 my-project 包含在两个指标范围内:

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'

如需获取有关指标范围的详细信息,请运行 gcloud beta monitoring metrics-scopes describe 命令。

curl

如需获取可查看项目指标的指标范围的列表,请向 locations.global.metricsScopes.listMetricsScopesByMonitoredProject 端点发送 GET 请求并添加指定项目的查询参数。

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

成功后,响应将是一组 MetricsScope 对象。

此方法不会导致系统将条目写入范围限定项目的审核日志。如需将这些操作记录在审核日志中,请为 Cloud Resource Manager API 启用数据读取。如需了解详情,请参阅配置数据访问审核日志

获取有关指标范围的详细信息

gcloud

如需获取有关指标范围的详细信息,请运行 gcloud beta monitoring metrics-scopes describe 命令:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

在运行该命令之前,请在变量 METRICS_SCOPE_ID 中输入指标范围的完全限定名称。以下是完全限定名称的示例:

locations/global/metricsScopes/012345012345

以下是一个响应示例。在此示例中,指标范围包含一个项目,并且指标范围和项目的 ID 相同:

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'

如需根据 ID 识别 Google Cloud 项目,请运行 gcloud projects list 命令并按项目 ID 进行过滤。例如,如需获取项目 012345012345 的名称,请运行以下命令:

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

curl

如需获取有关指标范围的信息,请向 locations.global.metricsScopes.get 端点发送 GET 请求:

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

成功后,该响应是一个 MetricsScope 对象。

此方法不会导致系统将条目写入范围限定项目的审核日志。如需将这些操作记录在审核日志中,请为 Cloud Resource Manager API 启用数据读取。如需了解详情,请参阅配置数据访问审核日志

将项目添加到指标范围

gcloud

如需将资源容器(例如 Google Cloud 项目)添加到指标范围,请运行 gcloud beta monitoring metrics-scopes create 命令:

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

在运行上一个命令之前,请执行以下操作:

  • 在变量 SCOPING_PROJECT_ID_OR_NUMBER 中输入要修改其指标范围的 Google Cloud 项目的名称或 ID。

  • 在变量 MONITORED_RESOURCE_CONTAINER_NAME 中输入资源容器的标识符。如果资源容器是 Google Cloud 项目,请输入 projects/PROJECT_ID_OR_NUMBER

例如,以下命令会将项目 my-monitored-project 添加到名为 my-staging-projects 的项目的指标范围内:

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

对上一个命令的响应提供确认命令已成功完成的确认信息:

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

curl

如需将 Google Cloud 项目添加到指标范围,请向 locations.global.metricsScopes.projects.create 端点发送 POST 请求。在以下示例中,环境变量 MONITORED_PROJECT_ID_OR_NUMBER 标识的项目会添加为受监控的项目:

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

此异步方法的响应是一个 Operation 对象。

调用此方法的应用应轮询 operation.get 端点,直到 Operation.done 字段的值为 true。当 Operation.done 字段设置为 false 时,表示操作正在进行中。如需了解详情,请参阅异步 API 命令

下面是成功添加受监控项目时的响应示例:

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

在上一个响应中,Operation.done 字段设置为 true。此值表示命令已完成。由于命令成功完成,因此 Operation.response 字段已设置且其值为 MonitoredProject 对象。response.name 字段包含范围限定项目和受监控项目的标识符。providerAccountId 字段列出了受监控项目的名称。

调用此方法会在范围限定项目的审核日志中生成一个条目。Google Cloud 控制台不会调用此 API 方法。因此,使用 Google Cloud 控制台对指标范围进行的修改不会记录在审核日志中。

从指标范围中移除项目

gcloud

如需从指标范围中移除资源容器(例如 Google Cloud 项目),请运行 gcloud beta monitoring metrics-scopes delete 命令:

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

在运行上一个命令之前,请执行以下操作:

  • 在变量 SCOPING_PROJECT_ID_OR_NUMBER 中输入要修改其指标范围的 Google Cloud 项目的名称或 ID。

  • 在变量 MONITORED_RESOURCE_CONTAINER_NAME 中输入资源容器的标识符。如果资源容器是 Google Cloud 项目,请输入 projects/PROJECT_ID_OR_NUMBER

例如,以下命令会从名为 my-staging-projects 的项目的指标范围中移除项目 my-monitored-project

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

对上一个命令的响应提供确认命令已成功完成的确认信息:

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

如果限定范围的项目未监控 MONITORED_RESOURCE_CONTAINER_NAME 变量指定的项目,系统会报告以下错误:

NOT_FOUND: Requested entity was not found.

curl

如需从指标范围中移除 Google Cloud 项目,请向 locations.global.metricsScopes.projects.delete 端点发送 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}

对此异步方法的响应是一个 Operation 对象。

调用此方法的应用应轮询 operation.get 端点,直到 Operation.done 字段的值为 true。当 Operation.done 字段设置为 false 时,表示操作正在进行中。如需了解详情,请参阅异步 API 命令

下面是成功移除受监控项目时的响应示例:

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

在上一个响应中,Operation.done 字段设置为 true。此值表示命令已完成。由于命令成功完成,因此 Operation.response 字段已设置且包含 @type 字段。

调用此方法会在范围限定项目的审核日志中生成一个条目。Google Cloud 控制台不会调用此 API 方法。因此,使用 Google Cloud 控制台对指标范围进行的修改不会记录在审核日志中。

异步 API 方法

Cloud Monitoring API 更改系统状态的所有指标范围方法都是异步的,例例如向受监控项目添加指标范围的命令。对于这些命令,命令响应是一个 Operation 对象。

调用异步 API 方法的应用应轮询 operation.get 端点,直到 Operation.done 字段的值为 true

  • donefalse 时,表示操作正在进行中。

    如需刷新状态信息,请向 operation.get 端点发送 GET 请求:

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

    在上一个命令中,OPERATION_NAME 是一个环境变量,用于存储 Operation.name 字段的值。

  • donetrue 时,表示操作已完成且已设置 errorresponse 字段:

    • error:设置此标志时,表示异步操作失败。此字段的值是一个 Status 对象,其中包含 gRPC 错误代码和错误消息。
    • response:如果设置此标志,则表示异步操作成功完成,并且值将反映结果。

curl 命令设置

本部分介绍本文档中用于创建 curl 命令的设置。此页面上的每个 curl 命令都包含一组参数,后跟 API 资源的网址:

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

设置以下环境变量,来简化 curl 命令的创建过程:

  1. 创建环境变量以存储范围限定项目 ID 或编号:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER
    
  2. 可选。如果您计划添加或移除受监控的项目,请使用受监控的项目 ID 或编号来配置环境变量:

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER
    
  3. 向 Google Cloud CLI 进行身份验证:

    gcloud auth login
    
  4. 可选。为避免在每个 gcloud 命令中指定项目 ID,请使用 gcloud CLI 将项目 ID 设置为默认值:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
    
  5. 创建授权令牌并将其存储到环境变量中:

    TOKEN=`gcloud auth print-access-token`
    

    令牌有效期有限。如果命令突然报告您未通过身份验证,请重新发布此命令。

  6. 要验证您是否已获得访问令牌,请回显 TOKEN 变量:

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

您可能还需要指定其他参数,例如指定 HTTP 请求的类型(例如 -X DELETE)。默认请求为 GET,因此示例中并未指定它。

后续步骤

如需了解如何将 Google Cloud 与 Terraform 结合使用,请参阅以下资源: