Add Group support to the Monitoring API

docs/index.rst

@@ -128,6 +128,7 @@
   Client <monitoring-client>
   monitoring-metric
   monitoring-resource
+  monitoring-group
   monitoring-query
   monitoring-timeseries
   monitoring-label

docs/monitoring-group.rst

@@ -0,0 +1,7 @@
+Groups
+======
+
+.. automodule:: gcloud.monitoring.group
+  :members:
+  :show-inheritance:
+

docs/monitoring-usage.rst

@@ -154,6 +154,86 @@ before you call
     projects.metricDescriptors
 
 
+Groups
+------
+
+A group is a dynamic collection of *monitored resources* whose membership is
+defined by a `filter`_.  These groups are usually created via the
+`Stackdriver dashboard`_. You can list all the groups in a project with the
+:meth:`~gcloud.monitoring.client.Client.list_groups` method::
+
+    >>> for group in client.list_groups():
+    ...     print(group.id, group.display_name, group.parent_id)
+    ('a001', 'Production', None)
+    ('a002', 'Front-end', 'a001')
+    ('1003', 'Back-end', 'a001')
+
+See :class:`~gcloud.monitoring.group.Group` and the API documentation for
+`Groups`_ and `Group members`_ for more information.
+
+You can get a specific group based on it's ID as follows::
+
+    >>> group = client.fetch_group('a001')
+
+You can get the current members of this group using the
+:meth:`~gcloud.monitoring.group.Group.list_members` method::
+
+    >>> for member in group.list_members():
+    ...     print(member)
+
+Passing in ``end_time`` and ``start_time`` to the above method will return
+historical members based on the current filter of the group. The group
+membership changes over time, as *monitored resources* come and go, and as they
+change properties.
+
+You can create new groups to define new collections of *monitored resources*.
+You do this by creating a :class:`~gcloud.monitoring.group.Group` object using
+the client's :meth:`~gcloud.monitoring.client.Client.group` factory and then
+calling the object's :meth:`~gcloud.monitoring.group.Group.create` method::
+
+    >>> filter_string = 'resource.zone = "us-central1-a"'
+    >>> group = client.group(
+    ...     display_name='My group',
+    ...     filter_string=filter_string,
+    ...     parent_id='a001',
+    ...     is_cluster=True)
+    >>> group.create()
+    >>> group.id
+    '1234'
+
+You can further manipulate an existing group by first initializing a Group
+object with it's ID or name, and then calling various methods on it.
+
+Delete a group::
+
+    >>> group = client.group('1234')
+    >>> group.exists()
+    True
+    >>> group.delete()
+
+
+Update a group::
+
+    >>> group = client.group('1234')
+    >>> group.exists()
+    True
+    >>> group.reload()
+    >>> group.display_name = 'New Display Name'
+    >>> group.update()
+
+.. _Stackdriver dashboard:
+    https://support.stackdriver.com/customer/portal/articles/\
+    1535145-creating-groups
+.. _filter:
+    https://cloud.google.com/monitoring/api/v3/filters#group-filter
+.. _Groups:
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.groups
+.. _Group members:
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.groups.members
+
+
 Time Series Queries
 -------------------
 

gcloud/monitoring/__init__.py

@@ -16,6 +16,7 @@
 
 from gcloud.monitoring.client import Client
 from gcloud.monitoring.connection import Connection
+from gcloud.monitoring.group import Group
 from gcloud.monitoring.label import LabelDescriptor
 from gcloud.monitoring.label import LabelValueType
 from gcloud.monitoring.metric import Metric
@@ -33,6 +34,7 @@
 __all__ = (
     'Client',
     'Connection',
+    'Group',
     'LabelDescriptor', 'LabelValueType',
     'Metric', 'MetricDescriptor', 'MetricKind', 'ValueType',
     'Aligner', 'Query', 'Reducer',

gcloud/monitoring/client.py

@@ -30,6 +30,7 @@
 
 from gcloud.client import JSONClient
 from gcloud.monitoring.connection import Connection
+from gcloud.monitoring.group import Group
 from gcloud.monitoring.metric import MetricDescriptor
 from gcloud.monitoring.metric import MetricKind
 from gcloud.monitoring.metric import ValueType
@@ -282,3 +283,82 @@ def list_resource_descriptors(self, filter_string=None):
             https://cloud.google.com/monitoring/api/v3/filters
         """
         return ResourceDescriptor._list(self, filter_string)
+
+    def group(self, group_id=None, display_name=None, parent_id=None,
+              filter_string=None, is_cluster=False):
+        """Factory constructor for group object.
+
+        .. note::
+          This will not make an HTTP request; it simply instantiates
+          a group object owned by this client.
+
+        :type group_id: string or None
+        :param group_id: The ID of the group.
+
+        :type display_name: string or None
+        :param display_name:
+            A user-assigned name for this group, used only for display
+            purposes.
+
+        :type parent_id: string or None
+        :param parent_id:
+            The ID of the group's parent, if it has one.
+
+        :type filter_string: string or None
+        :param filter_string:
+            The filter string used to determine which monitored resources
+            belong to this group.
+
+        :type is_cluster: boolean
+        :param is_cluster:
+            If true, the members of this group are considered to be a cluster.
+            The system can perform additional analysis on groups that are
+            clusters.
+
+        :rtype: :class:`Group`
+        :returns: The group created with the passed-in arguments.
+
+        :raises:
+            :exc:`ValueError` if both ``group_id`` and ``name`` are specified.
+        """
+        return Group(
+            self,
+            group_id=group_id,
+            display_name=display_name,
+            parent_id=parent_id,
+            filter_string=filter_string,
+            is_cluster=is_cluster,
+        )
+
+    def fetch_group(self, group_id):
+        """Fetch a group from the API based on it's ID.
+
+        Example::
+
+            >>> try:
+            >>>     group = client.fetch_group('1234')
+            >>> except gcloud.exceptions.NotFound:
+            >>>     print('That group does not exist!')
+
+        :type group_id: string
+        :param group_id: The ID of the group.
+
+        :rtype: :class:`~gcloud.monitoring.group.Group`
+        :returns: The group instance.
+
+        :raises: :class:`gcloud.exceptions.NotFound` if the group is not found.
+        """
+        return Group._fetch(self, group_id)
+
+    def list_groups(self):
+        """List all groups for the project.
+
+        Example::
+
+            >>> for group in client.list_groups():
+            ...     print((group.display_name, group.name))
+
+        :rtype: list of :class:`~gcloud.monitoring.group.Group`
+        :returns: A list of group instances.
+        """
+        return Group._list(self)