EUWATCH-PUT-DATA(1)

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.

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.