Version History (0.17.0)
Report an Issue

Monitoring Client#

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

Example:

>>> from gcloud 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 gcloud.monitoring.client.Client(project=None, credentials=None, http=None)[source]#

Bases: gcloud.client.JSONClient

Client to bundle configuration needed for API requests.

Parameters:
  • 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_metric_descriptor(metric_type)[source]#

Look up a metric descriptor by type.

Example:

>>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
>>> print(client.fetch_metric_descriptor(METRIC))
Parameters:metric_type (string) – The metric type name.
Return type:MetricDescriptor
Returns:The metric descriptor instance.
Raises:gcloud.exceptions.NotFound if the metric descriptor is not found.
fetch_resource_descriptor(resource_type)[source]#

Look up a monitored resource descriptor by type.

Example:

>>> print(client.fetch_resource_descriptor('gce_instance'))
Parameters:resource_type (string) – The resource type name.
Return type:ResourceDescriptor
Returns:The resource descriptor instance.
Raises:gcloud.exceptions.NotFound if the resource descriptor is not found.
list_metric_descriptors(filter_string=None, type_prefix=None)[source]#

List all metric descriptors for the project.

Examples:

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

>>> for descriptor in client.list_metric_descriptors(
...         type_prefix='custom.'):
...     print(descriptor.type)
Parameters:
  • 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
Returns:

A list of metric descriptor instances.
list_resource_descriptors(filter_string=None)[source]#

List all monitored resource descriptors for the project.

Example:

>>> 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.
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(
...     '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()
Parameters:
  • type (string) – The metric type including a DNS name prefix. For example: "custom.googleapis.com/my_metric"
  • 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.
query(metric_type='compute.googleapis.com/instance/cpu/utilization', end_time=None, days=0, hours=0, minutes=0)[source]#

Construct a query object for retrieving metric data.

Example:

>>> query = client.query(minutes=5)
>>> print(query.as_dataframe())  # Requires pandas.
Parameters:
  • 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:

Query
Returns:

The query object.
Raises:

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

Connection#

Create / interact with gcloud monitoring connections.

class gcloud.monitoring.connection.Connection(credentials=None, http=None)[source]#

Bases: gcloud.connection.JSONConnection

A connection to Google Monitoring via the JSON REST API.

Parameters:
API_BASE_URL = 'https://monitoring.googleapis.com'#

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.

API_VERSION = 'v3'#

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

SCOPE = ('https://www.googleapis.com/auth/monitoring.read', 'https://www.googleapis.com/auth/monitoring', 'https://www.googleapis.com/auth/cloud-platform')#

The scopes required for authenticating as a Monitoring consumer.