NAME

euwatch-put-data — add data points to a CloudWatch metric

SYNOPSIS

euwatch-put-data -n NAMESPACE [-v FLOAT] ...

euwatch-put-data -n NAMESPACE [-s KEY1=VALUE1,KEY2-VALUE2,...] ...

DESCRIPTION

The euwatch-put-data utility adds data to a CloudWatch metric. A metric datum consists of a metric name, any of several attributes, and either a simple, numeric value (-v) or a set of statistical values (-s).

All of the data in a given invocation of euwatch-put-data must belong to one namespace, whose name is specified with -n.

Metric data consist of one or more of the attributes below. These attributes may be specified using dedicated options that apply to all data in a given invocation of euwatch-put-data, or for individual data as part of an input to -s. A metric name is required for all metric data.

Name	Option	Aliases
MetricName	`-m`	metric
Dimensions	`-d`	dim
Timestamp	`-t`	ts
Unit	`-u`	unit

Simple metric data have one additional attribute for their values.

Name	Option	Aliases
Value	`-v`	val

Statistical metric data have four additional attributes. These attributes cannot be specified using separate command line options.

Name	Aliases
Maximum	max
Minimum	min
SampleCount	count
Sum	sum

Optional arguments:

-n NAMESPACE, --namespace NAMESPACE

The namespace for all the data points in the current invocation of euwatch-put-data. This option is required.

-v FLOAT, --value FLOAT

Each use of the -v option specifies a new simple metric datum. A value for a simple metric datum. To specify other attributes for simple data points specifed using this option, use the corresponding options for those attributes from the tables above. In particular, -m is required when -v is used.

-s KEY=VALUE,..., --metric-datum KEY=VALUE,...

The -s option allows for full control of the attributes of each metric datum. This mode of entry is required for specifying statistical data points. To specify a datum using this option, join each attribute's name or alias from the tables above with its value using the “=” character, and join each of those pairs with “,” characters. If a value contains a “,” character, surround the entire attribute with double-quotes, as in the following example.

"Dimensions=ImageId=ami-98765432,InstanceId:i-12345678"

Note that most shell environments require double-quotes to be escaped.

“Dimensions” attributes are specified as a comma-separated list of dimension names and values that are themselves separated by “:” characters.

Attributes specified via -s take precedence over those specified with attribute-specific options, such as -d.

See the EXAMPLES section for some illustrative examples.

-m METRIC, --metric-name METRIC

The name of the metric to add data to. This is required unless all metric data specify metric names themselves.

-d KEY=VALUE,..., --dimensions KEY=VALUE,...

A list of dimensions to associate with the new metric data.

-t YYYY-MM-DDThh:mm:ssZ, --timestamp YYYY-MM-DDThh:mm:ssZ

A timestamp for the new metric data, in a format specified by ISO 8601. Note that the CloudWatch service does not accept data with timestamps more than two weeks in the past.

-u UNIT, --unit UNIT

The unit, such as “Bytes”, in which to report the new metric data. Examples of valid units include the following:

Seconds
Microseconds
Milliseconds
Bytes
Kilobytes
Megabytes
Gigabytes
Terabytes
Bits
Kilobits
Megabits
Gigabits
Terabits
Percent
Count
Bytes/Second
Kilobytes/Second
Megabytes/Second
Gigabytes/Second
Terabytes/Second
Bits/Second
Kilobits/Second
Megabits/Second
Gigabits/Second
Terabits/Second
Count/Second
None

-h, --help

Show a help message and exit without doing anything.

-U URL, --url URL

The URL of the service to contact.

-I KEY_ID, --access-key-id KEY_ID

The access key ID to use to authenticate requests.

-S KEY. --secret-key KEY

The secret key to use to authenticate requests.

--security-token TOKEN

The STS security token to use to authenticate requests.

--region USER@REGION

The user and/or region name to use when looking up configuration file data.

--debug

Show debugging output when running.

--debugger

Launch an interactive epdb or pdb debugger after encountering an error.

--version

Show the program's version and exit.

EXAMPLES

Report that instance i-12345678 is using 747 megabytes of memory using metric “MemoryUtilization” in namespace “MyNamespace”.

euwatch-put-data
  -n MyNamespace
  -m MemoryUtilization
  -u Megabytes
  -d InstanceId=i-12345678
  -v 747

Same as above, but using the -s option.

euwatch-put-data
  -n MyNamespace
  -m MemoryUtilization
  -u Megabytes
  -d InstanceId=i-12345678
  -s Value=747

Same as above, but specifying as much as possible using the -s option.

euwatch-put-data
  -n MyNamespace
  -s
  MetricName=MemoryUtilization,Unit=Megabytes,Dimensions=InstanceId:i-12345678,Value=747

Report statistics for 50 samples from instance i-12345678 that have a minimum value of 20, a maximum value of 80, and a sum of 2500 using metric “QueriesPerSecond”, in namespace “MyNamespace”.

euwatch-put-data
  -n MyNamespace
  -m QueriesPerSecond
  -u Count/Second
  -d InstanceId=i-12345678
  -s
  Minimum=20,Maximum=80,Sum=2500,SampleCount=50

Same as above, but using aliases for attribute names.

euwatch-put-data
  -n MyNamespace
  -m QueriesPerSecond
  -u Count/Second
  -d InstanceId=i-12345678
  -s
  min=20,max=80,sum=2500,count=50

Report both of the metric data above at once. The second datum uses -s to override the metric name and unit attributes specified by -m and -u, but not the dimension specified by -d.

euwatch-put-data
  -n MyNamespace
  -m MemoryUtilization
  -u Megabytes
  -d InstanceId=i-12345678
  -v 747
  -s
  metric=QueriesPerSecond,unit=Count/Second,min=20,max=80,sum=2500,count=50

ENVIRONMENT

AWS_ACCESS_KEY_ID: The access key ID to use when authenticating web service requests. This takes precedence over --region and euca2ools.ini(5), but not -I.
AWS_SECRET_ACCESS_KEY: The secret key to use when authenticating web service requests. This takes precedence over --region and euca2ools.ini(5), but not -S.
AWS_CLOUDWATCH_URL: The URL of the service to contact. This takes precedence over --region and euca2ools.ini(5), but not -U.

HISTORY

The euwatch-put-data command first appeared in euca2ools 3.0.

The ability to report multiple metric data in a single request and the generic -s syntax that allows one to specify all attributes of a metric datum first appeared in euca2ools 3.4.

NOTES

euwatch-put-data requires access keys and knowledge of where to locate the web services it needs to contact. It can obtain these from several locations. See euca2ools(7) for more information.

euwatch-put-data(1)