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)