cloudwatch

README

Amazon CloudWatch Output Plugin

This plugin will send metrics to 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. Web identity provider credentials via STS if role_arn and web_identity_token_file are specified
2. Assumed credentials via STS if role_arn attribute is specified (source credentials are evaluated from subsequent rules)
3. Explicit credentials from access_key, secret_key, and token attributes
4. Shared profile from profile attribute
5. Environment Variables
6. Shared Credentials
7. EC2 Instance Profile

If you are using credentials from a web identity provider, you can specify the session name using role_session_name. If left empty, the current timestamp will be used.

The IAM user needs only the cloudwatch:PutMetricData permission.

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Configuration

# Configuration for AWS CloudWatch output.
[[outputs.cloudwatch]]
  ## Amazon REGION
  region = "us-east-1"

  ## Amazon Credentials
  ## Credentials are loaded in the following order
  ## 1) Web identity provider credentials via STS if role_arn and web_identity_token_file are specified
  ## 2) Assumed credentials via STS if role_arn is specified
  ## 3) explicit credentials from 'access_key' and 'secret_key'
  ## 4) shared profile from 'profile'
  ## 5) environment variables
  ## 6) shared credentials file
  ## 7) EC2 Instance Profile
  #access_key = ""
  #secret_key = ""
  #token = ""
  #role_arn = ""
  #web_identity_token_file = ""
  #role_session_name = ""
  #profile = ""
  #shared_credential_file = ""

  ## Endpoint to make request against, the correct endpoint is automatically
  ## determined and this option should only be set if you wish to override the
  ## default.
  ##   ex: endpoint_url = "http://localhost:8000"
  # endpoint_url = ""

  ## Set http_proxy
  # use_system_proxy = false
  # http_proxy_url = "http://localhost:8888"

  ## Namespace for the CloudWatch MetricDatums
  namespace = "InfluxData/Telegraf"

  ## If you have a large amount of metrics, you should consider to send statistic
  ## values instead of raw metrics which could not only improve performance but
  ## also save AWS API cost. If enable this flag, this plugin would parse the required
  ## CloudWatch statistic fields (count, min, max, and sum) and send them to CloudWatch.
  ## You could use basicstats aggregator to calculate those fields. If not all statistic
  ## fields are available, all fields would still be sent as raw metrics.
  # write_statistics = false

  ## Enable high resolution metrics of 1 second (if not enabled, standard resolution are of 60 seconds precision)
  # high_resolution_metrics = false

For this output plugin to function correctly the following variables must be configured.

• region
• namespace

region

The region is the Amazon region that you wish to connect to. Examples include but are not limited to:

• us-west-1
• us-west-2
• us-east-1
• ap-southeast-1
• ap-southeast-2

namespace

The namespace used for AWS CloudWatch metrics.

write_statistics

If you have a large amount of metrics, you should consider to send statistic values instead of raw metrics which could not only improve performance but also save AWS API cost. If enable this flag, this plugin would parse the required CloudWatch statistic fields (count, min, max, and sum) and send them to CloudWatch. You could use basicstats aggregator to calculate those fields. If not all statistic fields are available, all fields would still be sent as raw metrics.

high_resolution_metrics

Enable high resolution metrics (1 second precision) instead of standard ones (60 seconds precision).

Documentation

Index

• func BuildDimensions(mTags map[string]string) []types.Dimension
• func BuildMetricDatum(buildStatistic bool, highResolutionMetrics bool, point telegraf.Metric) []types.MetricDatum
• func PartitionDatums(size int, datums []types.MetricDatum) [][]types.MetricDatum
• type CloudWatch
  • func (c *CloudWatch) Close() error
  • func (c *CloudWatch) Connect() error
  • func (*CloudWatch) SampleConfig() string
  • func (c *CloudWatch) Write(metrics []telegraf.Metric) error
  • func (c *CloudWatch) WriteToCloudWatch(datums []types.MetricDatum) error

Functions

func BuildDimensions

func BuildDimensions(mTags map[string]string) []types.Dimension

BuildDimensions makes a list of Dimensions by using a Point's tags. CloudWatch supports up to 10 dimensions per metric, so we only keep up to the first 10 alphabetically. This always includes the "host" tag if it exists.

func BuildMetricDatum

func BuildMetricDatum(buildStatistic bool, highResolutionMetrics bool, point telegraf.Metric) []types.MetricDatum

BuildMetricDatum makes a MetricDatum from telegraf.Metric. It would check if all required fields of cloudwatch.StatisticSet are available. If so, it would build MetricDatum from statistic values. Otherwise, fields would still been built independently.

func PartitionDatums

func PartitionDatums(size int, datums []types.MetricDatum) [][]types.MetricDatum

PartitionDatums partitions the MetricDatums into smaller slices of a max size so that are under the limit for the AWS API calls.

Types

type CloudWatch

type CloudWatch struct {
	Namespace             string `toml:"namespace"` // CloudWatch Metrics Namespace
	HighResolutionMetrics bool   `toml:"high_resolution_metrics"`

	WriteStatistics bool            `toml:"write_statistics"`
	Log             telegraf.Logger `toml:"-"`
	internalaws.CredentialConfig
	httpconfig.HTTPClientConfig
	// contains filtered or unexported fields
}

func (*CloudWatch) Close

func (c *CloudWatch) Close() error

func (*CloudWatch) Connect

func (c *CloudWatch) Connect() error

func (*CloudWatch) SampleConfig

func (*CloudWatch) SampleConfig() string

func (*CloudWatch) Write

func (c *CloudWatch) Write(metrics []telegraf.Metric) error

func (*CloudWatch) WriteToCloudWatch

func (c *CloudWatch) WriteToCloudWatch(datums []types.MetricDatum) error