telegraf/plugins/inputs/cloudwatch
Nathan Haneysmith 5dd8f4e02b new config option cw_interval for multiple results 2016-09-20 15:33:39 -07:00
..
README.md new config option cw_interval for multiple results 2016-09-20 15:33:39 -07:00
cloudwatch.go new config option cw_interval for multiple results 2016-09-20 15:33:39 -07:00
cloudwatch_test.go update the test to include the rate 2016-08-25 18:17:33 -07:00

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.

  1. Assumed credentials via STS if role_arn attribute is specified (source credentials are evaluated from subsequent rules)
  2. Explicit credentials from access_key, secret_key, and token attributes
  3. Shared profile from profile attribute
  4. Environment Variables
  5. Shared Credentials
  6. EC2 Instance Profile

Configuration:

[[inputs.cloudwatch]]
  ## Amazon Region (required)
  region = 'us-east-1'

  ## Collection Delay (required - must account for metrics availability via CloudWatch API)
  delay = '1m'

  ## Requested CloudWatch aggregation Period (required - must be a multiple of 60s). This
  ## should match your interval setting below, unless you're using cw_interval. If this value
  ## is greater than 1m, the response will be the average during that time.
  period = '1m'

  ## Recomended: either set interval to match 'period', or set both 'interval' and 'cw_interval'
  ## to a multiple of 'period' to avoid gaps or overlap in pulled data.
  interval = '1m'

  ## Optional: CloudWatch can return multiple results per request. If your interval is greater
  ## than 1m, you can either set period to match or set cw_interval.
  ## Example: period = '1m', interval = '1m' returns one datapoint per metric per minute
  ## Example: period = '5m', interval = '5m' returns one datapoint per metric every 5m
  ## Example: period = '1m', interval = '5m', cw_interval = '5m', 5 datapoints per metric every 5m
  # cw_interval = 5m

  ## 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. Optional - default value is 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 value
  • period must be a valid CloudWatch Period value
  • namespace must be a valid CloudWatch Namespace value
  • names must be valid CloudWatch Metric names
  • dimensions 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

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