采集器「AWS-CloudWatch」配置手册

阅读本文前，请先阅读：

• 观测云集成 / 基本操作

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

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

1. 配置结构

本采集器配置结构如下：

字段	类型	是否必须	说明
Regions	List	必须	所需采集的 CloudWatch 地域列表
regions[#]	str	必须	地域 ID 如：'cn-northwest-1' 总表见附录
targets	list	必须	CloudWatch 采集对象配置列表 相同命名空间的多个配置之间逻辑关系为「且」
targets[#].namespace	str	必须	所需采集的 CloudWatch 命名空间。如：'AWS/EC2'总表见附录
targets[#].dimensions	str	非必须	所需采集的 CloudWatch 维度名称列表。此配置为新增配置，指定所采集指标的维度 总表见附录
targets[#].metrics	list	必须	所需采集的 CloudWatch 指标名列表 总表见附录）
targets[#].metrics[#]	str	必须	指标名模式，支持"NOT"、通配符方式匹配 正常情况下，多个之间逻辑关系为「或」 包含"NOT"标记时，多个之间逻辑关系为「且」。 详见下文

2. 配置示例

指定特定指标

采集AWS/EC2中维度为 InstanceId、名称为CPUCreditBalance、MetadataNoToken的 2 个指标

aws_cloudwatch_configs = {
    'regions': ['cn-northwest-1'],
    'targets': [
        {
            'namespace' : 'AWS/EC2',
            'dimensions': ['InstanceId'],
            'metrics'   : ['CPUCreditBalance', 'MetadataNoToken'],
        }
    ],
}

通配符匹配指标

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

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

• 维度为InstanceId的以下指标

• 名称为CPUCreditBalance的指标

• 名称以CPU开头的指标

• 名称以Balance结尾的指标

• 名称中包含Credit的指标

aws_cloudwatch_configs = {
    'regions': ['cn-northwest-1'],
    'targets': [
        {
            'namespace' : 'AWS/EC2',
            'dimensions': ['InstanceId'],
            'metrics'   : ['CPUCreditBalance', 'CPU*', '*Balance', '*Credit*'],
        }
    ],
}

剔除部分指标

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

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

• 维度为InstanceId的以下指标

• 名称为CPUCreditBalance的指标

• 名称以CPU开头的指标

• 名称以Balance结尾的指标

• 名称中包含Credit的指标

aws_cloudwatch_configs = {
    'regions': ['cn-northwest-1'],
    'targets': [
        {
            'namespace' : 'AWS/EC2',
            'dimensions': ['InstanceId'],
            'metrics'   : ['NOT', 'CPUCreditBalance', 'CPU*', '*Balance', '*Credit*'],
        }
    ],
}

多重过滤指定所需指标

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

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

1. 维度为 InstanceId下的所有名称中包含CPU的指标

2. 在上一步结果中，去除名称为CPUUtilization的指标

aws_cloudwatch_configs = {
    'regions': ['cn-northwest-1'],
    'targets': [
        {
            'namespace' : 'AWS/EC2',
            'dimensions': ['InstanceId'],
            'metrics'   : ['*CPU*'],
        },
        {
            'namespace' : 'AWS/EC2',
            'dimensions': ['InstanceId'],
            'metrics'   : ['NOT', 'CPUCreditBalance'],
        },
    ],
}

配置过滤器（可选项）

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

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

支持筛选的对象属性：

产品名称	支持属性
Elastic Compute Cloud (EC2)	InstanceId
Relational Database Service (RDS)	DBInstanceIdentifier

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

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

def filter_instance(instance, namespace='AWS/EC2'):
    '''
    采集 InstanceId 为 i-0d7620xxxxxxxa, i-0d7620xxxxxxxb 且 RegionId 为 cn-northwest-1 的指标
    '''
    region_id = instance['tags'].get('RegionId')
    instance_id = instance['tags'].get('InstanceId')

    if instance_id in ['i-0d7620xxxxxxxa', 'i-0d7620xxxxxxxb'] and region_id in ['cn-northwest-1']:
        return True
    return False

from guance_integration__runner import Runner
import guance_aws_cloudwatch__main as main

@DFF.API('AWS-CloudWatch Collection', timeout=3600, fixed_crontab='*/15 * * * *')
def run():
    Runner(main.DataCollector(account, collector_configs, filters=[filter_instance])).run()

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

3. 数据采集说明

云产品配置信息

产品名称	命名空间 (Namespace)	维度 (Dimension)	说明
Amazon EC2	AWS/EC2	InstanceId
Amazon RDS	AWS/RDS	DBInstanceIdentifier
Amazon S3	AWS/S3	*	*表示采集该命名空间的所有维度，下同 S3 中请求指标需要用户在控制台手动配置，详情见附件
Amazon OpenSearch Service	AWS/ES	*	同上
Elastic Load Balancing	AWS/ELB	LoadBalancerName
Elastic Load Balancing	AWS/NetworkELB AWS/GatewayELB AWS/ApplicationELB	LoadBalancer	按负载均衡器筛选指标数据。按以下方式指定负载均衡器：net/load-balancer-name/1234567890123456 （负载均衡器 ARN 的结尾部分）。
Amazon ElastiCache for Memcached	AWS/ElastiCache	CacheClusterId	采集器目前采集主机级指标，详情见附录（Amazon ElastiCache for Memcached 主机级指标监控）
Amazon ElastiCache for Redis	AWS/ElastiCache	CacheClusterId	采集器目前采集主机级指标，详情见附录（Amazon ElastiCache for Redis 主机级指标监控）

4. 数据上报格式

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

以如下采集器配置为例：

aws_cloudwatch_configs = {
    'regions': ['cn-northwest-1'],
    'targets': [
        {
            'namespace' : 'AWS/EC2',
            'dimensions': ['InstanceId'],
            'metrics'   : ['CPUCreditBalance'],
        },
    ],
}

上报的数据示例如下：

{
  "measurement": "aws_AWS/EC2",
  "tags": {
    "Dimensions": "InstanceId",
    "InstanceId": "i-xxx"
  },
  "fields": {
    "CPUCreditBalance_Average"    : 576.0,
    "CPUCreditBalance_Maximum"    : 576.0,
    "CPUCreditBalance_Minimum"    : 576.0,
    "CPUCreditBalance_SampleCount": 1.0,
    "CPUCreditBalance_Sum"        : 576.0
  }
}

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

本采集器采集了 AWS/EC2 命名空间中 InstanceId 维度的数据，详情见 数据采集说明

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

当同一个 DataFlux Func 中运行了其他自定义对象采集器（如： EC2 ）时，本采集器会根据 数据采集说明中指出的维度采集。例如tags.InstanceId等字段尝试匹配自定义对象中的tags.name字段。

实例维度的指标自动补充，关于实例维度解释，请参考 数据采集说明

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

# 创建采集器
collectors = [
    aws_ec2.DataCollector(account, common_aws_configs),
    aws_cloudwatch.DataCollector(account, aws_cloudwatch_configs) # CloudWatch 采集器一般放在最末尾
]

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

假设 CloudWatch 采集到的原始数据如下：

{
  "measurement": "aws_AWS/EC2",
  "tags": {
    "Dimensions": "InstanceId",
    "InstanceId": "i-xxx"
  },
  "fields": { "内容略" }
},

同时，AWS EC2 采集器采集到的自定义对象数据如下：

{
  "measurement": "aws_ec2",
  "tags": {
    "InstanceType"   : "c6g.xxx",
    "PlatformDetails": "xxx",
    "{其他字段}"     : "{略}"
  },
  "fields": { "内容略" }
}

那么，最终上报的 CloudWatch 数据如下：

{
  "measurement": "aws_AWS/EC2",
  "tags": {
    "InstanceId"          : "i-xxx",   // CloudWatch 原始字段
    "Dimensions"      : "InstanceId", // 维度信息字段
    "InstanceType"    : "c6g.xxx", // 来自自定义对象 EC2 的字段
    "PlatformDetails" : "xxx",     // 来自自定义对象 EC2 的字段
    "{其他字段}"      : "{略}"
  },
  "fields": { "内容略" }
},

6. 云监控调用次数说明

AWS cloudwatch 对部分 API 调用次数有免费额度限制（目前：查询 API 免费额度 100 万次/月，超出部分参考 Amazon （全球区） CloudWatch 定价、Amazon （中国区） CloudWatch 定价，本采集器所使用的 GetMetricStatistics、ListMetrics 也在限制范围内，以下对脚本集调用次数做出详细解释：

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

本采集器使用 ListMetrics（列出可用的指标）、GetMetricStatistics（获取指定指标的聚合信息，每次请求只能获取某一个资源的某一个指标）请求次数举例说明：

• 账号下有 1 个 ec2 资源需要采集 CPUUtilization 1 个监控项，需要 2 次请求（ListMetrics 1 次，GetMetricStatistics 1 次）；
• 账号下有 2 个 ec2 资源需要采集 CPUUtilization、DiskReadBPS 2 个监控项，需要 5 次请求（ListMetrics 1 次，GetMetricStatistics 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] -> monitoring.cn-northwest-1.amazonaws.com.cn/?Action=ListMetrics: 1 次
[2023-04-21 15:32:13.194] [+0ms] -> monitoring.cn-northwest-1.amazonaws.com.cn/?Action=GetMetricStatistics: 1 次

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

7. IAM 策略权限

如果用户使用带入 IAM 角色的方式采集资源，需要开启一定的操作权限

该采集器需要如下操作权限：

cloudwatch:GetMetricStatistics

cloudwatch:ListMetrics

注意事项

触发任务抛错情况以及解决方法

1. HTTPClientError: An HTTP Client raised an unhandled exception: SoftTimeLimitExceeded()

原因：任务执行时间过长 timeout。

解决方法：

• 适当加大对任务的 timeout 设置（如：@DFF.API('执行采集', timeout=120, fixed_crontab="* * * * *")，表示将任务中的超时时间设置成 120 秒）。

• 关于 CloudWatch 代理从 Amazon EC2 实例和本地服务器中收集的指标

原因：代理从 Amazon EC2 实例和本地服务器中收集的指标

解决方法： - https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html

X. 附录

AWS CloudWatch

请参考 AWS 官方文档：

• 区域和可用区
• S3 使用 Amazon CloudWatch 监控指标
• AWS 服务在 CloudWatch 中的命名空间
• CloudWatch 查看可用的指标及维度
• Amazon ElastiCache for Memcached 主机级指标监控
• Amazon ElastiCache for Redis 主机级指标监控
• Amazon （全球区） CloudWatch 定价
• Amazon （中国区） CloudWatch 定价