采集器「GoogleCloud-云监控」配置手册¶

阅读本文前，请先阅读：

Tip

使用本采集器前，必须安装「集成 Core 核心包」及其配套的第三方依赖包

Tip

该采集器默认支持开启多线程（默认开启五个线程），如果需要更改线程池大小，可以设置环境变量 COLLECTOR_THREAD_POOL_SIZE

1. 配置结构¶

本采集器配置结构如下：

字段	类型	是否必须	说明
`targets`	list	必须	云监控采集对象配置列表相同命名空间的多个配置之间逻辑关系为「且」
`targets[#].namespace`	str	必须	所需采集的云监控命名空间。如：`'compute.googleapis.com'`
`targets[#].metrics`	list	必须	所需采集的云监控指标名列表
`targets[#].metrics[#]`	str	必须	指标名模式，支持`"NOT"`、通配符方式匹配正常情况下，多个之间逻辑关系为「或」包含`"NOT"`标记时，多个之间逻辑关系为「且」。详见下文

1.1 指标类型¶

在了解采集器配置结构前，我们首先了解下 GCP 的指标类型（Metric Type），完整的指标类型组成{namespace}/{metric}，例：

Compute Engine CPU 使用率：compute.googleapis.com/instance/cpu/utilization

namespace: compute.googleapis.com

metric: instance/cpu/utilization

上图来源：Google Cloud 指标

1.2 资源类型¶

云监控指标可以描述为谷歌云 x 服务 x 种资源的 x 指标，其中 x 种资源就是资源类型（resource_type）

采集器配置并不需要指定资源类型，需要注意的是，上报到观测云的指标集（measurement）大多是以资源类型的格式命名 gcp_{resource_type}（有些资源类型也可能重命名）

Tip

指标的资源类型不是必须的，因为有的指标本身是服务级别的，并不特指资源层面，上报到观测云 measurement 就是 gcp_{service}，service 就是 namespace 的前缀部分：{service}.googleapis.com

2. 配置示例¶

指定特定指标¶

采集 Compute Engine 中名称为instance/cpu/utilization、guest/disk/io_time的 2 个指标

collector_configs = {
    'targets': [
        {
            'namespace': 'compute.googleapis.com',
            'metrics'  : [
              'instance/cpu/utilization',
              'guest/disk/bytes_used'
            ]
        }
    ]
}

通配符匹配指标¶

指标名可以使用*通配符来匹配。

本例中以下指标会被采集：

名称为instance/cpu/utilization的指标
名称以instance开头的指标
名称以cpu/utilization结尾的指标
名称中包含cpu的指标

collector_configs = {
    'targets': [
        {
            'namespace': 'compute.googleapis.com',
            'metrics'  : [
              'instance/cpu/utilization',
              'instance*',
              '*cpu/utilization',
              '*cpu*'
            ]
        }
    ]
}

剔除部分指标¶

在开头添加"NOT"标记表示去除后面的指标。

本例中，以下指标【不会】被采集：

名称为instance/cpu/utilization的指标
名称以instance开头的指标
名称以cpu/utilization结尾的指标
名称中包含cpu的指标

collector_configs = {
    'targets': [
        {
            'namespace': 'compute.googleapis.com',
            'metrics'  : [
              'NOT',
              'instance/cpu/utilization',
              'instance*',
              '*cpu/utilization',
              '*cpu*'
            ]
        }
    ]
}

多重过滤指定所需指标¶

相同的命名空间可以指定多次，从上到下依次按照指标名进行过滤。

本例中，相当于对指标名进行了如下过滤步骤：

选择所有名称中包含cpu的指标
在上一步结果中，去除名称为cpu/utilization的指标

collector_configs = {
    'targets': [
        {
            'namespace': 'compute.googleapis.com',
            'metrics'  : ['*cpu*'],
        },
        {
            'namespace': 'compute.googleapis.com',
            'metrics'  : ['NOT', '*cpu/utilization'],
        }
    ]
}

配置过滤器（可选项）¶

本采集器脚本支持用户自定义过滤器，让用户通过上报数据的标签筛选出需要上报的数据。过滤器函数返回值为 True｜False

True：目标资源需要被采集。
False 目标资源不需要被采集

# 示例：开启过滤器，根据对象的 InstanceId，RegionId 属性过滤，配置格式如下：

def filter_instance(instance, namespace='compute.googleapis.com'):
    '''
    采集 instance_id 为 i-xxxxxa, i-xxxxxb 的指标
    '''
    # print(instance) # 首次使用可以考虑打印 instance 查看待过滤的数据结构
    instance_id = instance['tags'].get('instance_id')
    if instance_id in ['i-xxxxxa', 'i-xxxxxb']:
        return True
    return False

from integration_core__runner import Runner
import integration_alibabacloud_monitor__main as main

@DFF.API('GoogleCloud-Monitor Collection', timeout=300, fixed_crontab="* * * * *")
def run():
    Runner(main.DataCollector(account, collector_configs, filters=[filter_instance])).run()

Tip

过滤器是对已采集的数据做过滤，所以不会减少云监控 API 的调用次数

3. 数据上报格式¶

数据正常同步后，可以在观测云的「指标」中查看数据。

以如下采集器配置为例：

collector_configs = {
    'targets': [
        {
            'namespace': 'compute.googleapis.com',
            'metrics'  : ['instance/cpu/utilization'],
        }
    ]
}

上报的数据示例如下：

{
  "measurement": "gcp_gce_instance",
  "tags": {
    "instance_id": "i-xxxxx",
    "userId"    : "xxxxx"
  },
  "fields": {
    "instance_cpu_utilization": 1.23
  }
}

measurement：字段的定义参考「1.2 资源类型」章节。
tags：指标对应的维度，以及额外标签。
fields：中的指标就是 metrics 中配置的指标（上报前统一处理成小写字母，下划线拼接)

因为指标的获取都是实时数据，最新的值，所以省略时间戳（默认上报时间点的时间戳）

Tip

所有的指标值都会以 float 类型上报

4. 云监控调用次数说明¶

Google Cloud 云监控对部分 API 调用次数有免费额度限制，2025 年 10 月 1 日前：查询 API 每个计费账户免费额度 100 万次/月，超出部分按 $0.01 /千次收费，本采集器所使用的/v3/project/{project_id}/timeSeries 也在限制范围内：

通过查看任务执行日志，找到真实调用次数¶

采集器对任务每次执行结果所调用的 API 次数有统计，可以在日志中查看，例：

[2023-04-21 15:32:13.194] [+0ms] 第【1】个账号采集完毕，共执行【274 毫秒】，期间调用 API【2 次】
[2023-04-21 15:32:13.194] [+0ms] 详细调用如下：
[2023-04-21 15:32:13.194] [+0ms] -> monitoring.googleapis.com/v3/projects/{project_id}/metricDescriptors: 1 次
[2023-04-21 15:32:13.194] [+0ms] -> monitoring.googleapis.com/v3/project/{project_id}/timeSeries: 1 次

Tip

2025 年 10 月 2 日后计费方式将不再按照 API 的调用次数收费，每个结算账号前 100 万个时序免费，超过后每 100 万个时序收取 0.50 $，详情参考：Google Cloud Observability 定价

!!! warning "鉴于云监控调用次数有免费额度，建议用户选择监控项时按需配置，避免通配造成额外消费"

X. 附录¶

参考官方文档：