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 unit: string
81        :param unit: The unit for the metric.  Value values are:
82            Seconds | Microseconds | Milliseconds | Bytes | Kilobytes |
83            Megabytes | Gigabytes | Terabytes | Bits | Kilobits |
84            Megabits | Gigabits | Terabits | Percent | Count |
85            Bytes/Second | Kilobytes/Second | Megabytes/Second |
86            Gigabytes/Second | Terabytes/Second | Bits/Second |
87            Kilobits/Second | Megabits/Second | Gigabits/Second |
88            Terabits/Second | Count/Second | None
89
90        :type period: integer
91        :param period: The granularity, in seconds, of the returned datapoints.
92            Period must be at least 60 seconds and must be a multiple
93            of 60. The default value is 60.
94
95        """
96        if not isinstance(statistics, list):
97            statistics = [statistics]
98        return self.connection.get_metric_statistics(period,
99                                                     start_time,
100                                                     end_time,
101                                                     self.name,
102                                                     self.namespace,
103                                                     statistics,
104                                                     self.dimensions,
105                                                     unit)
106
107    def create_alarm(self, name, comparison, threshold,
108                     period, evaluation_periods,
109                     statistic, enabled=True, description=None,
110                     dimensions=None, alarm_actions=None, ok_actions=None,
111                     insufficient_data_actions=None, unit=None):
112        """
113        Creates or updates an alarm and associates it with this metric.
114        Optionally, this operation can associate one or more
115        Amazon Simple Notification Service resources with the alarm.
116
117        When this operation creates an alarm, the alarm state is immediately
118        set to INSUFFICIENT_DATA. The alarm is evaluated and its StateValue is
119        set appropriately. Any actions associated with the StateValue is then
120        executed.
121
122        When updating an existing alarm, its StateValue is left unchanged.
123
124        :type alarm: boto.ec2.cloudwatch.alarm.MetricAlarm
125        :param alarm: MetricAlarm object.
126        """
127        if not dimensions:
128            dimensions = self.dimensions
129        alarm = MetricAlarm(self.connection, name, self.name,
130                            self.namespace, statistic, comparison,
131                            threshold, period, evaluation_periods,
132                            unit, description, dimensions,
133                            alarm_actions, insufficient_data_actions,
134                            ok_actions)
135        if self.connection.put_metric_alarm(alarm):
136            return alarm
137
138    def describe_alarms(self, period=None, statistic=None,
139                        dimensions=None, unit=None):
140        """
141        Retrieves all alarms for this metric. Specify a statistic, period,
142        or unit to filter the set of alarms further.
143
144        :type period: int
145        :param period: The period in seconds over which the statistic
146            is applied.
147
148        :type statistic: string
149        :param statistic: The statistic for the metric.
150
151        :param dimension_filters: A dictionary containing name/value
152            pairs that will be used to filter the results.  The key in
153            the dictionary is the name of a Dimension.  The value in
154            the dictionary is either a scalar value of that Dimension
155            name that you want to filter on, a list of values to
156            filter on or None if you want all metrics with that
157            Dimension name.
158
159        :type unit: string
160
161        :rtype list
162        """
163        return self.connection.describe_alarms_for_metric(self.name,
164                                                          self.namespace,
165                                                          period,
166                                                          statistic,
167                                                          dimensions,
168                                                          unit)
169