Collector 'AWS-CloudWatch' Configuration Manual¶

Before reading this document, please read:

• Cloud Integration

1. Configuration Structure¶

The configuration structure of this collector is as follows:

2. Configuration Examples¶

Specifying Specific Metrics¶

Collect the two metrics CPUCreditBalance and MetadataNoToken with the dimension InstanceId in AWS/EC2.

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

Wildcard Matching Metrics¶

Metric names can be matched using the * wildcard.

In this example, the following metrics will be collected:

• Metrics with the dimension InstanceId

• Metrics with the name CPUCreditBalance

• Metrics with names starting with CPU

• Metrics with names ending with Balance

• Metrics with names containing Credit

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

Excluding Specific Metrics¶

Adding the "NOT" tag at the beginning indicates that the following metrics should be excluded.

In this example, the following metrics will [not] be collected:

• Metrics with the dimension InstanceId

• Metrics with the name CPUCreditBalance

• Metrics with names starting with CPU

• Metrics with names ending with Balance

• Metrics with names containing Credit

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

Multiple Filters to Specify Required Metrics¶

The same namespace can be specified multiple times, and the metric names will be filtered sequentially from top to bottom.

In this example, the metric names are filtered through the following steps:

1. All metrics with names containing CPU under the dimension InstanceId

2. In the results from the previous step, exclude the metric with the name CPUUtilization

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

Configuring Filters (Optional)¶

This collector script supports custom filters, allowing users to filter target resources based on object attributes. The filter function returns True｜False

• True: The target resource should be collected.
• False: The target resource should not be collected.

Supported object attributes for filtering:

When custom object collection is enabled, more object attributes can be filtered. For details, refer to the corresponding product's custom object collector documentation (coming soon...)

# Example: Enabling a filter to filter based on the RegionId and InstanceId attributes of an object. The configuration format is as follows:

def filter_instance(instance, namespace='AWS/EC2'):
    '''
    Collect metrics for InstanceId i-0d7620xxxxxxxa, i-0d7620xxxxxxxb and 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 integration_core__runner import Runner
import integration_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()

3. Data Collection Description¶

Cloud Product Configuration Information¶

4. Data Reporting Format¶

After data is successfully synchronized, you can view the data in the "Metrics" section of Guance.

Take the following collector configuration as an example:

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

The reported data example is as follows:

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

5. Integration with Custom Object Collectors¶

When other custom object collectors (e.g., EC2) are running in the same DataFlux Func, this collector will collect based on the dimensions specified in Data Collection Description. For example, fields like tags.InstanceId will attempt to match the tags.name field in custom objects.

Instance-level metrics are automatically supplemented. For an explanation of instance-level metrics, refer to Data Collection Description.

Since custom object information needs to be known before integration can occur in the CloudWatch collector, it is generally recommended to place the CloudWatch collector at the end of the list, such as:

# Create collectors
collectors = [
    aws_ec2.DataCollector(account, common_aws_configs),
    aws_cloudwatch.DataCollector(account, aws_cloudwatch_configs) # The CloudWatch collector is usually placed at the end
]

When a successful match is made, additional fields from the custom object's tags will be added to the CloudWatch data's tags, enabling effects such as filtering CloudWatch metric data using instance names. The specific effect is as follows:

Assume the original data collected by CloudWatch is as follows:

{
  "measurement": "aws_AWS/EC2",
  "tags": {
    "Dimensions": "InstanceId",
    "InstanceId": "i-xxx"
  },
  "fields": { "Content omitted" }
},

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

{
  "measurement": "aws_ec2",
  "tags": {
    "InstanceType"   : "c6g.xxx",
    "PlatformDetails": "xxx",
    "{key}"     : "{value}"
  },
  "fields": { "Content omitted" }
}

Then, the final reported CloudWatch data is as follows:

{
  "measurement": "aws_AWS/EC2",
  "tags": {
    "InstanceId"          : "i-xxx",   // Original field from CloudWatch
    "Dimensions"      : "InstanceId", // Dimension information field
    "InstanceType"    : "c6g.xxx", // Field from custom object EC2
    "PlatformDetails" : "xxx",     // Field from custom object EC2
    "{key}"      : "{value}"
  },
  "fields": { "Content omitted" }
},

6. Cloud Monitoring API Call Count Explanation¶

AWS CloudWatch has a free tier limit on the number of API calls for some APIs (currently: 1 million API calls per month for query APIs, with additional charges for exceeding this limit. Refer to Amazon (Global) CloudWatch Pricing, Amazon (China) CloudWatch Pricing). The APIs used by this collector, GetMetricStatistics and ListMetrics, are also within this limit. Below is a detailed explanation of the script's API call count:

1. The user has multiple resources and needs to collect multiple monitoring items. How to determine if the free tier limit will be exceeded:

This collector uses ListMetrics (lists available metrics) and GetMetricStatistics (retrieves aggregated information for a specified metric, each request can only retrieve one metric for one resource) to illustrate the number of requests:

• If there is 1 EC2 resource in the account and 1 monitoring item CPUUtilization needs to be collected, 2 requests are required (ListMetrics 1 time, GetMetricStatistics 1 time);
• If there are 2 EC2 resources in the account and 2 monitoring items CPUUtilization and DiskReadBPS need to be collected, 5 requests are required (ListMetrics 1 time, GetMetricStatistics 4 times);

2. View the actual number of API calls by checking the task execution logs:

The collector counts the number of API calls for each task execution result, which can be viewed in the logs. For example:

[2023-04-21 15:32:13.194] [+0ms] The [1] account collection is complete, taking [274 milliseconds], with [2] API calls
[2023-04-21 15:32:13.194] [+0ms] Detailed calls are as follows:
[2023-04-21 15:32:13.194] [+0ms] -> monitoring.cn-northwest-1.amazonaws.com.cn/?Action=ListMetrics: 1 time
[2023-04-21 15:32:13.194] [+0ms] -> monitoring.cn-northwest-1.amazonaws.com.cn/?Action=GetMetricStatistics: 1 time

!!! warning "Given the free tier limit on cloud monitoring API calls, it is recommended that users configure monitoring items as needed to avoid additional costs caused by wildcard matching"

7. IAM Policy Permissions¶

This collector requires the following operation permissions:

cloudwatch:GetMetricStatistics

cloudwatch:ListMetrics

Notes¶

Task Execution Errors and Solutions¶

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

Reason: The task execution time is too long, causing a timeout.

Solution:

• Appropriately increase the timeout setting for the task (e.g., @DFF.API('Execute Collection', timeout=120, fixed_crontab="* * * * *"), which sets the timeout time in the task to 120 seconds).

• About CloudWatch Agent Collecting Metrics from Amazon EC2 Instances and On-Premises Servers

Reason: The agent collects metrics from Amazon EC2 instances and on-premises servers.

Solution: - https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html

X. Appendix¶

AWS CloudWatch¶

Please refer to the official AWS documentation:

• Regions and Availability Zones
• S3 Using Amazon CloudWatch Monitoring Metrics
• AWS Services in CloudWatch Namespaces
• CloudWatch Viewing Available Metrics and Dimensions
• Amazon ElastiCache for Memcached Host-Level Metrics Monitoring
• Amazon ElastiCache for Redis Host-Level Metrics Monitoring
• Amazon (Global) CloudWatch Pricing
• Amazon (China) CloudWatch Pricing