AWS module

This module periodically fetches monitoring metrics from AWS CloudWatch using GetMetricData API for AWS services.

All metrics are enabled by default.

The aws module requires AWS credentials configuration in order to make AWS API calls. Users can either use AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and/or AWS_SESSION_TOKEN, or use shared AWS credentials file. Please see AWS credentials options for more details.

This module also accepts optional configuration regions to specify which AWS regions to query metrics from. If the regions parameter is not set in the config file, then by default, the aws module will query metrics from all available AWS regions. If endpoint is specified, regions becomes a required config parameter.

Some AWS services send monitoring metrics to CloudWatch with a latency to process larger than Metricbeat collection period. This will cause data points missing or none get collected by Metricbeat. In this case, please specify a latency parameter so collection start time and end time will be shifted by the given latency amount.

Most AWS services offer a regional endpoint that can be used to make requests. The general syntax of a regional endpoint is protocol://service-code.region-code.endpoint-code. Some services, such as IAM, do not support regions. The endpoints for these services do not include a region. In aws module, endpoint config is to set the endpoint-code part, such as amazonaws.com, amazonaws.com.cn, c2s.ic.gov, sc2s.sgov.gov.

If endpoint is specified, regions config becomes required. For example:

- module: aws
  period: 5m
  endpoint: amazonaws.com.cn
  regions: cn-north-1
  metricsets:
    - ec2

The aws module comes with a predefined dashboard. For example:

Currently, we have billing, cloudwatch, dynamodb, ebs, ec2, elb, lambda, natgateway, rds, s3_daily_storage, s3_request, sns, sqs, transitgateway, usage and vpn metricset in aws module.

Collecting tags for ec2, rds, cloudwatch, and metricset created based on cloudwatch using light module is supported.

Billing metric data includes the estimated charges for every service in the AWS account and the estimated overall total charge for the AWS account. The estimated charges are calculated and sent several times daily to CloudWatch. Therefore, period in aws module configuration is set to 12h.

The billing metricset comes with a predefined dashboard:

This metricset allows users to query metrics from AWS CloudWatch with any given namespaces or specific instance with a given period. Please see AWS Services That Publish CloudWatch Metrics for a list of AWS services that publish metrics to CloudWatch.

DynamoDB sends metrics to CloudWatch periodically for better monitoring how web application or service is performing.

The dynamodb metricset comes with a predefined dashboard:

For basic monitoring in AWS EBS volumes, data is available automatically in 5-minute periods at no charge. This includes data for the root device volumes for EBS-backed instances. User can also enable detailed monitoring for provisioned IOPS SSD (io1) volumes to automatically send one-minute metrics to CloudWatch. Default period in aws module configuration is set to 5m for ebs metricset.

The ebs metricset comes with a predefined dashboard:

By default, Amazon EC2 sends metric data to CloudWatch every 5 minutes. With this basic monitoring, period in aws module configuration should be larger or equal than 300s. If period is set to be less than 300s, the same cloudwatch metrics will be collected more than once which will cause extra fees without getting more granular metrics. For example, in US East (N. Virginia) region, it costs $0.01/1000 metrics requested using GetMetricData. Please see AWS CloudWatch Pricing for more details. To avoid unnecessary charges, period is preferred to be set to 300s or multiples of 300s, such as 600s and 900s. For more granular monitoring data you can enable detailed monitoring on the instance to get metrics every 1 minute. Please see Enabling Detailed Monitoring for instructions on how to enable detailed monitoring. With detailed monitoring enabled, period in aws module configuration can be any number larger than 60s. Since AWS sends metric data to CloudWatch in 1-minute periods, setting metricbeat module period less than 60s will cause extra API requests which means extra charges on AWS. To avoid unnecessary charges, period is preferred to be set to 60s or multiples of 60s, such as 120s and 180s.

The ec2 metricset comes with a predefined dashboard:

elb metricset collects CloudWatch metrics from classic load balancer, application load balancer and network load balancer.

All three kinds of elastic load balancing reports metrics to Cloudwatch only when requests are flowing through the load balancer. If there are requests flowing through the load balancer, Elastic Load Balancing measures and sends its metrics in 60-second intervals. If there are no requests flowing through the load balancer or no data for a metric, the metric is not reported. Therefore, period in aws module configuration is set to 1m.

The elb metricset comes with a predefined dashboard:

When an invocation completes, Lambda sends a set of metrics to CloudWatch for that invocation. Default period in aws module configuration is set to 5m for lambda metricset. The lambda metricset comes with a predefined dashboard:

CloudWatch collects information from NAT gateways and creates readable, near real-time metrics. This metricset enables users to collect these metrics from CloudWatch to monitor and troubleshoot their NAT gateway. NAT gateway metric data is provided at 1-minute intervals and therefore, period for natgateway metricset is recommended to be 1m or multiples of 1m.

period for rds metricset is recommended to be 60s or multiples of 60s because Amazon RDS sends metrics and dimensions to Amazon CloudWatch every minute.

The rds metricset comes with a predefined dashboard:

Daily storage metrics for S3 buckets are reported once per day with no additional cost. Since they are daily metrics, period for s3_daily_storage metricset is recommended to be 86400s or multiples of 86400s.

Request metrics are available at 1-minute intervals with additional charges. The s3_request metricset will give more granular data to track S3 bucket usage. The period for s3_request metricset can be set to 60s or multiples of 60s. But because of the extra charges for querying these metrics, the period is recommended to set to 86400s. The user can always adjust this to the granularity they want. Request metrics are not enabled by default for S3 buckets. Please see How to Configure Request Metrics for S3 for instructions on how to enable request metrics for each S3 bucket.

The s3_daily_storage and s3_request metricset comes with a predefined combined dashboard:

CloudWatch metrics for Amazon SQS queues are automatically collected and pushed to CloudWatch every 5 minutes, the period for sqs metricset is recommended to be 300s or multiples of 300s.

The sqs metricset comes with a predefined dashboard:

Amazon VPC reports metrics to CloudWatch only when requests are flowing through the transit gateway. If there are requests flowing through the transit gateway, Amazon VPC measures and sends its metrics in 60-second intervals. period for transitgateway metricset is recommended to be 1m or multiples of 1m.

CloudWatch collects metrics that track the usage of some AWS resources. These metrics correspond to AWS service quotas. Tracking these metrics can help proactively manage quotas. Service quota usage metrics are in the AWS/Usage namespace and are collected every minute. Therefore, period in aws module configuration for usage metricset is set to 1m.

The usage metricset comes with a predefined dashboard:

CloudWatch collects and processes raw data from the VPN service into readable, near real-time metrics for users to better understand the performance of their web applications and services.

This session is to document what are the AWS API called made by each metricset in aws module. This will be useful for users to estimate costs for using aws module.

Note: some AWS APIs need pagination like ListMetrics and GetMetricData. Count value is depends on the number of results.

ListMetrics max page size: 500, based on AWS API ListMetrics

GetMetricData max page size: 100, based on AWS API GetMetricData

billing, ebs, elb, sns, usage and lambda are the same as cloudwatch metricset.

To configure AWS credentials, either put the credentials into the Metricbeat configuration, or use a shared credentials file, as shown in the following examples.

Users can either put the credentials into the Metricbeat module configuration or use environment variable AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and/or AWS_SESSION_TOKEN instead.

If running on Docker, these environment variables should be added as a part of the docker command. For example, with Metricbeat:

$ docker run -e AWS_ACCESS_KEY_ID=abcd -e AWS_SECRET_ACCESS_KEY=abcd -d --name=metricbeat --user=root --volume="$(pwd)/metricbeat.aws.yml:/usr/share/metricbeat/metricbeat.yml:ro" docker.elastic.co/beats/metricbeat:7.11.1 metricbeat -e -E cloud.auth=elastic:1234 -E cloud.id=test-aws:1234

Sample metricbeat.aws.yml looks like:

metricbeat.modules:
- module: aws
  period: 5m
  access_key_id: ${AWS_ACCESS_KEY_ID}
  secret_access_key: ${AWS_SECRET_ACCESS_KEY}
  session_token: ${AWS_SESSION_TOKEN}
  metricsets:
    - ec2

Environment variables can also be added through a file. For example:

$ cat env.list
AWS_ACCESS_KEY_ID=abcd
AWS_SECRET_ACCESS_KEY=abcd

$ docker run --env-file env.list -d --name=metricbeat --user=root --volume="$(pwd)/metricbeat.aws.yml:/usr/share/metricbeat/metricbeat.yml:ro" docker.elastic.co/beats/metricbeat:7.11.1 metricbeat -e -E cloud.auth=elastic:1234 -E cloud.id=test-aws:1234

If access_key_id, secret_access_key and role_arn are all not given, then metricbeat will check for credential_profile_name. If you use different credentials for different tools or applications, you can use profiles to configure multiple access keys in the same configuration file. If there is no credential_profile_name given, the default profile will be used.

shared_credential_file is optional to specify the directory of your shared credentials file. If it’s empty, the default directory will be used. In Windows, shared credentials file is at C:\Users\<yourUserName>\.aws\credentials. For Linux, macOS or Unix, the file is located at ~/.aws/credentials. When running as a service, the home path depends on the user that manages the service, so the shared_credential_file parameter can be used to avoid ambiguity. Please see Create Shared Credentials File for more details.

role_arn is used to specify which AWS IAM role to assume for generating temporary credentials. If role_arn is given, metricbeat will check if access keys are given. If not, metricbeat will check for credential profile name. If neither is given, default credential profile will be used. Please make sure credentials are given under either a credential profile or access keys.

If running on Docker, the credential file needs to be provided via a volume mount. For example, with Metricbeat:

docker run -d --name=metricbeat --user=root --volume="$(pwd)/metricbeat.aws.yml:/usr/share/metricbeat/metricbeat.yml:ro" --volume="/Users/foo/.aws/credentials:/usr/share/metricbeat/credentials:ro" docker.elastic.co/beats/metricbeat:7.11.1 metricbeat -e -E cloud.auth=elastic:1234 -E cloud.id=test-aws:1234

Sample metricbeat.aws.yml looks like:

metricbeat.modules:
- module: aws
  period: 5m
  credential_profile_name: elastic-beats
  shared_credential_file: /usr/share/metricbeat/credentials
  metricsets:
    - ec2

There are two different types of AWS credentials can be used: access keys and temporary security credentials.

AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are the two parts of access keys. They are long-term credentials for an IAM user or the AWS account root user. Please see AWS Access Keys and Secret Access Keys for more details.

An IAM role is an IAM identity that you can create in your account that has specific permissions that determine what the identity can and cannot do in AWS. A role does not have standard long-term credentials such as a password or access keys associated with it. Instead, when you assume a role, it provides you with temporary security credentials for your role session. IAM role Amazon Resource Name (ARN) can be used to specify which AWS IAM role to assume to generate temporary credentials. Please see AssumeRole API documentation for more details.

Here are the steps to set up IAM role using AWS CLI for Metricbeat. Please replace 123456789012 with your own account ID.

Step 1. Create example-policy.json file to include all permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "sqs:ReceiveMessage"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "sqs:ChangeMessageVisibility",
            "Resource": "arn:aws:sqs:us-east-1:123456789012:test-fb-ks"
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": "sqs:DeleteMessage",
            "Resource": "arn:aws:sqs:us-east-1:123456789012:test-fb-ks"
        },
        {
            "Sid": "VisualEditor3",
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole",
                "sqs:ListQueues",
                "tag:GetResources",
                "ec2:DescribeInstances",
                "cloudwatch:GetMetricData",
                "ec2:DescribeRegions",
                "iam:ListAccountAliases",
                "sts:GetCallerIdentity",
                "cloudwatch:ListMetrics"
            ],
            "Resource": "*"
        }
    ]
}

Step 2. Create IAM policy using the aws iam create-policy command:

$ aws iam create-policy --policy-name example-policy --policy-document file://example-policy.json

Step 3. Create the JSON file example-role-trust-policy.json that defines the trust relationship of the IAM role

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Principal": { "AWS": "arn:aws:iam::123456789012:root" },
        "Action": "sts:AssumeRole"
    }
}

Step 4. Create the IAM role and attach the policy:

$ aws iam create-role --role-name example-role --assume-role-policy-document file://example-role-trust-policy.json
$ aws iam attach-role-policy --role-name example-role --policy-arn "arn:aws:iam::123456789012:policy/example-policy"

After these steps are done, IAM role ARN can be used for authentication in Metricbeat aws module.

Temporary security credentials has a limited lifetime and consists of an access key ID, a secret access key, and a security token which typically returned from GetSessionToken. MFA-enabled IAM users would need to submit an MFA code while calling GetSessionToken. default_region identifies the AWS Region whose servers you want to send your first API request to by default. This is typically the Region closest to you, but it can be any Region. Please see Temporary Security Credentials for more details. sts get-session-token AWS CLI can be used to generate temporary credentials. For example. with MFA-enabled:

aws> sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --token-code 456789 --duration-seconds 129600

Because temporary security credentials are short term, after they expire, the user needs to generate new ones and modify the aws.yml config file with the new credentials. Unless live reloading feature is enabled for Metricbeat, the user needs to manually restart Metricbeat after updating the config file in order to continue collecting Cloudwatch metrics. This will cause data loss if the config file is not updated with new credentials before the old ones expire. For Metricbeat, we recommend users to use access keys in config file to enable aws module making AWS api calls without have to generate new temporary credentials and update the config frequently.

IAM policy is an entity that defines permissions to an object within your AWS environment. Specific permissions needs to be added into the IAM user’s policy to authorize Metricbeat to collect AWS monitoring metrics. Please see documentation under each metricset for required permissions.

The AWS module supports the standard configuration options that are described in Modules. Here is an example configuration:

metricbeat.modules:
- module: aws
  period: 300s
  credential_profile_name: test-mb
  metricsets:
    - ec2
  tags_filter:
    - key: "Organization"
      value: "Engineering"
- module: aws
  period: 300s
  credential_profile_name: test-mb
  metricsets:
    - sqs
  regions:
    - us-west-1
- module: aws
  period: 86400s
  metricsets:
    - s3_request
    - s3_daily_storage
  access_key_id: '${AWS_ACCESS_KEY_ID:""}'
  secret_access_key: '${AWS_SECRET_ACCESS_KEY:""}'
  session_token: '${AWS_SESSION_TOKEN:""}'
- module: aws
  period: 300s
  credential_profile_name: test-mb
  metricsets:
    - cloudwatch
  metrics:
    - namespace: AWS/EC2
      name: ["CPUUtilization"]
      dimensions:
        - name: InstanceId
          value: i-0686946e22cf9494a
    - namespace: AWS/EBS
    - namespace: AWS/ELB
      resource_type: elasticloadbalancing
      tags:
        - key: "Organization"
          value: "Engineering"
- module: aws
  period: 60s
  credential_profile_name: test-mb
  tags_filter:
    - key: "dept"
      value: "eng"
  metricsets:
    - elb
    - natgateway
    - rds
    - transitgateway
    - usage
    - vpn

The following metricsets are available: