/boto-2.5.2/boto/ec2/cloudwatch/metric.py

  1# Copyright (c) 2006-2012 Mitch Garnaat http://garnaat.org/
  2# Copyright (c) 2012 Amazon.com, Inc. or its affiliates.
  3# All Rights Reserved
  4#
  5# Permission is hereby granted, free of charge, to any person obtaining a
  6# copy of this software and associated documentation files (the
  7# "Software"), to deal in the Software without restriction, including
  8# without limitation the rights to use, copy, modify, merge, publish, dis-
  9# tribute, sublicense, and/or sell copies of the Software, and to permit
 10# persons to whom the Software is furnished to do so, subject to the fol-
 11# lowing conditions:
 12#
 13# The above copyright notice and this permission notice shall be included
 14# in all copies or substantial portions of the Software.
 15#
 16# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 17# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
 18# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
 19# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 20# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 21# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 22# IN THE SOFTWARE.
 23#
 24
 25from boto.ec2.cloudwatch.alarm import MetricAlarm
 26from boto.ec2.cloudwatch.dimension import Dimension
 27
 28
 29class Metric(object):
 30
 31    Statistics = ['Minimum', 'Maximum', 'Sum', 'Average', 'SampleCount']
 32    Units = ['Seconds', 'Microseconds', 'Milliseconds', 'Bytes', 'Kilobytes',
 33             'Megabytes', 'Gigabytes', 'Terabytes', 'Bits', 'Kilobits',
 34             'Megabits', 'Gigabits', 'Terabits', 'Percent', 'Count',
 35             'Bytes/Second', 'Kilobytes/Second', 'Megabytes/Second',
 36             'Gigabytes/Second', 'Terabytes/Second', 'Bits/Second',
 37             'Kilobits/Second', 'Megabits/Second', 'Gigabits/Second',
 38             'Terabits/Second', 'Count/Second', None]
 39
 40    def __init__(self, connection=None):
 41        self.connection = connection
 42        self.name = None
 43        self.namespace = None
 44        self.dimensions = None
 45
 46    def __repr__(self):
 47        return 'Metric:%s' % self.name
 48
 49    def startElement(self, name, attrs, connection):
 50        if name == 'Dimensions':
 51            self.dimensions = Dimension()
 52            return self.dimensions
 53
 54    def endElement(self, name, value, connection):
 55        if name == 'MetricName':
 56            self.name = value
 57        elif name == 'Namespace':
 58            self.namespace = value
 59        else:
 60            setattr(self, name, value)
 61
 62    def query(self, start_time, end_time, statistics, unit=None, period=60):
 63        """
 64        :type start_time: datetime
 65        :param start_time: The time stamp to use for determining the
 66            first datapoint to return. The value specified is
 67            inclusive; results include datapoints with the time stamp
 68            specified.
 69
 70        :type end_time: datetime
 71        :param end_time: The time stamp to use for determining the
 72            last datapoint to return. The value specified is
 73            exclusive; results will include datapoints up to the time
 74            stamp specified.
 75
 76        :type statistics: list
 77        :param statistics: A list of statistics names Valid values:
 78            Average | Sum | SampleCount | Maximum | Minimum
 79
 80        :type dimensions: dict
 81        :param dimensions: A dictionary of dimension key/values where
 82                           the key is the dimension name and the value
 83                           is either a scalar value or an iterator
 84                           of values to be associated with that
 85                           dimension.
 86
 87        :type unit: string
 88        :param unit: The unit for the metric.  Value values are:
 89            Seconds | Microseconds | Milliseconds | Bytes | Kilobytes |
 90            Megabytes | Gigabytes | Terabytes | Bits | Kilobits |
 91            Megabits | Gigabits | Terabits | Percent | Count |
 92            Bytes/Second | Kilobytes/Second | Megabytes/Second |
 93            Gigabytes/Second | Terabytes/Second | Bits/Second |
 94            Kilobits/Second | Megabits/Second | Gigabits/Second |
 95            Terabits/Second | Count/Second | None
 96
 97        :type period: integer
 98        :param period: The granularity, in seconds, of the returned datapoints.
 99            Period must be at least 60 seconds and must be a multiple
100            of 60. The default value is 60.
101
102        """
103        if not isinstance(statistics, list):
104            statistics = [statistics]
105        return self.connection.get_metric_statistics(period,
106                                                     start_time,
107                                                     end_time,
108                                                     self.name,
109                                                     self.namespace,
110                                                     statistics,
111                                                     self.dimensions,
112                                                     unit)
113
114    def create_alarm(self, name, comparison, threshold,
115                     period, evaluation_periods,
116                     statistic, enabled=True, description=None,
117                     dimensions=None, alarm_actions=None, ok_actions=None,
118                     insufficient_data_actions=None, unit=None):
119        """
120        Creates or updates an alarm and associates it with this metric.
121        Optionally, this operation can associate one or more
122        Amazon Simple Notification Service resources with the alarm.
123
124        When this operation creates an alarm, the alarm state is immediately
125        set to INSUFFICIENT_DATA. The alarm is evaluated and its StateValue is
126        set appropriately. Any actions associated with the StateValue is then
127        executed.
128
129        When updating an existing alarm, its StateValue is left unchanged.
130
131        :type alarm: boto.ec2.cloudwatch.alarm.MetricAlarm
132        :param alarm: MetricAlarm object.
133        """
134        if not dimensions:
135            dimensions = self.dimensions
136        alarm = MetricAlarm(self.connection, name, self.name,
137                            self.namespace, statistic, comparison,
138                            threshold, period, evaluation_periods,
139                            unit, description, dimensions,
140                            alarm_actions, insufficient_data_actions,
141                            ok_actions)
142        if self.connection.put_metric_alarm(alarm):
143            return alarm
144
145    def describe_alarms(self, period=None, statistic=None,
146                        dimensions=None, unit=None):
147        """
148        Retrieves all alarms for this metric. Specify a statistic, period,
149        or unit to filter the set of alarms further.
150
151        :type period: int
152        :param period: The period in seconds over which the statistic
153            is applied.
154
155        :type statistic: string
156        :param statistic: The statistic for the metric.
157
158        :param dimension_filters: A dictionary containing name/value
159            pairs that will be used to filter the results.  The key in
160            the dictionary is the name of a Dimension.  The value in
161            the dictionary is either a scalar value of that Dimension
162            name that you want to filter on, a list of values to
163            filter on or None if you want all metrics with that
164            Dimension name.
165
166        :type unit: string
167
168        :rtype list
169        """
170        return self.connection.describe_alarms_for_metric(self.name,
171                                                          self.namespace,
172                                                          period,
173                                                          statistic,
174                                                          dimensions,
175                                                          unit)