Collector "AWS-CloudWatchLogs" Configuration Manual¶

Before reading this document, please read:

Cloud Integration

Tip

Before using this collector, you must install the "Integration Core Package" and its accompanying third-party dependencies.

1. Configuration Structure¶

The configuration structure of this collector is as follows:

Field	Type	Required	Description
`region_id`	str	Required	Region ID such as: `'cn-north-1'`
`targets`	list	Required	CloudWatchLogs target configuration list The logical relationship between multiple configurations of the same log group is "AND"
`targets[#].log_group_name`	str	Required	The CloudWatch namespace to be collected. For example: `'AWS/EC2'` See the appendix for the complete list
`targets[#].log_streams`	list	Required	The list of CloudWatch log streams to be collected
`targets[#].log_streams[#]`	str	Required	Log stream name pattern, supports `"NOT"`, wildcard matching Normally, the logical relationship between multiple is "OR". When `"NOT"` is included, the logical relationship between multiple is "AND". See below for details

2. Configuration Examples¶

Specify Specific Log Stream¶

Collect the log stream named database-1 in /aws/rds/instance/database-1/slowquery

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

Collect All Log Streams¶

Collect all log streams under the /aws/rds/instance/database-1/slowquery log group

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

Wildcard Matching Log Streams¶

Log stream names can be matched using the * wildcard.

In this example, the following log streams will be collected:

Log stream named test
Log stream names starting with database
Log stream names ending with query
Log stream names containing slow

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

Exclude Some Log Streams¶

Adding "NOT" at the beginning indicates to exclude the following log streams.

In this example, the following log streams will not be collected:

Log stream named test
Log stream names starting with database
Log stream names ending with query
Log stream names containing slow

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

Multiple Filters to Specify Required Log Streams¶

The same log group can be specified multiple times, filtering log stream names sequentially from top to bottom.

In this example, the log stream names are filtered as follows:

Select all log stream names containing database
In the previous result, remove the log stream named 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. Data Reporting Format¶

After data is synchronized normally, you can view the data in the "Logs" section of TrueWatch.

Take the following collector configuration as an example:

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

The reported data example is as follows:

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

Note

The fields in tags and fields may change with subsequent updates

Tip

The value of tags.name is the instance ID, which serves as a unique identifier, and fields.message is a JSON serialized string

4. Integration with Custom Object Collector¶

Currently, only RDS custom object supplementation is supported. This collector will obtain the DBInstanceIdentifier field based on the log group name and attempt to match the tags.DBInstanceIdentifier field in the custom object.

When a match is successful, additional fields from the custom object tags will be added to the CloudWatchlogs data tags. The specific effect is as follows:

Assume the original data collected by CloudWatchlogs is as follows:

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

At the same time, the custom object data collected by the AWS RDS collector is as follows:

{
  "measurement": "aws_rds",
  "tags": {
    "DBInstanceIdentifier": "database-1",
    "DBInstanceClass"     : "xxx",
    "{key}"          : "{value}"
  },
  "fields": {
    "{key}": "{value}"
  }
}

Then, the final reported CloudWatchlogs data will be as follows:

{
  "measurement": "aws_cloudwatch_logs_/aws/rds/instance/database-1/slowquery",
  "tags": {
    "logStreamName"       : "database-1",     // Original field from CloudWatchlogs
    "DBInstanceIdentifier": "database-1",     // Field from custom object RDS
    "DBInstanceClass"     : "xxx",            // Field from custom object RDS
    "{key}"          : "{value}"
  },
  "fields": {
    "{key}": "{value}"
  }
}

6. IAM Policy Permissions¶

Note

If users use the method of bringing in IAM roles to collect resources, certain operation permissions need to be enabled

This collector requires the following operation permissions:

logs:DescribeLogStreams

logs:FilterLogEvents

X. Appendix¶

AWS CloudWatchLogs¶

Please refer to the official AWS documentation:

Logs Publishing to CloudWatchLogs