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

阅读本文前，请先阅读：

• 观测云集成 / 基本操作

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

1. 配置结构

本采集器配置结构如下：

字段	类型	是否必须	说明
region_id	str	必须	地域 ID 如：'cn-north-1'
targets	list	必须	CloudWatchLogs 采集对象配置列表 相同日志组的多个配置之间逻辑关系为「且」
targets[#].log_group_name	str	必须	所需采集的 CloudWatch 命名空间。如：'AWS/EC2' 总表见附录
targets[#].log_streams	list	必须	所需采集的 CloudWatch 日志流列表
targets[#].log_streams[#]	str	必须	日志流名字模式，支持 "NOT"、通配符方式匹配 正常情况下，多个之间逻辑关系为「或」 包含 "NOT" 标记时，多个之间逻辑关系为「且」。 详见下文

2. 配置示例

指定特定日志流

采集 /aws/rds/instance/database-1/slowquery 中名称为 database-1 的日志流

config = [{
  'region_id': 'cn-north-1',
  'targets': [
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['database-1']
      }
    ]
  }
]

获取全部日志流

采集 /aws/rds/instance/database-1/slowquery 日志组下的所有日志流

config = [{
  'region_id': 'cn-north-1',
  'targets': [
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['ALL']
      }
    ]
  }
]

通配符匹配日志流

日志流名字可以使用 * 通配符来匹配。

本例中以下日志流会被采集：

• 名称为 test 的日志流名称

• 名称以 database 开头的日志流名称

• 名称以 query 结尾的日志流名称

• 名称中包含 slow 的日志流名称

config = [{
  'region_id': 'cn-north-1',
  'targets': [
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['test', 'database*', '*query', '*slow*'],
      }
    ]
  }
]

剔除部分日志流

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

本例中以下日志流【不会】被采集：

• 名称为 test 的日志流名称

• 名称以 database 开头的日志流名称

• 名称以 query 结尾的日志流名称

• 名称中包含 slow 的日志流名称

config = [{
  'region_id': 'cn-north-1',
  'targets': [
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['NOT', 'test', 'database*', '*query', '*slow*'],
      }
    ]
  }
]

多重过滤指定所需日志流

相同的日志组可以指定多次，从上到下依次按照日志流名字进行过滤。

本例中，相当于对日志流名字进行了如下过滤步骤：

1. 选择所有名称中包含 database 的日志流

2. 在上一步结果中，去除名称为 database-2 的日志流

config = [{
  'region_id': 'cn-north-1',
  'targets': [
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['*database*'],
      },
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['NOT', 'database-2'],
      }
    ]
  }
]

3. 数据上报格式

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

以如下采集器配置为例：

config = [{
  'region_id': 'cn-north-1',
  'targets': [
      {
        'log_group_name': '/aws/rds/instance/database-1/slowquery',
        'log_streams'   : ['database-1']
      }
    ]
  }
]

上报的数据示例如下：

{
  "measurement": "aws_cloudwatch_logs_/aws/rds/instance/database-1/slowquery",
  "tags": {
    "logStreamName"       : "database-1",
    "errorCode"           : "InvalidRequestException",
    "accessKeyId"         : "xxx",
    "userIdentityUserName": "xxx"
  },
  "fields": {
    "message"     : "# Time: 2023-02-28T02:37:44.959003Z\n# User@Host: root[root] @  [xxx.xxx.xxx.xxx]  Id:     9\n# Query_time: 1.995580  Lock_time: 0.000002 Rows_sent: 100000  Rows_examined: 100000\nuse aa;\nSET timestamp=1677551862;\nselect * from t1 limit 100000;",
    "timestamp"   : 1677551864959,
    "errorMessage": "DataCatalog AwsDataCatalog was not found"
  }
}

tags、fields 中的字段可能会随后续更新有所变动

tags.name 值为实例 ID，作为唯一标识，fields.message 为 JSON 序列化后字符串

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

目前只支持 RDS 自定义对象补充 本采集器会根据日志组名称获取到 DBInstanceIdentifier 字段 ,字段尝试匹配自定义对象中的 tags.DBInstanceIdentifier 字段。

当成功匹配后，会将所匹配的自定义对象 tags 中额外的字段加入到 CloudWatchlogs 数据的 tags 中，具体效果如下：

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

{
  "measurement": "aws_cloudwatch_logs_/aws/rds/instance/database-1/slowquery",
  "tags": {
    "logStreamName"       : "database-1",
    "errorCode"           : "InvalidRequestException",
    "accessKeyId"         : "xxx",
    "userIdentityUserName": "xxx"
  },
  "fields": {
    "message"     : "# Time: 2023-02-28T02:37:44.959003Z\n# User@Host: root[root] @  [xxx.xxx.xxx.xxx]  Id:     9\n# Query_time: 1.995580  Lock_time: 0.000002 Rows_sent: 100000  Rows_examined: 100000\nuse aa;\nSET timestamp=1677551862;\nselect * from t1 limit 100000;",
    "timestamp"   : 1677551864959,
    "errorMessage": "DataCatalog AwsDataCatalog was not found"
  }
}

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

{
  "measurement": "aws_rds",
  "tags": {
    "DBInstanceIdentifier": "database-1",
    "DBInstanceClass"     : "xxx",
    "{其他字段}"          : "{略}"
  },
  "fields": {
    "{其他字段}": "{略}"
  }
}

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

{
  "measurement": "aws_cloudwatch_logs_/aws/rds/instance/database-1/slowquery",
  "tags": {
    "logStreamName"       : "database-1",     // CloudWatchlogs 原始字段
    "DBInstanceIdentifier": "database-1",     // 来自自定义对象 RDS 的字段
    "DBInstanceClass"     : "xxx",            // 来自自定义对象 RDS 的字段
    "{其他字段}"          : "{略}"
  },
  "fields": {
    "{其他字段}": "{略}"
  }
}

6.IAM 策略权限

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

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

logs:DescribeLogStreams

logs:FilterLogEvents

X. 附录

AWS CloudWatchLogs

请参考 AWS 官方文档：

• 日志发布到 CloudWatchLogs