Update docs on Cloudwatch. Set default period to 5m. (#2000)

Also don't use named returns in fetchNamespaceMetrics since it's
non-standard for the rest of the codebase.

CHANGELOG.md

@@ -1,3 +1,11 @@
+## v1.2 [unreleased]
+
+### Release Notes
+
+### Features
+
+### Bugfixes
+
 ## v1.1 [unreleased]
 
 ### Release Notes

etc/telegraf.conf

@@ -160,7 +160,7 @@
 # # Configuration for AWS CloudWatch output.
 # [[outputs.cloudwatch]]
 #   ## Amazon REGION
-#   region = 'us-east-1'
+#   region = "us-east-1"
 #
 #   ## Amazon Credentials
 #   ## Credentials are loaded in the following order
@@ -178,7 +178,7 @@
 #   #shared_credential_file = ""
 #
 #   ## Namespace for the CloudWatch MetricDatums
-#   namespace = 'InfluxData/Telegraf'
+#   namespace = "InfluxData/Telegraf"
 
 
 # # Configuration for DataDog API to send metrics to.
@@ -623,7 +623,7 @@
 # # Pull Metric Statistics from Amazon CloudWatch
 # [[inputs.cloudwatch]]
 #   ## Amazon Region
-#   region = 'us-east-1'
+#   region = "us-east-1"
 #
 #   ## Amazon Credentials
 #   ## Credentials are loaded in the following order
@@ -641,21 +641,21 @@
 #   #shared_credential_file = ""
 #
 #   ## Requested CloudWatch aggregation Period (required - must be a multiple of 60s)
-#   period = '1m'
+#   period = "5m"
 #
 #   ## Collection Delay (required - must account for metrics availability via CloudWatch API)
-#   delay = '1m'
+#   delay = "5m"
 #
 #   ## Recomended: use metric 'interval' that is a multiple of 'period' to avoid
 #   ## gaps or overlap in pulled data
-#   interval = '1m'
+#   interval = "5m"
 #
 #   ## Configure the TTL for the internal cache of metrics.
 #   ## Defaults to 1 hr if not specified
-#   #cache_ttl = '10m'
+#   #cache_ttl = "10m"
 #
 #   ## Metric Statistic Namespace (required)
-#   namespace = 'AWS/ELB'
+#   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
@@ -666,12 +666,12 @@
 #   ## Defaults to all Metrics in Namespace if nothing is provided
 #   ## Refreshes Namespace available metrics every 1h
 #   #[[inputs.cloudwatch.metrics]]
-#   #  names = ['Latency', 'RequestCount']
+#   #  names = ["Latency", "RequestCount"]
 #   #
 #   #  ## Dimension filters for Metric (optional)
 #   #  [[inputs.cloudwatch.metrics.dimensions]]
-#   #    name = 'LoadBalancerName'
+#   #    name = "LoadBalancerName"
-#   #    value = 'p-example'
+#   #    value = "p-example"
 
 
 # # Gather health check statuses from services registered in Consul
@@ -1979,4 +1979,3 @@
 #
 #   [inputs.webhooks.rollbar]
 #     path = "/rollbar"
-

plugins/inputs/cloudwatch/README.md

@@ -18,21 +18,28 @@ API endpoint. In the following order the plugin will attempt to authenticate.
 ```toml
 [[inputs.cloudwatch]]
   ## Amazon Region (required)
-  region = 'us-east-1'
+  region = "us-east-1"
 
+  # The minimum period for Cloudwatch metrics is 1 minute (60s). However not all
+  # metrics are made available to the 1 minute period. Some are collected at
+  # 3 minute and 5 minutes intervals. See https://aws.amazon.com/cloudwatch/faqs/#monitoring.
+  # Note that if a period is configured that is smaller than the minimum for a
+  # particular metric, that metric will not be returned by the Cloudwatch API
+  # and will not be collected by Telegraf.
+  #
   ## Requested CloudWatch aggregation Period (required - must be a multiple of 60s)
-  period = '1m'
+  period = "5m"
 
   ## Collection Delay (required - must account for metrics availability via CloudWatch API)
-  delay = '1m'
+  delay = "5m"
 
   ## 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'
+  interval = "5m"
 
   ## Metric Statistic Namespace (required)
-  namespace = 'AWS/ELB'
+  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
@@ -43,16 +50,16 @@ API endpoint. In the following order the plugin will attempt to authenticate.
   ## Defaults to all Metrics in Namespace if nothing is provided
   ## Refreshes Namespace available metrics every 1h
   [[inputs.cloudwatch.metrics]]
-    names = ['Latency', 'RequestCount']
+    names = ["Latency", "RequestCount"]
 
     ## Dimension filters for Metric (optional)
     [[inputs.cloudwatch.metrics.dimensions]]
-      name = 'LoadBalancerName'
+      name = "LoadBalancerName"
-      value = 'p-example'
+      value = "p-example"
 
     [[inputs.cloudwatch.metrics.dimensions]]
-      name = 'AvailabilityZone'
+      name = "AvailabilityZone"
-      value = '*'
+      value = "*"
 ```
 #### Requirements and Terminology
 
@@ -71,16 +78,16 @@ wildcard dimension is ignored.
 Example:
 ```
 [[inputs.cloudwatch.metrics]]
-  names = ['Latency']
+  names = ["Latency"]
 
   ## Dimension filters for Metric (optional)
   [[inputs.cloudwatch.metrics.dimensions]]
-    name = 'LoadBalancerName'
+    name = "LoadBalancerName"
-    value = 'p-example'
+    value = "p-example"
 
   [[inputs.cloudwatch.metrics.dimensions]]
-    name = 'AvailabilityZone'
+    name = "AvailabilityZone"
-    value = '*'
+    value = "*"
 ```
 
 If the following ELBs are available:

plugins/inputs/cloudwatch/cloudwatch.go

@@ -63,7 +63,7 @@ type (
 func (c *CloudWatch) SampleConfig() string {
 	return `
   ## Amazon Region
-  region = 'us-east-1'
+  region = "us-east-1"
 
   ## Amazon Credentials
   ## Credentials are loaded in the following order
@@ -80,22 +80,29 @@ func (c *CloudWatch) SampleConfig() string {
   #profile = ""
   #shared_credential_file = ""
 
+  # The minimum period for Cloudwatch metrics is 1 minute (60s). However not all
+  # metrics are made available to the 1 minute period. Some are collected at
+  # 3 minute and 5 minutes intervals. See https://aws.amazon.com/cloudwatch/faqs/#monitoring.
+  # Note that if a period is configured that is smaller than the minimum for a
+  # particular metric, that metric will not be returned by the Cloudwatch API
+  # and will not be collected by Telegraf.
+  #
   ## Requested CloudWatch aggregation Period (required - must be a multiple of 60s)
-  period = '1m'
+  period = "5m"
 
   ## Collection Delay (required - must account for metrics availability via CloudWatch API)
-  delay = '1m'
+  delay = "5m"
 
   ## Recomended: use metric 'interval' that is a multiple of 'period' to avoid
   ## gaps or overlap in pulled data
-  interval = '1m'
+  interval = "5m"
 
   ## Configure the TTL for the internal cache of metrics.
   ## Defaults to 1 hr if not specified
-  #cache_ttl = '10m'
+  #cache_ttl = "10m"
 
   ## Metric Statistic Namespace (required)
-  namespace = 'AWS/ELB'
+  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
@@ -106,12 +113,12 @@ func (c *CloudWatch) SampleConfig() string {
   ## Defaults to all Metrics in Namespace if nothing is provided
   ## Refreshes Namespace available metrics every 1h
   #[[inputs.cloudwatch.metrics]]
-  #  names = ['Latency', 'RequestCount']
+  #  names = ["Latency", "RequestCount"]
   #
   #  ## Dimension filters for Metric (optional)
   #  [[inputs.cloudwatch.metrics.dimensions]]
-  #    name = 'LoadBalancerName'
+  #    name = "LoadBalancerName"
-  #    value = 'p-example'
+  #    value = "p-example"
 `
 }
 
@@ -133,7 +140,6 @@ func (c *CloudWatch) Gather(acc telegraf.Accumulator) error {
 			if !hasWilcard(m.Dimensions) {
 				dimensions := make([]*cloudwatch.Dimension, len(m.Dimensions))
 				for k, d := range m.Dimensions {
-					fmt.Printf("Dimension [%s]:[%s]\n", d.Name, d.Value)
 					dimensions[k] = &cloudwatch.Dimension{
 						Name:  aws.String(d.Name),
 						Value: aws.String(d.Value),
@@ -229,13 +235,12 @@ func (c *CloudWatch) initializeCloudWatch() error {
 /*
  * Fetch available metrics for given CloudWatch Namespace
  */
-func (c *CloudWatch) fetchNamespaceMetrics() (metrics []*cloudwatch.Metric, err error) {
+func (c *CloudWatch) fetchNamespaceMetrics() ([]*cloudwatch.Metric, error) {
 	if c.metricCache != nil && c.metricCache.IsValid() {
-		metrics = c.metricCache.Metrics
+		return c.metricCache.Metrics, nil
-		return
 	}
 
-	metrics = []*cloudwatch.Metric{}
+	metrics := []*cloudwatch.Metric{}
 
 	var token *string
 	for more := true; more; {
@@ -263,7 +268,7 @@ func (c *CloudWatch) fetchNamespaceMetrics() (metrics []*cloudwatch.Metric, err
 		TTL:     c.CacheTTL.Duration,
 	}
 
-	return
+	return metrics, nil
 }
 
 /*

plugins/outputs/cloudwatch/cloudwatch.go

@@ -30,7 +30,7 @@ type CloudWatch struct {
 
 var sampleConfig = `
   ## Amazon REGION
-  region = 'us-east-1'
+  region = "us-east-1"
 
   ## Amazon Credentials
   ## Credentials are loaded in the following order
@@ -48,7 +48,7 @@ var sampleConfig = `
   #shared_credential_file = ""
 
   ## Namespace for the CloudWatch MetricDatums
-  namespace = 'InfluxData/Telegraf'
+  namespace = "InfluxData/Telegraf"
 `
 
 func (c *CloudWatch) SampleConfig() string {

scripts/circle-test.sh

@@ -82,6 +82,6 @@ if [ $? -eq 0 ]; then
     unset GOGC
     tag=$(git describe --exact-match HEAD)
     echo $tag
-    exit_if_fail ./scripts/build.py --release --package --version=$tag --platform=all --arch=all --upload --bucket=dl.influxdata.com/telegraf/releases
+    exit_if_fail ./scripts/build.py --release --package --platform=all --arch=all --upload --bucket=dl.influxdata.com/telegraf/releases
     mv build $CIRCLE_ARTIFACTS
 fi