Stackdriver Monitoring Client#

Client for interacting with the Google Stackdriver Monitoring API (V3).


>>> from import monitoring
>>> client = monitoring.Client()
>>> query = client.query(minutes=5)
>>> print(query.as_dataframe())  # Requires pandas.

At present, the client supports querying of time series, metric descriptors, and monitored resource descriptors.

class, credentials=None, http=None)[source]#


Client to bundle configuration needed for API requests.

  • project (string) – The target project. If not passed, falls back to the default inferred from the environment.
  • credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
  • http (httplib2.Http or class that defines request()) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.

Fetch a group from the API based on it’s ID.


>>> try:
>>>     group = client.fetch_group('1234')
>>> except
>>>     print('That group does not exist!')
Parameters:group_id (string) – The ID of the group.
Return type:Group
Returns:The group instance. if the group is not found.

Look up a metric descriptor by type.


>>> METRIC = ''
>>> print(client.fetch_metric_descriptor(METRIC))
Parameters:metric_type (string) – The metric type name.
Return type:MetricDescriptor
Returns:The metric descriptor instance. if the metric descriptor is not found.

Look up a monitored resource descriptor by type.


>>> print(client.fetch_resource_descriptor('gce_instance'))
Parameters:resource_type (string) – The resource type name.
Return type:ResourceDescriptor
Returns:The resource descriptor instance. if the resource descriptor is not found.
group(group_id=None, display_name=None, parent_id=None, filter_string=None, is_cluster=False)[source]#

Factory constructor for group object.


This will not make an HTTP request; it simply instantiates a group object owned by this client.

  • group_id (string or None) – The ID of the group.
  • display_name (string or None) – A user-assigned name for this group, used only for display purposes.
  • parent_id (string or None) – The ID of the group’s parent, if it has one.
  • filter_string (string or None) – The filter string used to determine which monitored resources belong to this group.
  • is_cluster (boolean) – If true, the members of this group are considered to be a cluster. The system can perform additional analysis on groups that are clusters.
Return type:



The group created with the passed-in arguments.


ValueError if both group_id and name are specified.


List all groups for the project.


>>> for group in client.list_groups():
...     print((group.display_name,
Return type:list of Group
Returns:A list of group instances.
list_metric_descriptors(filter_string=None, type_prefix=None)[source]#

List all metric descriptors for the project.


>>> for descriptor in client.list_metric_descriptors():
...     print(descriptor.type)

>>> for descriptor in client.list_metric_descriptors(
...         type_prefix='custom.'):
...     print(descriptor.type)
  • filter_string (string or None) – An optional filter expression describing the metric descriptors to be returned. See the filter documentation.
  • type_prefix (string or None) – An optional prefix constraining the selected metric types. This adds metric.type = starts_with("<prefix>") to the filter.
Return type:

list of MetricDescriptor


A list of metric descriptor instances.


List all monitored resource descriptors for the project.


>>> for descriptor in client.list_resource_descriptors():
...     print(descriptor.type)
Parameters:filter_string (string or None) – An optional filter expression describing the resource descriptors to be returned. See the filter documentation.
Return type:list of ResourceDescriptor
Returns:A list of resource descriptor instances.
static metric(type_, labels)[source]#

Factory for constructing metric objects.

Metric objects are typically created to write custom metric values. The type should match the metric type specified in the MetricDescriptor used to create the custom metric:

>>> metric = client.metric('',
...                        labels={
...                            'status': 'successful',
...                         })
  • type (string) – The metric type name.
  • labels (dict) – A mapping from label names to values for all labels enumerated in the associated MetricDescriptor.
Return type:



The metric object.

metric_descriptor(type_, metric_kind='METRIC_KIND_UNSPECIFIED', value_type='VALUE_TYPE_UNSPECIFIED', labels=(), unit='', description='', display_name='')[source]#

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 create() method to define custom metrics:

>>> descriptor = client.metric_descriptor(
...     '',
...     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(
...     '',
...     metric_kind=MetricKind.CUMULATIVE,
...     value_type=ValueType.INT64,
...     labels=[label],
...     description='Cumulative count of HTTP responses.')
>>> descriptor.create()
  • type (string) – The metric type including a DNS name prefix. For example: ""
  • metric_kind (string) – The kind of measurement. It must be one of MetricKind.GAUGE, MetricKind.DELTA, or MetricKind.CUMULATIVE. See MetricKind.
  • value_type (string) – The value type of the metric. It must be one of ValueType.BOOL, ValueType.INT64, ValueType.DOUBLE, ValueType.STRING, or ValueType.DISTRIBUTION. See ValueType.
  • labels (list of LabelDescriptor) – A sequence of zero or more label descriptors specifying the labels used to identify a specific instance of this metric.
  • unit (string) – An optional unit in which the metric value is reported.
  • description (string) – An optional detailed description of the metric.
  • display_name (string) – An optional concise name for the metric.
Return type:



The metric descriptor created with the passed-in arguments.

query(metric_type='', end_time=None, days=0, hours=0, minutes=0)[source]#

Construct a query object for retrieving metric data.


>>> query = client.query(minutes=5)
>>> print(query.as_dataframe())  # Requires pandas.
  • metric_type (string) – The metric type name. The default value is Query.DEFAULT_METRIC_TYPE, but please note that this default value is provided only for demonstration purposes and is subject to change. See the supported metrics.
  • end_time (datetime.datetime or None) –

    The end time (inclusive) of the time interval for which results should be returned, as a datetime object. The default is the start of the current minute.

    The start time (exclusive) is determined by combining the values of days, hours, and minutes, and subtracting the resulting duration from the end time.

    It is also allowed to omit the end time and duration here, in which case select_interval() must be called before the query is executed.

  • days (integer) – The number of days in the time interval.
  • hours (integer) – The number of hours in the time interval.
  • minutes (integer) – The number of minutes in the time interval.
Return type:



The query object.


ValueError if end_time is specified but days, hours, and minutes are all zero. If you really want to specify a point in time, use select_interval().

static resource(type_, labels)[source]#

Factory for constructing monitored resource objects.

A monitored resource object ( Resource) is typically used to create a TimeSeries object.

For a list of possible monitored resource types and their associated labels, see:

  • type (string) – The monitored resource type name.
  • labels (dict) – A mapping from label names to values for all labels enumerated in the associated ResourceDescriptor, except that project_id can and should be omitted when writing time series data.
Return type:



A monitored resource object.

static time_series(metric, resource, value, end_time=None, start_time=None)[source]#

Construct a time series object for a single data point.


While TimeSeries objects returned by the API typically have multiple data points, TimeSeries objects sent to the API must have at most one point.

For example:

>>> timeseries = client.time_series(metric, resource, 1.23,
...                                 end_time=end)

For more information, see:

  • metric (Metric) – A Metric.
  • resource (Resource) – A Resource object.
  • value (bool, int, string, or float) –

    The value of the data point to create for the TimeSeries.


    The Python type of the value will determine the ValueType sent to the API, which must match the value type specified in the metric descriptor. For example, a Python float will be sent to the API as a ValueType.DOUBLE.

  • end_time (datetime) – The end time for the point to be included in the time series. Assumed to be UTC if no time zone information is present. Defaults to the current time, as obtained by calling datetime.datetime.utcnow().
  • start_time (datetime) – The start time for the point to be included in the time series. Assumed to be UTC if no time zone information is present Defaults to None. If the start time is unspecified, the API interprets the start time to be the same as the end time.
Return type:



A time series object.


Create / interact with Stackdriver Monitoring connections.

class, http=None)[source]#


A connection to Google Stackdriver Monitoring via the JSON REST API.


The base of the API call URL.

API_URL_TEMPLATE = '{api_base_url}/{api_version}{path}'#

A template for the URL of a particular API call.


The version of the API, used in building the API call’s URL.

SCOPE = ('', '', '')#

The scopes required for authenticating as a Monitoring consumer.