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.exists():

>>> 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(descriptor=metric_descriptor, labels={

... 'response_code': 404

... })

It's also possible to assign labels to Metrics and Resources with keyword arguments::

>>> metric = client.metric(descriptor=metric_descriptor, 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 specified, the :class:`~gcloud.monitoring.timeseries.MetricStream`

can be used to write :class:`~gcloud.monitoring.timeseries.Point` values.

:class:`~gcloud.monitoring.timeseries.MetricStream` is a helper class that helps create

:class:`~gcloud.monitoring.timeseries.TimeSeries` objects with the same Metric and Resource types.

When writing points with :class:`~gcloud.monitoring.timeseries.MetricStream`, you specify

points containing a value of the type that matches the *value_type* specified in the associated

:class:`~gcloud.monitoring.metric.MetricDescriptor`. The point must also contain a time interval.

The point's time interval must be later than any points already created for the same

:class:`~gcloud.monitoring.timeseries.TimeSeries`

(where :class:`~gcloud.monitoring.timeseries.TimeSeries` with matching :class:`~gcloud.monitoring.metric.Metric` and :class:`~gcloud.monitoring.resource.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::

Stackdriver Monitoring supports several **value types**. A *CUMULATIVE* metric represents a value

over time. Successive points in a :class:`~gcloud.monitoring.timeseries.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::

By default, end_time defaults to :meth:`~datetime.datetime.utcnow()`, so metrics written for the

can be simplified to::

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.

>>> metric_stream.write_point(value, start_time=start_time) # API call

As an alternative to :class:`~gcloud.monitoring.timeseries.MetricStream`, 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::

or be used in :meth:`~gcloud.monitoring.client.write_time_series`::

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