get_metric_statistics ( $namespace, $metric_name, $start_time, $end_time, $period, $statistics, $unit, $opt )

Gets statistics for the specified metric.

The maximum number of data points returned from a single GetMetricStatistics request is 1,440. If a request is made that generates more than 1,440 data points, Amazon CloudWatch returns an error. In such a case, alter the request by narrowing the specified time range or increasing the specified period. Alternatively, 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 maximum number of data points that can be queried is 50,850; whereas the maximum number of data points returned is 1,440.

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

Access

public

Parameters

Parameter

Type

Required

Description

$namespace

string

Required

The namespace of the metric. [Constraints: The value must be between 1 and 255 characters, and must match the following regular expression pattern: [^:].*]

$metric_name

string

Required

The name of the metric.

$start_time

string

Required

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.

May be passed as a number of seconds since UNIX Epoch, or any string compatible with strtotime().

$end_time

string

Required

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. May be passed as a number of seconds since UNIX Epoch, or any string compatible with strtotime().

$period

integer

Required

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

string
array

Required

The metric statistics to return. Pass a string for a single value, or an indexed array for multiple values.

$unit

string

Required

The unit for the metric. [Allowed values: 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]

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • Dimensions - array - Optional - A list of dimensions describing qualities of the metric.
    • x - array - Optional - This represents a simple array index.
      • Name - string - Required - The name of the dimension.
      • Value - string - Required - The value representing the dimension measurement
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Get metric statistics.

// Get metrics
$cw = new AmazonCloudWatch();

$response = $cw->get_metric_statistics('AWS/EC2', 'CPUUtilization', '1 August 2009', '2 August 2009', 1800, 'Average', 'Percent');

// Success?
var_dump($response->isOK());
Result:
bool(true)

Get multiple metric statistics.

// Get metrics
$cw = new AmazonCloudWatch();

$response = $cw->get_metric_statistics('AWS/EC2', 'CPUUtilization', '1 August 2009', '2 August 2009', 1800, array('Average', 'Sum'), 'Percent');

// Success?
var_dump($response->isOK());
Result:
bool(true)

Changelog

Version

Description

1.2

The GetMetricStatistics operation introduced backwards-incompatible changes in the 2010-08-01 API release. These changes were accounted for in version 1.2 of the SDK.

Related Methods

Source

Method defined in services/cloudwatch.class.php | Toggle source view (26 lines) | View on GitHub

public function get_metric_statistics($namespace, $metric_name, $start_time, $end_time, $period, $statistics, $unit, $opt = null)
{
    if (!$opt) $opt = array();
    $opt['Namespace'] = $namespace;
    $opt['MetricName'] = $metric_name;
    $opt['Period'] = $period;
    $opt['Unit'] = $unit;
    $opt['StartTime'] = $this->util->convert_date_to_iso8601($start_time);
    $opt['EndTime'] = $this->util->convert_date_to_iso8601($end_time);

    // Required list (non-map)
    $opt = array_merge($opt, CFComplexType::map(array(
        'Statistics' => (is_array($statistics) ? $statistics : array($statistics))
    ), 'member'));

    // Optional list + map
    if (isset($opt['Dimensions']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'Dimensions' => $opt['Dimensions']
        ), 'member'));
        unset($opt['Dimensions']);
    }

    return $this->authenticate('GetMetricStatistics', $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback