Class: AWS.CloudWatch

Inherits:
AWS.Service show all
Identifier:
cloudwatch
API Version:
2010-08-01
Defined in:
(unknown)

Overview

Constructs a service interface object. Each API operation is exposed as a function on service.

Sending a Request Using CloudWatch

var cloudwatch = new AWS.CloudWatch();
cloudwatch.deleteAlarms(params, function (err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Locking the API Version

In order to ensure that the CloudWatch object uses this specific API, you can construct the object by passing the apiVersion option to the constructor:

var cloudwatch = new AWS.CloudWatch({apiVersion: '2010-08-01'});

You can also set the API version globally in AWS.config.apiVersions using the cloudwatch service identifier:

AWS.config.apiVersions = {
  cloudwatch: '2010-08-01',
  // other service API versions
};

var cloudwatch = new AWS.CloudWatch();

Version:

Constructor Summary (collapse)

Property Summary (collapse)

Properties inherited from AWS.Service

apiVersions

Method Summary (collapse)

Methods inherited from AWS.Service

makeRequest, makeUnauthenticatedRequest, waitFor, setupRequestListeners, defineService

Constructor Details

new AWS.CloudWatch(options = {})

Constructs a service object. This object has one method for each API operation.

Examples:

Constructing a CloudWatch object

var cloudwatch = new AWS.CloudWatch({apiVersion: '2010-08-01'});

Options Hash (options):

  • endpoint (String)

    The endpoint URI to send requests to. The default endpoint is built from the configured region. The endpoint should be a string like 'https://{service}.{region}.amazonaws.com'.

  • accessKeyId (String)

    your AWS access key ID.

  • secretAccessKey (String)

    your AWS secret access key.

  • sessionToken (AWS.Credentials)

    the optional AWS session token to sign requests with.

  • credentials (AWS.Credentials)

    the AWS credentials to sign requests with. You can either specify this object, or specify the accessKeyId and secretAccessKey options directly.

  • credentialProvider (AWS.CredentialProviderChain)

    the provider chain used to resolve credentials if no static credentials property is set.

  • region (String)

    the region to send service requests to. See AWS.CloudWatch.region for more information.

  • maxRetries (Integer)

    the maximum amount of retries to attempt with a request. See AWS.CloudWatch.maxRetries for more information.

  • maxRedirects (Integer)

    the maximum amount of redirects to follow with a request. See AWS.CloudWatch.maxRedirects for more information.

  • sslEnabled (Boolean)

    whether to enable SSL for requests.

  • paramValidation (Boolean)

    whether parameter validation is on.

  • computeChecksums (Boolean)

    whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only)

  • convertResponseTypes (Boolean)

    whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to true.

  • s3ForcePathStyle (Boolean)

    whether to force path style URLs for S3 objects.

  • httpOptions (map)

    A set of options to pass to the low-level HTTP request. Currently supported options are:

    • proxy [String] — the URL to proxy requests through
    • agent [http.Agent, https.Agent] — the Agent object to perform HTTP requests with. Used for connection pooling. Defaults to the global agent (http.globalAgent) for non-SSL connections. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only available in the Node.js environment.
    • timeout [Integer] — Sets the socket to timeout after timeout milliseconds of inactivity on the socket. Defaults to no timeout.
    • xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
  • apiVersion (String, Date)

    a String in YYYY-MM-DD format (or a date) that represents the latest possible API version that can be used in all services (unless overridden by apiVersions). Specify 'latest' to use the latest possible version.

  • apiVersions (map<String, String|Date>)

    a map of service identifiers (the lowercase service class name) with the API version to use when instantiating a service. Specify 'latest' for each individual that can use the latest available version.

  • logger (#write, #log)

    an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests

  • signatureVersion (String)

    the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.

Property Details

(AWS.Endpoint) endpoint (readwrite)

Returns an Endpoint object representing the endpoint URL for service requests.

Returns:

  • (AWS.Endpoint)

    an Endpoint object representing the endpoint URL for service requests.

Method Details

(AWS.Request) deleteAlarms(params = {}, callback)

Deletes all specified alarms. In the event of an error, no alarms are deleted.

Examples:

Calling the deleteAlarms operation

var params = {
  AlarmNames: [ // required
    'STRING_VALUE',
    // ... more items ...
  ]
};
cloudwatch.deleteAlarms(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmNames — (Array<String>)

      A list of alarms to be deleted.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) describeAlarmHistory(params = {}, callback)

Retrieves history for the specified alarm. Filter alarms by date range or item type. If an alarm name is not specified, Amazon CloudWatch returns histories for all of the owner's alarms.

Amazon CloudWatch retains the history of an alarm for two weeks, whether or not you delete the alarm.

Examples:

Calling the describeAlarmHistory operation

var params = {
  AlarmName: 'STRING_VALUE',
  EndDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
  HistoryItemType: 'ConfigurationUpdate | StateUpdate | Action',
  MaxRecords: 0,
  NextToken: 'STRING_VALUE',
  StartDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789
};
cloudwatch.describeAlarmHistory(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmName — (String)

      The name of the alarm.

    • HistoryItemType — (String)

      The type of alarm histories to retrieve.

      Possible values include:
      • "ConfigurationUpdate"
      • "StateUpdate"
      • "Action"
    • StartDate — (Date)

      The starting date to retrieve alarm history.

    • EndDate — (Date)

      The ending date to retrieve alarm history.

    • MaxRecords — (Integer)

      The maximum number of alarm history records to retrieve.

    • NextToken — (String)

      The token returned by a previous call to indicate that there is more data available.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • AlarmHistoryItems — (Array<map>)

        A list of alarm histories in JSON format.

        • AlarmName — (String)

          The descriptive name for the alarm.

        • Timestamp — (Date)

          The time stamp for the alarm history item. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

        • HistoryItemType — (String)

          The type of alarm history item.

          Possible values include:
          • "ConfigurationUpdate"
          • "StateUpdate"
          • "Action"
        • HistorySummary — (String)

          A human-readable summary of the alarm history.

        • HistoryData — (String)

          Machine-readable data about the alarm in JSON format.

      • NextToken — (String)

        A string that marks the start of the next batch of returned results.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) describeAlarms(params = {}, callback)

Retrieves alarms with the specified names. If no name is specified, all alarms for the user are returned. Alarms can be retrieved by using only a prefix for the alarm name, the alarm state, or a prefix for any action.

Examples:

Calling the describeAlarms operation

var params = {
  ActionPrefix: 'STRING_VALUE',
  AlarmNamePrefix: 'STRING_VALUE',
  AlarmNames: [
    'STRING_VALUE',
    // ... more items ...
  ],
  MaxRecords: 0,
  NextToken: 'STRING_VALUE',
  StateValue: 'OK | ALARM | INSUFFICIENT_DATA'
};
cloudwatch.describeAlarms(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmNames — (Array<String>)

      A list of alarm names to retrieve information for.

    • AlarmNamePrefix — (String)

      The alarm name prefix. AlarmNames cannot be specified if this parameter is specified.

    • StateValue — (String)

      The state value to be used in matching alarms.

      Possible values include:
      • "OK"
      • "ALARM"
      • "INSUFFICIENT_DATA"
    • ActionPrefix — (String)

      The action name prefix.

    • MaxRecords — (Integer)

      The maximum number of alarm descriptions to retrieve.

    • NextToken — (String)

      The token returned by a previous call to indicate that there is more data available.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • MetricAlarms — (Array<map>)

        A list of information for the specified alarms.

        • AlarmName — (String)

          The name of the alarm.

        • AlarmArn — (String)

          The Amazon Resource Name (ARN) of the alarm.

        • AlarmDescription — (String)

          The description for the alarm.

        • AlarmConfigurationUpdatedTimestamp — (Date)

          The time stamp of the last update to the alarm configuration. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

        • ActionsEnabled — (Boolean)

          Indicates whether actions should be executed during any changes to the alarm's state.

        • OKActions — (Array<String>)

          The list of actions to execute when this alarm transitions into an OK state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supported are publishing to an Amazon SNS topic and triggering an Auto Scaling policy.

        • AlarmActions — (Array<String>)

          The list of actions to execute when this alarm transitions into an ALARM state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supported are publishing to an Amazon SNS topic and triggering an Auto Scaling policy.

        • InsufficientDataActions — (Array<String>)

          The list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supported are publishing to an Amazon SNS topic or triggering an Auto Scaling policy.

          The current WSDL lists this attribute as UnknownActions.
        • StateValue — (String)

          The state value for the alarm.

          Possible values include:
          • "OK"
          • "ALARM"
          • "INSUFFICIENT_DATA"
        • StateReason — (String)

          A human-readable explanation for the alarm's state.

        • StateReasonData — (String)

          An explanation for the alarm's state in machine-readable JSON format

        • StateUpdatedTimestamp — (Date)

          The time stamp of the last update to the alarm's state. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

        • MetricName — (String)

          The name of the alarm's metric.

        • Namespace — (String)

          The namespace of alarm's associated metric.

        • Statistic — (String)

          The statistic to apply to the alarm's associated metric.

          Possible values include:
          • "SampleCount"
          • "Average"
          • "Sum"
          • "Minimum"
          • "Maximum"
        • Dimensions — (Array<map>)

          The list of dimensions associated with the alarm's associated metric.

          • Namerequired — (String)

            The name of the dimension.

          • Valuerequired — (String)

            The value representing the dimension measurement

        • Period — (Integer)

          The period in seconds over which the statistic is applied.

        • Unit — (String)

          The unit of the alarm's associated metric.

          Possible values include:
          • "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"
        • EvaluationPeriods — (Integer)

          The number of periods over which data is compared to the specified threshold.

        • Threshold — (Float)

          The value against which the specified statistic is compared.

        • ComparisonOperator — (String)

          The arithmetic operation to use when comparing the specified Statistic and Threshold. The specified Statistic value is used as the first operand.

          Possible values include:
          • "GreaterThanOrEqualToThreshold"
          • "GreaterThanThreshold"
          • "LessThanThreshold"
          • "LessThanOrEqualToThreshold"
      • NextToken — (String)

        A string that marks the start of the next batch of returned results.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) describeAlarmsForMetric(params = {}, callback)

Retrieves all alarms for a single metric. Specify a statistic, period, or unit to filter the set of alarms further.

Examples:

Calling the describeAlarmsForMetric operation

var params = {
  MetricName: 'STRING_VALUE', // required
  Namespace: 'STRING_VALUE', // required
  Dimensions: [
    {
      Name: 'STRING_VALUE', // required
      Value: 'STRING_VALUE' // required
    },
    // ... more items ...
  ],
  Period: 0,
  Statistic: 'SampleCount | Average | Sum | Minimum | Maximum',
  Unit: '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'
};
cloudwatch.describeAlarmsForMetric(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • MetricName — (String)

      The name of the metric.

    • Namespace — (String)

      The namespace of the metric.

    • Statistic — (String)

      The statistic for the metric.

      Possible values include:
      • "SampleCount"
      • "Average"
      • "Sum"
      • "Minimum"
      • "Maximum"
    • Dimensions — (Array<map>)

      The list of dimensions associated with the metric.

      • Namerequired — (String)

        The name of the dimension.

      • Valuerequired — (String)

        The value representing the dimension measurement

    • Period — (Integer)

      The period in seconds over which the statistic is applied.

    • Unit — (String)

      The unit for the metric.

      Possible values include:
      • "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"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • MetricAlarms — (Array<map>)

        A list of information for each alarm with the specified metric.

        • AlarmName — (String)

          The name of the alarm.

        • AlarmArn — (String)

          The Amazon Resource Name (ARN) of the alarm.

        • AlarmDescription — (String)

          The description for the alarm.

        • AlarmConfigurationUpdatedTimestamp — (Date)

          The time stamp of the last update to the alarm configuration. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

        • ActionsEnabled — (Boolean)

          Indicates whether actions should be executed during any changes to the alarm's state.

        • OKActions — (Array<String>)

          The list of actions to execute when this alarm transitions into an OK state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supported are publishing to an Amazon SNS topic and triggering an Auto Scaling policy.

        • AlarmActions — (Array<String>)

          The list of actions to execute when this alarm transitions into an ALARM state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supported are publishing to an Amazon SNS topic and triggering an Auto Scaling policy.

        • InsufficientDataActions — (Array<String>)

          The list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supported are publishing to an Amazon SNS topic or triggering an Auto Scaling policy.

          The current WSDL lists this attribute as UnknownActions.
        • StateValue — (String)

          The state value for the alarm.

          Possible values include:
          • "OK"
          • "ALARM"
          • "INSUFFICIENT_DATA"
        • StateReason — (String)

          A human-readable explanation for the alarm's state.

        • StateReasonData — (String)

          An explanation for the alarm's state in machine-readable JSON format

        • StateUpdatedTimestamp — (Date)

          The time stamp of the last update to the alarm's state. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

        • MetricName — (String)

          The name of the alarm's metric.

        • Namespace — (String)

          The namespace of alarm's associated metric.

        • Statistic — (String)

          The statistic to apply to the alarm's associated metric.

          Possible values include:
          • "SampleCount"
          • "Average"
          • "Sum"
          • "Minimum"
          • "Maximum"
        • Dimensions — (Array<map>)

          The list of dimensions associated with the alarm's associated metric.

          • Namerequired — (String)

            The name of the dimension.

          • Valuerequired — (String)

            The value representing the dimension measurement

        • Period — (Integer)

          The period in seconds over which the statistic is applied.

        • Unit — (String)

          The unit of the alarm's associated metric.

          Possible values include:
          • "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"
        • EvaluationPeriods — (Integer)

          The number of periods over which data is compared to the specified threshold.

        • Threshold — (Float)

          The value against which the specified statistic is compared.

        • ComparisonOperator — (String)

          The arithmetic operation to use when comparing the specified Statistic and Threshold. The specified Statistic value is used as the first operand.

          Possible values include:
          • "GreaterThanOrEqualToThreshold"
          • "GreaterThanThreshold"
          • "LessThanThreshold"
          • "LessThanOrEqualToThreshold"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) disableAlarmActions(params = {}, callback)

Disables actions for the specified alarms. When an alarm's actions are disabled the alarm's state may change, but none of the alarm's actions will execute.

Examples:

Calling the disableAlarmActions operation

var params = {
  AlarmNames: [ // required
    'STRING_VALUE',
    // ... more items ...
  ]
};
cloudwatch.disableAlarmActions(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmNames — (Array<String>)

      The names of the alarms to disable actions for.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) enableAlarmActions(params = {}, callback)

Enables actions for the specified alarms.

Examples:

Calling the enableAlarmActions operation

var params = {
  AlarmNames: [ // required
    'STRING_VALUE',
    // ... more items ...
  ]
};
cloudwatch.enableAlarmActions(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmNames — (Array<String>)

      The names of the alarms to enable actions for.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) getMetricStatistics(params = {}, callback)

Gets statistics for the specified metric.

The maximum number of data points returned from a single GetMetricStatistics request is 1,440, wereas the maximum number of data points that can be queried is 50,850. If you make a request that generates more than 1,440 data points, Amazon CloudWatch returns an error. In such a case, you can alter the request by narrowing the specified time range or increasing the specified period. Alternatively, you can make multiple requests across adjacent time ranges.

Amazon CloudWatch aggregates data points based on the length of the period that you specify. For example, if you request statistics with a one-minute granularity, Amazon CloudWatch aggregates data points with time stamps that fall within the same one-minute period. In such a case, the data points queried can greatly outnumber the data points returned.

The following examples show various statistics allowed by the data point query maximum of 50,850 when you call GetMetricStatistics on Amazon EC2 instances with detailed (one-minute) monitoring enabled:

  • Statistics for up to 400 instances for a span of one hour
  • Statistics for up to 35 instances over a span of 24 hours
  • Statistics for up to 2 instances over a span of 2 weeks

For information about the namespace, metric names, and dimensions that other Amazon Web Services products use to send metrics to Cloudwatch, go to Amazon CloudWatch Metrics, Namespaces, and Dimensions Reference in the Amazon CloudWatch Developer Guide.

Examples:

Calling the getMetricStatistics operation

var params = {
  EndTime: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789, // required
  MetricName: 'STRING_VALUE', // required
  Namespace: 'STRING_VALUE', // required
  Period: 0, // required
  StartTime: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789, // required
  Statistics: [ // required
    'SampleCount | Average | Sum | Minimum | Maximum',
    // ... more items ...
  ],
  Dimensions: [
    {
      Name: 'STRING_VALUE', // required
      Value: 'STRING_VALUE' // required
    },
    // ... more items ...
  ],
  Unit: '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'
};
cloudwatch.getMetricStatistics(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • Namespace — (String)

      The namespace of the metric, with or without spaces.

    • MetricName — (String)

      The name of the metric, with or without spaces.

    • Dimensions — (Array<map>)

      A list of dimensions describing qualities of the metric.

      • Namerequired — (String)

        The name of the dimension.

      • Valuerequired — (String)

        The value representing the dimension measurement

    • StartTime — (Date)

      The time stamp to use for determining the first datapoint to return. The value specified is inclusive; results include datapoints with the time stamp specified.

      The specified start time is rounded down to the nearest value. Datapoints are returned for start times up to two weeks in the past. Specified start times that are more than two weeks in the past will not return datapoints for metrics that are older than two weeks.

      Data that is timestamped 24 hours or more in the past may take in excess of 48 hours to become available from submission time using GetMetricStatistics.

    • EndTime — (Date)

      The time stamp to use for determining the last datapoint to return. The value specified is exclusive; results will include datapoints up to the time stamp specified.

    • Period — (Integer)

      The granularity, in seconds, of the returned datapoints. Period must be at least 60 seconds and must be a multiple of 60. The default value is 60.

    • Statistics — (Array<String>)

      The metric statistics to return. For information about specific statistics returned by GetMetricStatistics, go to Statistics in the Amazon CloudWatch Developer Guide.

      Valid Values: Average | Sum | SampleCount | Maximum | Minimum

    • Unit — (String)

      The unit for the metric.

      Possible values include:
      • "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"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Label — (String)

        A label describing the specified metric.

      • Datapoints — (Array<map>)

        The datapoints for the specified metric.

        • Timestamp — (Date)

          The time stamp used for the datapoint. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

        • SampleCount — (Float)

          The number of metric values that contributed to the aggregate value of this datapoint.

        • Average — (Float)

          The average of metric values that correspond to the datapoint.

        • Sum — (Float)

          The sum of metric values used for the datapoint.

        • Minimum — (Float)

          The minimum metric value used for the datapoint.

        • Maximum — (Float)

          The maximum of the metric value used for the datapoint.

        • Unit — (String)

          The standard unit used for the datapoint.

          Possible values include:
          • "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"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) listMetrics(params = {}, callback)

Returns a list of valid metrics stored for the AWS account owner. Returned metrics can be used with GetMetricStatistics to obtain statistical data for a given metric.

Up to 500 results are returned for any one call. To retrieve further results, use returned NextToken values with subsequent ListMetrics operations. If you create a metric with the PutMetricData action, allow up to fifteen minutes for the metric to appear in calls to the ListMetrics action. Statistics about the metric, however, are available sooner using GetMetricStatistics.

Examples:

Calling the listMetrics operation

var params = {
  Dimensions: [
    {
      Name: 'STRING_VALUE', // required
      Value: 'STRING_VALUE'
    },
    // ... more items ...
  ],
  MetricName: 'STRING_VALUE',
  Namespace: 'STRING_VALUE',
  NextToken: 'STRING_VALUE'
};
cloudwatch.listMetrics(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • Namespace — (String)

      The namespace to filter against.

    • MetricName — (String)

      The name of the metric to filter against.

    • Dimensions — (Array<map>)

      A list of dimensions to filter against.

      • Namerequired — (String)

        The dimension name to be matched.

      • Value — (String)

        The value of the dimension to be matched.

        Specifying a Name without specifying a Value returns all values associated with that Name.
    • NextToken — (String)

      The token returned by a previous call to indicate that there is more data available.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Metrics — (Array<map>)

        A list of metrics used to generate statistics for an AWS account.

        • Namespace — (String)

          The namespace of the metric.

        • MetricName — (String)

          The name of the metric.

        • Dimensions — (Array<map>)

          A list of dimensions associated with the metric.

          • Namerequired — (String)

            The name of the dimension.

          • Valuerequired — (String)

            The value representing the dimension measurement

      • NextToken — (String)

        A string that marks the start of the next batch of returned results.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) putMetricAlarm(params = {}, callback)

Creates or updates an alarm and associates it with the specified Amazon CloudWatch metric. Optionally, this operation can associate one or more Amazon Simple Notification Service resources with the alarm.

When this operation creates an alarm, the alarm state is immediately set to INSUFFICIENT_DATA. The alarm is evaluated and its StateValue is set appropriately. Any actions associated with the StateValue is then executed.

When updating an existing alarm, its StateValue is left unchanged.

Examples:

Calling the putMetricAlarm operation

var params = {
  AlarmName: 'STRING_VALUE', // required
  ComparisonOperator: 'GreaterThanOrEqualToThreshold | GreaterThanThreshold | LessThanThreshold | LessThanOrEqualToThreshold', // required
  EvaluationPeriods: 0, // required
  MetricName: 'STRING_VALUE', // required
  Namespace: 'STRING_VALUE', // required
  Period: 0, // required
  Statistic: 'SampleCount | Average | Sum | Minimum | Maximum', // required
  Threshold: 0.0, // required
  ActionsEnabled: true || false,
  AlarmActions: [
    'STRING_VALUE',
    // ... more items ...
  ],
  AlarmDescription: 'STRING_VALUE',
  Dimensions: [
    {
      Name: 'STRING_VALUE', // required
      Value: 'STRING_VALUE' // required
    },
    // ... more items ...
  ],
  InsufficientDataActions: [
    'STRING_VALUE',
    // ... more items ...
  ],
  OKActions: [
    'STRING_VALUE',
    // ... more items ...
  ],
  Unit: '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'
};
cloudwatch.putMetricAlarm(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmName — (String)

      The descriptive name for the alarm. This name must be unique within the user's AWS account

    • AlarmDescription — (String)

      The description for the alarm.

    • ActionsEnabled — (Boolean)

      Indicates whether or not actions should be executed during any changes to the alarm's state.

    • OKActions — (Array<String>)

      The list of actions to execute when this alarm transitions into an OK state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only action supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy.

    • AlarmActions — (Array<String>)

      The list of actions to execute when this alarm transitions into an ALARM state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only action supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy.

    • InsufficientDataActions — (Array<String>)

      The list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only action supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy.

    • MetricName — (String)

      The name for the alarm's associated metric.

    • Namespace — (String)

      The namespace for the alarm's associated metric.

    • Statistic — (String)

      The statistic to apply to the alarm's associated metric.

      Possible values include:
      • "SampleCount"
      • "Average"
      • "Sum"
      • "Minimum"
      • "Maximum"
    • Dimensions — (Array<map>)

      The dimensions for the alarm's associated metric.

      • Namerequired — (String)

        The name of the dimension.

      • Valuerequired — (String)

        The value representing the dimension measurement

    • Period — (Integer)

      The period in seconds over which the specified statistic is applied.

    • Unit — (String)

      The unit for the alarm's associated metric.

      Possible values include:
      • "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"
    • EvaluationPeriods — (Integer)

      The number of periods over which data is compared to the specified threshold.

    • Threshold — (Float)

      The value against which the specified statistic is compared.

    • ComparisonOperator — (String)

      The arithmetic operation to use when comparing the specified Statistic and Threshold. The specified Statistic value is used as the first operand.

      Possible values include:
      • "GreaterThanOrEqualToThreshold"
      • "GreaterThanThreshold"
      • "LessThanThreshold"
      • "LessThanOrEqualToThreshold"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) putMetricData(params = {}, callback)

Publishes metric data points to Amazon CloudWatch. Amazon Cloudwatch associates the data points with the specified metric. If the specified metric does not exist, Amazon CloudWatch creates the metric. It can take up to fifteen minutes for a new metric to appear in calls to the ListMetrics action.

The size of a PutMetricData request is limited to 8 KB for HTTP GET requests and 40 KB for HTTP POST requests.

Although the Value parameter accepts numbers of type Double, Amazon CloudWatch truncates values with very large exponents. Values with base-10 exponents greater than 126 (1 x 10126) are truncated. Likewise, values with base-10 exponents less than -130 (1 x 10^-130) are also truncated.

Data that is timestamped 24 hours or more in the past may take in excess of 48 hours to become available from submission time using GetMetricStatistics.

Examples:

Calling the putMetricData operation

var params = {
  MetricData: [ // required
    {
      MetricName: 'STRING_VALUE', // required
      Dimensions: [
        {
          Name: 'STRING_VALUE', // required
          Value: 'STRING_VALUE' // required
        },
        // ... more items ...
      ],
      StatisticValues: {
        Maximum: 0.0, // required
        Minimum: 0.0, // required
        SampleCount: 0.0, // required
        Sum: 0.0 // required
      },
      Timestamp: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
      Unit: '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',
      Value: 0.0
    },
    // ... more items ...
  ],
  Namespace: 'STRING_VALUE' // required
};
cloudwatch.putMetricData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • Namespace — (String)

      The namespace for the metric data.

      You cannot specify a namespace that begins with "AWS/". Namespaces that begin with "AWS/" are reserved for other Amazon Web Services products that send metrics to Amazon CloudWatch.
    • MetricData — (Array<map>)

      A list of data describing the metric.

      • MetricNamerequired — (String)

        The name of the metric.

      • Dimensions — (Array<map>)

        A list of dimensions associated with the metric. Note, when using the Dimensions value in a query, you need to append .member.N to it (e.g., Dimensions.member.N).

        • Namerequired — (String)

          The name of the dimension.

        • Valuerequired — (String)

          The value representing the dimension measurement

      • Timestamp — (Date)

        The time stamp used for the metric. If not specified, the default value is set to the time the metric data was received. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide.

      • Value — (Float)

        The value for the metric.

        Although the Value parameter accepts numbers of type Double, Amazon CloudWatch truncates values with very large exponents. Values with base-10 exponents greater than 126 (1 x 10126) are truncated. Likewise, values with base-10 exponents less than -130 (1 x 10^-130) are also truncated.
      • StatisticValues — (map)

        A set of statistical values describing the metric.

        • SampleCountrequired — (Float)

          The number of samples used for the statistic set.

        • Sumrequired — (Float)

          The sum of values for the sample set.

        • Minimumrequired — (Float)

          The minimum value of the sample set.

        • Maximumrequired — (Float)

          The maximum value of the sample set.

      • Unit — (String)

        The unit of the metric.

        Possible values include:
        • "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"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

(AWS.Request) setAlarmState(params = {}, callback)

Temporarily sets the state of an alarm. When the updated StateValue differs from the previous value, the action configured for the appropriate state is invoked. This is not a permanent change. The next periodic alarm check (in about a minute) will set the alarm to its actual state.

Examples:

Calling the setAlarmState operation

var params = {
  AlarmName: 'STRING_VALUE', // required
  StateReason: 'STRING_VALUE', // required
  StateValue: 'OK | ALARM | INSUFFICIENT_DATA', // required
  StateReasonData: 'STRING_VALUE'
};
cloudwatch.setAlarmState(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • AlarmName — (String)

      The descriptive name for the alarm. This name must be unique within the user's AWS account. The maximum length is 255 characters.

    • StateValue — (String)

      The value of the state.

      Possible values include:
      • "OK"
      • "ALARM"
      • "INSUFFICIENT_DATA"
    • StateReason — (String)

      The reason that this alarm is set to this specific state (in human-readable text format)

    • StateReasonData — (String)

      The reason that this alarm is set to this specific state (in machine-readable JSON format)

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.