googleapis · rimey · May 2, 2016 · Apr 24, 2016
diff --git a/docs/monitoring-resource.rst b/docs/monitoring-resource.rst
@@ -1,5 +1,5 @@
-Resource Descriptors
-====================
+Monitored Resource Descriptors
+==============================
 
 .. automodule:: gcloud.monitoring.resource
   :members:

diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
@@ -24,8 +24,13 @@ Essential concepts:
 Please refer to the documentation for the `Monitoring API`_ for
 more information.
 
-At present, this client library supports querying of time series,
-metric descriptors, and resource descriptors.
+At present, this client library supports the following features
+of the API:
+
+- Querying of time series.
+- Querying of metric descriptors and monitored resource descriptors.
+- Creation and deletion of metric descriptors for custom metrics.
+- (Writing of custom metric data will be coming soon.)
 
 .. _Monitoring API: https://cloud.google.com/monitoring/api/v3/
 
@@ -101,6 +106,46 @@ You can list all of these with the
 See :class:`~gcloud.monitoring.metric.MetricDescriptor` and the
 `Metric Descriptors`_ API documentation for more information.
 
+You can create new metric descriptors to define custom metrics in
+the ``custom.googleapis.com`` namespace. You do this by creating a
+:class:`~gcloud.monitoring.metric.MetricDescriptor` object using the
+client's :meth:`~gcloud.monitoring.client.Client.metric_descriptor`
+factory and then calling the object's
+:meth:`~gcloud.monitoring.metric.MetricDescriptor.create` method::
+
+    >>> from gcloud.monitoring import MetricKind, ValueType
+    >>> descriptor = client.metric_descriptor(
+    ...     'custom.googleapis.com/my_metric',
+    ...     metric_kind=MetricKind.GAUGE,
+    ...     value_type=ValueType.DOUBLE,
+    ...     description='This is a simple example of a custom metric.')
+    >>> descriptor.create()
+
+You can delete such a metric descriptor as follows::
+
+    >>> descriptor = client.metric_descriptor(
+    ...     'custom.googleapis.com/my_metric')
+    >>> descriptor.delete()
+
+To define a custom metric parameterized by one or more labels,
+you must build the appropriate
+:class:`~gcloud.monitoring.label.LabelDescriptor` objects
+and include them in the
+:class:`~gcloud.monitoring.metric.MetricDescriptor` object
+before you call
+:meth:`~gcloud.monitoring.metric.MetricDescriptor.create`::
+
+    >>> from gcloud.monitoring import LabelDescriptor, LabelValueType
+    >>> label = LabelDescriptor('response_code', LabelValueType.INT64,
+    ...                         description='HTTP status code')
+    >>> descriptor = client.metric_descriptor(
+    ...     'custom.googleapis.com/my_app/response_count',
+    ...     metric_kind=MetricKind.CUMULATIVE,
+    ...     value_type=ValueType.INT64,
+    ...     labels=[label],
+    ...     description='Cumulative count of HTTP responses.')
+    >>> descriptor.create()
+
 .. _platform metrics: https://cloud.google.com/monitoring/api/metrics
 .. _agent metrics: https://cloud.google.com/monitoring/agent/
 .. _custom metrics: https://cloud.google.com/monitoring/custom-metrics/

diff --git a/gcloud/monitoring/client.py b/gcloud/monitoring/client.py
@@ -30,6 +30,8 @@
 from gcloud.client import JSONClient
 from gcloud.monitoring.connection import Connection
 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 ResourceDescriptor
 
@@ -60,7 +62,7 @@ def query(self,
               metric_type=Query.DEFAULT_METRIC_TYPE,
               end_time=None,
               days=0, hours=0, minutes=0):
-        """Construct a query object for listing time series.
+        """Construct a query object for retrieving metric data.
 
         Example::
 
@@ -112,6 +114,82 @@ def query(self,
                      end_time=end_time,
                      days=days, hours=hours, minutes=minutes)
 
+    def metric_descriptor(self, type_,
+                          metric_kind=MetricKind.METRIC_KIND_UNSPECIFIED,
+                          value_type=ValueType.VALUE_TYPE_UNSPECIFIED,
+                          labels=(), unit='', description='', display_name=''):
+        """Construct a metric descriptor object.
+
+        Metric descriptors specify the schema for a particular metric type.
+
+        This factory method is used most often in conjunction with the metric
+        descriptor :meth:`~gcloud.monitoring.metric.MetricDescriptor.create`
+        method to define custom metrics::
+
+            >>> descriptor = client.metric_descriptor(
+            ...     'custom.googleapis.com/my_metric',
+            ...     metric_kind=MetricKind.GAUGE,
+            ...     value_type=ValueType.DOUBLE,
+            ...     description='This is a simple example of a custom metric.')
+            >>> descriptor.create()
+
+        Here is an example where the custom metric is parameterized by a
+        metric label::
+
+            >>> label = LabelDescriptor('response_code', LabelValueType.INT64,
+            ...                         description='HTTP status code')
+            >>> descriptor = client.metric_descriptor(
+            ...     'custom.googleapis.com/my_app/response_count',
+            ...     metric_kind=MetricKind.CUMULATIVE,
+            ...     value_type=ValueType.INT64,
+            ...     labels=[label],
+            ...     description='Cumulative count of HTTP responses.')
+            >>> descriptor.create()
+
+        :type type_: string
+        :param type_:
+            The metric type including a DNS name prefix. For example:
+            ``"custom.googleapis.com/my_metric"``
+
+        :type metric_kind: string
+        :param metric_kind:
+            The kind of measurement. It must be one of
+            :data:`MetricKind.GAUGE`, :data:`MetricKind.DELTA`,
+            or :data:`MetricKind.CUMULATIVE`.
+            See :class:`~gcloud.monitoring.metric.MetricKind`.
+
+        :type value_type: string
+        :param value_type:
+            The value type of the metric. It must be one of
+            :data:`ValueType.BOOL`, :data:`ValueType.INT64`,
+            :data:`ValueType.DOUBLE`, :data:`ValueType.STRING`,
+            or :data:`ValueType.DISTRIBUTION`.
+            See :class:`ValueType`.
+
+        :type labels: list of :class:`~gcloud.monitoring.label.LabelDescriptor`
+        :param labels:
+            A sequence of zero or more label descriptors specifying the labels
+            used to identify a specific instance of this metric.
+
+        :type unit: string
+        :param unit: An optional unit in which the metric value is reported.
+
+        :type description: string
+        :param description: An optional detailed description of the metric.
+
+        :type display_name: string
+        :param display_name: An optional concise name for the metric.
+        """
+        return MetricDescriptor(
+            self, type_,
+            metric_kind=metric_kind,
+            value_type=value_type,
+            labels=labels,
+            unit=unit,
+            description=description,
+            display_name=display_name,
+        )
+
     def fetch_metric_descriptor(self, metric_type):
         """Look up a metric descriptor by type.
 
@@ -163,7 +241,7 @@ def list_metric_descriptors(self, filter_string=None, type_prefix=None):
                                       type_prefix=type_prefix)
 
     def fetch_resource_descriptor(self, resource_type):
-        """Look up a resource descriptor by type.
+        """Look up a monitored resource descriptor by type.
 
         Example::
 
@@ -181,7 +259,7 @@ def fetch_resource_descriptor(self, resource_type):
         return ResourceDescriptor._fetch(self, resource_type)
 
     def list_resource_descriptors(self, filter_string=None):
-        """List all resource descriptors for the project.
+        """List all monitored resource descriptors for the project.
 
         Example::
 

diff --git a/gcloud/monitoring/label.py b/gcloud/monitoring/label.py
@@ -48,7 +48,7 @@ class LabelDescriptor(object):
     :param description: A human-readable description for the label.
     """
 
-    def __init__(self, key, value_type, description):
+    def __init__(self, key, value_type=LabelValueType.STRING, description=''):
         self.key = key
         self.value_type = value_type
         self.description = description
@@ -70,6 +70,28 @@ def _from_dict(cls, info):
             info.get('description', ''),
         )
 
+    def _to_dict(self):
+        """Build a dictionary ready to be serialized to the JSON wire format.
+
+        :rtype: dict
+        :returns: A dictionary.
+        """
+        info = {
+            'key': self.key,
+            'valueType': self.value_type,
+        }
+
+        if self.description:
+            info['description'] = self.description
+
+        return info
+
+    def __eq__(self, other):
+        return self.__dict__ == other.__dict__
+
+    def __ne__(self, other):
+        return self.__dict__ != other.__dict__
+
     def __repr__(self):
         return (
             'LabelDescriptor(key={key!r}, value_type={value_type!r},'