euwatch-put-data man page

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.

See Also

euca2ools.ini(5), euca2ools(7)

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.

Info

December 8, 2016