Monitoring Custom Metric Usage

Bill Prin · Bill Prin · commit 25573ea6f961 · 2016-08-04T15:19:16.000-07:00
diff --git a/docs/monitoring-usage.rst b/docs/monitoring-usage.rst
@@ -278,3 +278,111 @@ follows::
 
 .. _Time Series:
     https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
+
+
+Writing Custom Time Series
+---------------------------
+
+The Stackdriver Monitoring API can be used to create and delete custom metrics, as well as write
+data points to them. Please refer to the documentation for the `Creating Custom Metrics`_
+documentation for more information.
+
+
+To create a custom TimeSeries value, you must first create a custom
+:class:`~gcloud.monitoring.metric.MetricDescriptor` object, and then use its
+type to create a fully parametrized :class:`~gcloud.monitoring.metric.Metric` by providing specific
+values for the available labels. You must create a fully parametrized  :class:`~gcloud.monitoring.resource.Resource` from one of the
+available ResourceDescriptors which can be listed using the :class:`~gcloud.monitoring.resource.ResourceDescriptor` class,
+which similarly requires that its available labels have values specified.
+
+>>> from gcloud import monitoring
+>>> import datetime
+>>> client = monitoring.Client()
+>>> label = LabelDescriptor('response_code', LabelValueType.INT64,
+    ...                         description='HTTP status code')
+>>> metric_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.')
+>>> if not metric_descriptor.exist():
+>>>     metric_descriptor.create()
+>>> # Create a Resource by its resource name, assign labels as dict
+>>> resource = client.resource('gce_instance',
+...                            labels={
+...                                'instance_id': 'my-instance',
+...                                'zone': 'us-central1-f'
+...                             })
+>>> # Create a Metric using its metric descriptor parametrized with labels
+>>> metric = client.metric(type=metric_descriptor.type, labels={
+...                                              'response_code': 404
+...                                               }
+
+It's also possible to assign labels to Metrics and Resources with keyword arguments::
+
+>>> metric = client.metric(type=metric_descriptor.type, response_code=404)
+>>> resource = client.resource('gce_instance', instance_id='my-instance', zone='us-central1-f')
+
+Please refer to the `Metrics`_ documentation for more information.
+
+With a Metric and Resource created, the :class:`~gcloud.monitoring.timeseries.TimeSeries`
+can be used to write  :class:`~gcloud.monitoring.timeseries.Point` values.
+
+When creating :class:`~gcloud.monitoring.timeseries.TimeSeries`, you specify points containing a
+value of the type that matches the *value_type* specified in the associated `MetricDescriptor`.
+The point must also contain a time interval. The point's time interval must be later than any
+points already created for the :class:`~gcloud.monitoring.timeseries.TimeSeries` (where
+TimeSeries with matching `Metric` and `Resource` types are considered the same). The end time of
+the interval must not be more than 24 hours in
+ the past or more than five minutes in the future::
+
+    >>> start = datetime.now()
+    >>> end = datetime.now() - datetime.timedelta(minutes=5)
+    >>> value = get_num_404s_in_last_five_minutes() # get value from a hypothetical call
+    >>>
+    >>> client.write_timeseries(value, start_time=start, end_time=end,
+    ...                         metric=metric, resource=resource) # API call
+
+You can also use the :class:`~gcloud.monitoring.TimeseriesWriter` class to
+associate a fully specified Metric and Resource pair to write :class:`~gcloud.monitoring.timeseries.TimeSeries` together::
+
+    >>> timeseries_writer = client.get_timeseries_writer(metric, resource)
+    >>> timeseries_writer.write_point(value, start_time=start, end_time=end) # API call
+
+Stackdriver Monitoring supports several **value types**. A *CUMULATIVE* metric represents a value
+over time. Successive points in a TimeSeries should have the same start time and increasing
+end times, until an event resets the cumulative value to zero and sets a new start time for
+the follow points.
+
+For *GAUGE* metrics, the time intervals a single point in time, so only the end_time should be
+specified::
+
+    >>> timeseries_writer.write_point(value, end_time=end) # API call
+
+By default, end_time defaults to :meth:`~datetime.datetime.utcnow()`, so metrics written for the
+can be simplified to::
+
+   >>> timeseries_writer.write_point(value) # API call
+
+For *DELTA* metrics, the points reflect a change during a finite time interval, so both start_time
+and end_time should be specified, though end_time again defaults to the current time.
+
+    >>> timeseries_writer.write_point(value, start_time=start_time) # API call
+
+It's also possible to have the :class:`gcloud.monitoring.client.Client` return a
+:class:`gcloud.monitoring.timeseries.TimeSeries` object, which can then written later::
+
+    >>> ts1 = client.timeseries(value, end_time=end_time, metric=metric1, resource=resource1)
+    >>> ts1.create()
+
+or be used in :meth:`~gcloud.monitoring.client.write_time_series`::
+
+    >>> ts1 = client.timeseries(value, end_time=end_time, metric=metric1, resource=resource1)
+    >>> ts2 = client.timeseries(value2, end_time=end_time2, metric=metric2, resource=resource2)
+    >>> client.write_time_series([ts1, ts2])
+
+All timezone-naive Python datetimes are assumed to be UTC.
+
+.. _Creating Custom Metrics: https://cloud.google.com/monitoring/custom-metrics/creating-metrics
+.. _Metrics: https://cloud.google.com/monitoring/api/v3/metrics
