Add Factory Methods for Metric/Resource/Timeseries

Author: Bill Prin

gcloud/monitoring/client.py

@@ -28,14 +28,22 @@
     https://cloud.google.com/monitoring/api/v3/
 """
 
+import datetime
+
 from gcloud.client import JSONClient
 from gcloud.monitoring.connection import Connection
 from gcloud.monitoring.group import Group
+from gcloud.monitoring.metric import Metric
 from gcloud.monitoring.metric import MetricDescriptor
 from gcloud.monitoring.metric import MetricKind
 from gcloud.monitoring.metric import ValueType
 from gcloud.monitoring.query import Query
+from gcloud.monitoring.resource import Resource
 from gcloud.monitoring.resource import ResourceDescriptor
+from gcloud.monitoring.timeseries import Point
+from gcloud.monitoring.timeseries import TimeSeries
+
+_UTCNOW = datetime.datetime.utcnow  # To be replaced by tests.
 
 
 class Client(JSONClient):
@@ -195,6 +203,130 @@ def metric_descriptor(self, type_,
             display_name=display_name,
         )
 
+    @staticmethod
+    def metric(type_, labels):
+        """Construct a metric object.
+
+        The type of the Metric should match the type of a MetricDescriptor.
+        For a list of built-in Metric types and the associated labels, see:
+
+        https://cloud.google.com/monitoring/api/metrics
+
+        Here is an example of creating using a built-in metric type:
+
+             >>> type_ = 'compute.googleapis.com/instance/cpu/utilization'
+             >>> metric = client.metric(type_, labels={
+             ...    'instance_name': 'my-instance',
+             ... })
+
+        For custom metrics, the simplest way to get the type is from the
+        :class:`~gcloud.monitoring.metric.MetricDescriptor` class used to
+        create the custom metric::
+
+             >>> metric = client.metric(metric_descriptor.type, labels={
+             ...    'instance_name': 'my-instance',
+             ... })
+
+        :type type_: string
+        :param type_: The metric type name.
+
+        :type labels: dict
+        :param labels: A mapping from label names to values for all labels
+                       enumerated in the associated :class:`MetricDescriptor`.
+
+        :rtype: :class:`~gcloud.monitoring.metric.Metric`
+        :returns: The Metric created with the passed in arguments
+        """
+        return Metric(type=type_, labels=labels)
+
+    @staticmethod
+    def resource(type_, labels):
+        """Construct a resource object.
+
+        For a list of possible MonitoredResources and their associated labels,
+        see:
+
+        https://cloud.google.com/monitoring/api/resources
+
+        For example, to create a Resource object for a GCE instance::
+
+            >>> resource = client.resource('gce_instance', labels={
+            ...     'project_id': 'my-project-id',
+            ...     'instance_id': 'my-instance-id',
+            ...     'zone': 'us-central1-f'
+            ... })
+
+        :type type_: string
+        :param type_: The monitored resource type name.
+
+        :type labels: dict
+        :param labels: A mapping from label names to values for all labels
+                       enumerated in the associated
+                       :class:`ResourceDescriptor`.
+
+        :rtype: :class:`gcloud.resource.Resource`
+        :returns: The Resource created with the passed in arguments
+        """
+        return Resource(type_, labels)
+
+    @staticmethod
+    def timeseries(metric, resource, value,
+                   start_time=None, end_time=None):
+        """Constructs a TimeSeries object for a single data point.
+
+        .. note::
+
+           While TimeSeries objects returned by the API can have
+           multiple data points when queried as aggregates, TimeSeries created
+           on the client-side can have at most one point.
+
+        For example::
+
+            >>> timeseries = client.timeseries(metric, resource, value,
+            ...                                end_time=end)
+
+        For more information, see:
+
+        https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
+
+        :type metric: :class:`~gcloud.monitoring.metric.Metric`
+        :param metric: A metric object.
+
+        :type resource: :class:`~gcloud.monitoring.resource.Resource`
+        :param resource: A resource object.
+
+        :type value: bool, int, string, or float
+        :param value:
+            The value of the data point to create for the TimeSeries
+
+            .. note::
+
+               This parameter can be multiple types and the TypedValue of the
+               `gcloud.monitoring.TimeSeries.Point` will be mapped from the
+               type passed in. For example, a Python float will be sent to
+               the API as a doubleValue.
+
+        :type start_time: :class:`datetime.datetime`
+        :param start_time:
+            The start time for the point written to the
+            timeseries. Defaults to None, which has meaning dependent on the
+            metric_kind of the metric being written to.
+
+        :type end_time: :class`datetime.datetime`
+        :param end_time:
+            The end time for the point written to the timeseries. Defaults to
+            the current time, as obtained by calling
+            :meth:`datetime.datetime.utcnow`
+
+        :rtype: :class:`gcloud.timeseries.TimeSeries`
+        :returns: The TimeSeries created with the passed in arguments
+        """
+        if end_time is None:
+            end_time = _UTCNOW()
+        point = Point(value=value, start_time=start_time, end_time=end_time)
+        return TimeSeries(metric=metric, resource=resource, metric_kind=None,
+                          value_type=None, points=[point])
+
     def fetch_metric_descriptor(self, metric_type):
         """Look up a metric descriptor by type.
 

gcloud/monitoring/metric.py

@@ -319,6 +319,10 @@ def __repr__(self):
 class Metric(collections.namedtuple('Metric', 'type labels')):
     """A specific metric identified by specifying values for all labels.
 
+    The preferred way to construct a metric object is using the
+    :meth:`~gcloud.monitoring.client.Client.metric` factory method
+    of the :class:`~gcloud.monitoring.client.Client` class.
+
     :type type: string
     :param type: The metric type name.
 

gcloud/monitoring/resource.py

@@ -158,6 +158,10 @@ def __repr__(self):
 class Resource(collections.namedtuple('Resource', 'type labels')):
     """A monitored resource identified by specifying values for all labels.
 
+    The preferred way to construct a resource object is using the
+    :meth:`~gcloud.monitoring.client.Client.resource` factory method
+    of the :class:`~gcloud.monitoring.client.Client` class.
+
     :type type: string
     :param type: The resource type name.
 

gcloud/monitoring/test_client.py

@@ -157,6 +157,79 @@ def test_metric_descriptor_factory(self):
         self.assertEqual(descriptor.description, DESCRIPTION)
         self.assertEqual(descriptor.display_name, '')
 
+    def test_metric_factory(self):
+        TYPE = 'custom.googleapis.com/my_metric'
+        LABELS = {
+            'instance_name': 'my-instance'
+        }
+
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        client.connection = _Connection()   # For safety's sake.
+        metric = client.metric(TYPE, LABELS)
+        self.assertEqual(metric.type, TYPE)
+        self.assertEqual(metric.labels, LABELS)
+
+    def test_resource_factory(self):
+        TYPE = 'https://cloud.google.com/monitoring/api/resources'
+        LABELS = {
+            'project_id': 'my-project-id',
+            'instance_id': 'my-instance-id',
+            'zone': 'us-central1-f'
+        }
+
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        client.connection = _Connection()   # For safety's sake.
+        resource = client.resource(TYPE, LABELS)
+        self.assertEqual(resource.type, TYPE)
+        self.assertEqual(resource.labels, LABELS)
+
+    def test_timeseries_factory(self):
+        import datetime
+        from gcloud._testing import _Monkey
+        import gcloud.monitoring.client
+        METRIC_TYPE = 'custom.googleapis.com/my_metric'
+        METRIC_LABELS = {
+            'instance_name': 'my-instance'
+        }
+
+        RESOURCE_TYPE = 'https://cloud.google.com/monitoring/api/resources'
+        RESOURCE_LABELS = {
+            'project_id': 'my-project-id',
+            'instance_id': 'my-instance-id',
+            'zone': 'us-central1-f'
+        }
+
+        VALUE = 42
+
+        client = self._makeOne(project=PROJECT, credentials=_Credentials())
+        client.connection = _Connection()   # For safety's sake.
+        metric = client.metric(METRIC_TYPE, METRIC_LABELS)
+        resource = client.resource(RESOURCE_TYPE, RESOURCE_LABELS)
+        NOW = datetime.datetime.utcnow()
+        timeseries = client.timeseries(metric, resource, VALUE, end_time=NOW)
+
+        self.assertEqual(timeseries.metric, metric)
+        self.assertEqual(timeseries.resource, resource)
+        self.assertEqual(len(timeseries.points), 1)
+        self.assertEqual(timeseries.points[0].value, VALUE)
+        self.assertIsNone(timeseries.points[0].start_time)
+        self.assertEqual(timeseries.points[0].end_time, NOW)
+
+        NEW_NOW = datetime.datetime.utcnow()
+        timeseries_with_start = client.timeseries(metric,
+                                                  resource,
+                                                  VALUE,
+                                                  start_time=NOW,
+                                                  end_time=NEW_NOW)
+        self.assertEqual(timeseries_with_start.points[0].start_time, NOW)
+        self.assertEqual(timeseries_with_start.points[0].end_time, NEW_NOW)
+
+        with _Monkey(gcloud.monitoring.client, _UTCNOW=lambda: NOW):
+            timeseries_no_end = client.timeseries(metric, resource, VALUE)
+
+        self.assertEqual(timeseries_no_end.points[0].end_time, NOW)
+        self.assertIsNone(timeseries_no_end.points[0].start_time)
+
     def test_fetch_metric_descriptor(self):
         TYPE = 'custom.googleapis.com/my_metric'
         NAME = 'projects/{project}/metricDescriptors/{type}'.format(

gcloud/monitoring/timeseries.py

@@ -32,6 +32,10 @@ class TimeSeries(collections.namedtuple(
         'TimeSeries', 'metric resource metric_kind value_type points')):
     """A single time series of metric values.
 
+    The preferred way to construct a TimeSeries object is using the
+    :meth:`~gcloud.monitoring.client.Client.timeseries` factory method
+    of the :class:`~gcloud.monitoring.client.Client` class.
+
     :type metric: :class:`~gcloud.monitoring.metric.Metric`
     :param metric: A metric object.