180773ecb7 | ||
---|---|---|
.. | ||
README.md | ||
cloudwatch.go | ||
cloudwatch_test.go |
README.md
Amazon CloudWatch Statistics Input
This plugin will pull Metric Statistics from Amazon CloudWatch.
Amazon Authentication
This plugin uses a credential chain for Authentication with the CloudWatch API endpoint. In the following order the plugin will attempt to authenticate.
- Assumed credentials via STS if
role_arn
attribute is specified (source credentials are evaluated from subsequent rules) - Explicit credentials from
access_key
,secret_key
, andtoken
attributes - Shared profile from
profile
attribute - Environment Variables
- Shared Credentials
- EC2 Instance Profile
Configuration:
[[inputs.cloudwatch]]
## Amazon Region (required)
region = 'us-east-1'
## Requested CloudWatch aggregation Period (required - must be a multiple of 60s)
period = '1m'
## Collection Delay (required - must account for metrics availability via CloudWatch API)
delay = '1m'
## Override global run interval (optional - defaults to global interval)
## Recomended: use metric 'interval' that is a multiple of 'period' to avoid
## gaps or overlap in pulled data
interval = '1m'
## Metric Statistic Namespace (required)
namespace = 'AWS/ELB'
## Maximum requests per second. Note that the global default AWS rate limit is
## 10 reqs/sec, so if you define multiple namespaces, these should add up to a
## maximum of 10.
ratelimit = 10
## Metrics to Pull (optional)
## Defaults to all Metrics in Namespace if nothing is provided
## Refreshes Namespace available metrics every 1h
[[inputs.cloudwatch.metrics]]
names = ['Latency', 'RequestCount']
## Dimension filters for Metric (optional)
[[inputs.cloudwatch.metrics.dimensions]]
name = 'LoadBalancerName'
value = 'p-example'
[[inputs.cloudwatch.metrics.dimensions]]
name = 'AvailabilityZone'
value = '*'
Requirements and Terminology
Plugin Configuration utilizes CloudWatch concepts and access pattern to allow monitoring of any CloudWatch Metric.
region
must be a valid AWS Region valueperiod
must be a valid CloudWatch Period valuenamespace
must be a valid CloudWatch Namespace valuenames
must be valid CloudWatch Metric namesdimensions
must be valid CloudWatch Dimension name/value pairs
Omitting or specifying a value of '*'
for a dimension value configures all available metrics that contain a dimension with the specified name
to be retrieved. If specifying >1 dimension, then the metric must contain all the configured dimensions where the the value of the
wildcard dimension is ignored.
Example:
[[inputs.cloudwatch.metrics]]
names = ['Latency']
## Dimension filters for Metric (optional)
[[inputs.cloudwatch.metrics.dimensions]]
name = 'LoadBalancerName'
value = 'p-example'
[[inputs.cloudwatch.metrics.dimensions]]
name = 'AvailabilityZone'
value = '*'
If the following ELBs are available:
- name:
p-example
, availabilityZone:us-east-1a
- name:
p-example
, availabilityZone:us-east-1b
- name:
q-example
, availabilityZone:us-east-1a
- name:
q-example
, availabilityZone:us-east-1b
Then 2 metrics will be output:
- name:
p-example
, availabilityZone:us-east-1a
- name:
p-example
, availabilityZone:us-east-1b
If the AvailabilityZone
wildcard dimension was omitted, then a single metric (name: p-example
)
would be exported containing the aggregate values of the ELB across availability zones.
Restrictions and Limitations
- CloudWatch metrics are not available instantly via the CloudWatch API. You should adjust your collection
delay
to account for this lag in metrics availability based on your monitoring subscription level - CloudWatch API usage incurs cost - see GetMetricStatistics Pricing
Measurements & Fields:
Each CloudWatch Namespace monitored records a measurement with fields for each available Metric Statistic Namespace and Metrics are represented in snake case
- cloudwatch_{namespace}
- {metric}_sum (metric Sum value)
- {metric}_average (metric Average value)
- {metric}_minimum (metric Minimum value)
- {metric}_maximum (metric Maximum value)
- {metric}_sample_count (metric SampleCount value)
Tags:
Each measurement is tagged with the following identifiers to uniquely identify the associated metric Tag Dimension names are represented in snake case
- All measurements have the following tags:
- region (CloudWatch Region)
- unit (CloudWatch Metric Unit)
- {dimension-name} (Cloudwatch Dimension value - one for each metric dimension)
Example Output:
$ ./telegraf -config telegraf.conf -input-filter cloudwatch -test
> cloudwatch_aws_elb,load_balancer_name=p-example,region=us-east-1,unit=seconds latency_average=0.004810798017284538,latency_maximum=0.1100282669067383,latency_minimum=0.0006084442138671875,latency_sample_count=4029,latency_sum=19.382705211639404 1459542420000000000