采集器「阿里云-云监控」配置手册

阅读本文前，请先阅读：

• 观测云集成 / 基本操作

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

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

1. 配置结构

本采集器配置结构如下：

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

2. 配置示例

指定特定指标

采集 ECS 中名称为CPUUtilization、concurrentConnections的 2 个指标

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard',
            'metrics'  : ['CPUUtilization', 'concurrentConnections'],
        },
    ],
}

通配符匹配指标

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

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

• 名称为CPUUtilization的指标
• 名称以CPU开头的指标
• 名称以Connections结尾的指标
• 名称中包含Conn的指标

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard',
            'metrics'  : ['CPUUtilization', 'CPU*', '*Connections', '*Conn*'],
        },
    ],
}

剔除部分指标

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

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

• 名称为CPUUtilization的指标
• 名称以CPU开头的指标
• 名称以Connections结尾的指标
• 名称中包含Conn的指标

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard',
            'metrics'  : ['NOT', 'CPUUtilization', 'CPU*', '*Connections', '*Conn*'],
        },
    ],
}

多重过滤指定所需指标

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

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

1. 选择所有名称中包含CPU的指标
2. 在上一步结果中，去除名称为CPUUtilization的指标

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard',
            'metrics'  : ['*CPU*'],
        },
        {
            'namespace': 'acs_ecs_dashboard',
            'metrics'  : ['NOT', 'CPUUtilization'],
        },
    ],
}

配置过滤器（可选项）

本采集器脚本支持用户自定义过滤器，让用户通过对象属性筛选出目标资源。过滤器函数返回值为 True｜False

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

支持筛选的对象属性：

产品名称	支持属性
云资产(对象数据)/云服务器 ECS	instanceId、userId
云资产(对象数据)/数据库和存储/云数据库 RDS	instanceId、userId
云资产(对象数据)/负载均衡 SLB	instanceId、userId
云资产(对象数据)/数据库和存储/对象存储 OSS	BucketName、userId

当开启自定义对象采集时，将支持筛选更多的对象属性，详情请参考对应产品的自定义对象采集器文档（支持中...）

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

def filter_instance(instance, namespace='acs_ecs_dashboard'):
    '''
    采集 InstanceId 为 i-xxxxxa, i-xxxxxb 且 RegionId 为 cn-hangzhou 的指标
    '''
    instance_id = instance['tags'].get('InstanceId')
    region_id = instance['tags'].get('RegionId')
    if instance_id in ['i-xxxxxa', 'i-xxxxxb'] and region_id in ['cn-hangzhou']:
        return True
    return False

from guance_integration__runner import Runner
import guance_aliyun_monitor__main as main

@DFF.API('AlibabaCloud-monitor ', timeout=3600, fixed_crontab="*/5 * * * *")
def run():
    Runner(main.DataCollector(account, collector_configs, filters=[filter_instance])).run()

相同 namespace 下配置多个过滤器时同时满足所有过滤器才会上报

3. 数据上报格式

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

以如下采集器配置为例：

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard',
            'metrics'  : ['CPUUtilization'],
        },
    ],
}

上报的数据示例如下：

{
  "measurement": "aliyun_acs_ecs_dashboard",
  "tags": {
    "instanceId": "i-xxxxx",
    "userId"    : "xxxxx"
  },
  "fields": {
    "CPUUtilization_Average": 1.23,
    "CPUUtilization_Maximum": 1.23,
    "CPUUtilization_Minimum": 1.23
  }
}

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

4. 与自定义对象采集器联动

当同一个 DataFlux Func 中运行了其他自定义对象采集器（如 ECS、RDS）时，本采集器会自动根据tags.instanceId等字段尝试匹配自定义对象中的tags.name字段。

由于需要先获知自定义对象信息才能在云监控类采集器中进行联动，因此一般建议将云监控的采集器放置在列表末尾，如：

    # 创建采集器
    collectors = [
        aliyun_ecs.DataCollector(account, common_aliyun_configs),
        aliyun_rds.DataCollector(account, common_aliyun_configs),
        aliyun_slb.DataCollector(account, common_aliyun_configs),
        aliyun_oss.DataCollector(account, common_aliyun_configs),
        aliyun_monitor.DataCollector(account, monitor_collector_configs), # 云监控类采集器一般放在最末尾
    ]

当成功匹配后，会将所匹配的自定义对象tags中除name以外的字段加入到监控数据的tags中，以此实现在使用实例名称筛选云监控的指标数据等效果。具体效果如下：

假设云监控采集到的原始数据如下：

{
  "measurement": "aliyun_acs_ecs_dashboard",
  "tags": {
    "instanceId": "i-001",
    "{其他字段}": "{略}"
  },
  "fields": {
    "{指标}": "{指标值}"
  }
}

同时，阿里云 ECS 采集器采集到的自定义对象数据如下：

{
  "measurement": "aliyun_ecs",
  "tags": {
    "name"      : "i-001",
    "InstanceId": "i-001",
    "RegionId"  : "cn-hangzhou",
    "{其他字段}": "{略}"
  },
  "fields": {
    "{其他字段}": "{略}"
  }
}

那么，最终上报的云监控数据如下：

{
"measurement": "aliyun_acs_ecs_dashboard",
  "tags": {
    "instanceId": "i-001",
    "RegionId"  : "cn-hangzhou",
    "{其他字段}": "{略}"
  },
  "fields": {
    "{指标}": "{指标值}"
  }
}

5. 云监控调用次数说明

阿里云云监控对部分 API 调用次数有免费额度限制（目前：查询 API 免费额度 100 万次/月，超出部分按 0.12 元/万次收费），本采集器所使用的 DescribeMetricLast 也在限制范围内，以下对脚本集调用次数做出详细解释：

1. 用户有多个资源，需要采集多种监控项，判断会不会超过免费额度：

本采集器使用 DescribeMetricLast（查询指定监控项的最新监控数据）一次请求能获取多个（最多 1000，超过则翻页获取） 资源的某一项监控项。请求次数举例说明：

• 账号下有 1000 个 ecs 资源需要采集 CPUUtilization 1 个监控项，需要 1 次请求；
• 账号下有 1000 个 ecs 资源需要采集 CPUUtilization、DiskReadBPS 2 个监控项，需要 2 次请求（每个监控项请求一次）；
• 账号下有 1001 个 ecs 资源需要采集 CPUUtilization 一个监控项，需要 2 次请求（资源超过 1000 翻页获取）；
• 账号下有 1001 个 ecs 资源需要采集 CPUUtilization、DiskReadBPS 2 个监控项，需要 4 次请求；

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

采集器对任务每次执行结果所调用的 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] -> metrics.aliyuncs.com/?Action=DescribeMetricMetaList: 1 次
[2023-04-21 15:32:13.194] [+0ms] -> metrics.aliyuncs.com/?Action=DescribeMetricLast: 1 次

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

注意事项

常见错误及解决办法

1. 采集实例数量与实际存在实例数量不一致

原因：实例状态为关机状态

解决方法：

• 开启实例。

X. 附录

请参考阿里云官方文档：

• 云监控 / 附录 1 云服务监控项 / 概览
• 云监控指标查询
• 基础云监控 / 免费额度
• 基础云监控 / 按量计费