def __init__(self, project=None, credentials=None, http=None):
super(Client, self).__init__(project=project,
credentials=credentials,
http=http)
self._connection = Connection(credentials=self._credentials,
http=self._http)
def __init__(self, project=None, credentials=None, http=None):
super(Client, self).__init__(
project=project, credentials=credentials, http=http)
self._connection = Connection(
credentials=self._credentials, http=self._http)
class Client(ClientWithProject):
"""Client to bundle configuration needed for API requests.
:type project: str
:param project: The target project. If not passed, falls back to the
default inferred from the environment.
:type credentials: :class:`~google.auth.credentials.Credentials`
:param credentials: (Optional) The OAuth2 Credentials to use for this
client. If not passed (and if no ``http`` object is
passed), falls back to the default inferred from the
environment.
:type http: :class:`~httplib2.Http`
:param http: (Optional) HTTP object to make requests. Can be any object
that defines ``request()`` with the same interface as
:meth:`~httplib2.Http.request`. If not passed, an
``http`` object is created that is bound to the
``credentials`` for the current object.
"""
def __init__(self, project=None, credentials=None, http=None):
super(Client, self).__init__(project=project,
credentials=credentials,
http=http)
self._connection = Connection(credentials=self._credentials,
http=self._http)
def query(self,
metric_type=Query.DEFAULT_METRIC_TYPE,
end_time=None,
days=0,
hours=0,
minutes=0):
"""Construct a query object for retrieving metric data.
Example::
>>> query = client.query(minutes=5)
>>> print(query.as_dataframe()) # Requires pandas.
:type metric_type: str
:param metric_type: The metric type name. The default value is
:data:`Query.DEFAULT_METRIC_TYPE
<google.cloud.monitoring.query.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`_.
:type end_time: :class:`datetime.datetime`
:param end_time:
(Optional) 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
:meth:`~google.cloud.monitoring.query.Query.select_interval`
must be called before the query is executed.
:type days: int
:param days: The number of days in the time interval.
:type hours: int
:param hours: The number of hours in the time interval.
:type minutes: int
:param minutes: The number of minutes in the time interval.
:rtype: :class:`~google.cloud.monitoring.query.Query`
:returns: The query object.
:raises: :exc:`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
:meth:`~google.cloud.monitoring.query.Query.select_interval`.
.. _supported metrics: https://cloud.google.com/monitoring/api/metrics
"""
return Query(self,
metric_type,
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:`~google.cloud.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_: str
:param type_:
The metric type including a DNS name prefix. For example:
``"custom.googleapis.com/my_metric"``
:type metric_kind: str
:param metric_kind:
The kind of measurement. It must be one of
:data:`MetricKind.GAUGE`, :data:`MetricKind.DELTA`,
or :data:`MetricKind.CUMULATIVE`.
See :class:`~google.cloud.monitoring.metric.MetricKind`.
:type value_type: str
: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:`~google.cloud.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: str
:param unit: An optional unit in which the metric value is reported.
:type description: str
:param description: An optional detailed description of the metric.
:type display_name: str
:param display_name: An optional concise name for the metric.
:rtype: :class:`MetricDescriptor`
:returns: The metric descriptor created with the passed-in arguments.
"""
return MetricDescriptor(
self,
type_,
metric_kind=metric_kind,
value_type=value_type,
labels=labels,
unit=unit,
description=description,
display_name=display_name,
)
@staticmethod
def metric(type_, labels):
"""Factory for constructing metric objects.
:class:`~google.cloud.monitoring.metric.Metric` objects are typically
created to write custom metric values. The type should match the
metric type specified in the
:class:`~google.cloud.monitoring.metric.MetricDescriptor` used to
create the custom metric::
>>> metric = client.metric('custom.googleapis.com/my_metric',
... labels={
... 'status': 'successful',
... })
:type type_: str
:param type_: The metric type name.
:type labels: dict
:param labels: A mapping from label names to values for all labels
enumerated in the associated
:class:`~.metric.MetricDescriptor`.
:rtype: :class:`~google.cloud.monitoring.metric.Metric`
:returns: The metric object.
"""
return Metric(type=type_, labels=labels)
@staticmethod
def resource(type_, labels):
"""Factory for constructing monitored resource objects.
A monitored resource object (
:class:`~google.cloud.monitoring.resource.Resource`) is
typically used to create a
:class:`~google.cloud.monitoring.timeseries.TimeSeries` object.
For a list of possible monitored resource types and their associated
labels, see:
https://cloud.google.com/monitoring/api/resources
:type type_: str
:param type_: The monitored resource type name.
:type labels: dict
:param labels: A mapping from label names to values for all labels
enumerated in the associated
:class:`~.resource.ResourceDescriptor`,
except that ``project_id`` can and should be omitted
when writing time series data.
:rtype: :class:`~google.cloud.monitoring.resource.Resource`
:returns: A monitored resource object.
"""
return Resource(type_, labels)
@staticmethod
def time_series(metric, resource, value, end_time=None, start_time=None):
"""Construct a time series object for a single data point.
.. note::
While :class:`~google.cloud.monitoring.timeseries.TimeSeries`
objects returned by the API typically have multiple data points,
:class:`~google.cloud.monitoring.timeseries.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:
https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
:type metric: :class:`~google.cloud.monitoring.metric.Metric`
:param metric: A :class:`~google.cloud.monitoring.metric.Metric`.
:type resource: :class:`~google.cloud.monitoring.resource.Resource`
:param resource: A :class:`~google.cloud.monitoring.resource.Resource`
object.
:type value: bool, int, string, or float
:param value:
The value of the data point to create for the
:class:`~google.cloud.monitoring.timeseries.TimeSeries`.
.. note::
The Python type of the value will determine the
:class:`~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 :data:`ValueType.DOUBLE`.
:type end_time: :class:`~datetime.datetime`
:param end_time:
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
:meth:`datetime.datetime.utcnow`.
:type start_time: :class:`~datetime.datetime`
:param start_time:
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.
:rtype: :class:`~google.cloud.monitoring.timeseries.TimeSeries`
:returns: A time series object.
"""
if end_time is None:
end_time = _UTCNOW()
end_time = _datetime_to_rfc3339(end_time, ignore_zone=False)
if start_time:
start_time = _datetime_to_rfc3339(start_time, ignore_zone=False)
point = Point(value=value, start_time=start_time, end_time=end_time)
return TimeSeries(metric=metric,
resource=resource,
metric_kind=None,
value_type=None,
points=[point])
def fetch_metric_descriptor(self, metric_type):
"""Look up a metric descriptor by type.
Example::
>>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
>>> print(client.fetch_metric_descriptor(METRIC))
:type metric_type: str
:param metric_type: The metric type name.
:rtype: :class:`~google.cloud.monitoring.metric.MetricDescriptor`
:returns: The metric descriptor instance.
:raises: :class:`google.cloud.exceptions.NotFound` if the metric
descriptor is not found.
"""
return MetricDescriptor._fetch(self, metric_type)
def list_metric_descriptors(self, filter_string=None, type_prefix=None):
"""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)
:type filter_string: str
:param filter_string:
(Optional) An optional filter expression describing the metric
descriptors to be returned. See the `filter documentation`_.
:type type_prefix: str
:param type_prefix:
(Optional) An optional prefix constraining the selected metric
types. This adds ``metric.type = starts_with("<prefix>")`` to the
filter.
:rtype:
list of :class:`~google.cloud.monitoring.metric.MetricDescriptor`
:returns: A list of metric descriptor instances.
.. _filter documentation:
https://cloud.google.com/monitoring/api/v3/filters
"""
return MetricDescriptor._list(self,
filter_string,
type_prefix=type_prefix)
def fetch_resource_descriptor(self, resource_type):
"""Look up a monitored resource descriptor by type.
Example::
>>> print(client.fetch_resource_descriptor('gce_instance'))
:type resource_type: str
:param resource_type: The resource type name.
:rtype: :class:`~google.cloud.monitoring.resource.ResourceDescriptor`
:returns: The resource descriptor instance.
:raises: :class:`google.cloud.exceptions.NotFound` if the resource
descriptor is not found.
"""
return ResourceDescriptor._fetch(self, resource_type)
def list_resource_descriptors(self, filter_string=None):
"""List all monitored resource descriptors for the project.
Example::
>>> for descriptor in client.list_resource_descriptors():
... print(descriptor.type)
:type filter_string: str
:param filter_string:
(Optional) An optional filter expression describing the resource
descriptors to be returned. See the `filter documentation`_.
:rtype: list of
:class:`~google.cloud.monitoring.resource.ResourceDescriptor`
:returns: A list of resource descriptor instances.
.. _filter documentation:
https://cloud.google.com/monitoring/api/v3/filters
"""
return ResourceDescriptor._list(self, filter_string)
def group(self,
group_id=None,
display_name=None,
parent_id=None,
filter_string=None,
is_cluster=False):
"""Factory constructor for group object.
.. note::
This will not make an HTTP request; it simply instantiates
a group object owned by this client.
:type group_id: str
:param group_id: (Optional) The ID of the group.
:type display_name: str
:param display_name:
(Optional) A user-assigned name for this group, used only for
display purposes.
:type parent_id: str
:param parent_id:
(Optional) The ID of the group's parent, if it has one.
:type filter_string: str
:param filter_string:
(Optional) The filter string used to determine which monitored
resources belong to this group.
:type is_cluster: bool
:param is_cluster:
If true, the members of this group are considered to be a cluster.
The system can perform additional analysis on groups that are
clusters.
:rtype: :class:`Group`
:returns: The group created with the passed-in arguments.
:raises:
:exc:`ValueError` if both ``group_id`` and ``name`` are specified.
"""
return Group(
self,
group_id=group_id,
display_name=display_name,
parent_id=parent_id,
filter_string=filter_string,
is_cluster=is_cluster,
)
def fetch_group(self, group_id):
"""Fetch a group from the API based on it's ID.
Example::
>>> try:
>>> group = client.fetch_group('1234')
>>> except google.cloud.exceptions.NotFound:
>>> print('That group does not exist!')
:type group_id: str
:param group_id: The ID of the group.
:rtype: :class:`~google.cloud.monitoring.group.Group`
:returns: The group instance.
:raises: :class:`google.cloud.exceptions.NotFound` if the group
is not found.
"""
return Group._fetch(self, group_id)
def list_groups(self):
"""List all groups for the project.
Example::
>>> for group in client.list_groups():
... print((group.display_name, group.name))
:rtype: list of :class:`~google.cloud.monitoring.group.Group`
:returns: A list of group instances.
"""
return Group._list(self)
def write_time_series(self, timeseries_list):
"""Write a list of time series objects to the API.
The recommended approach to creating time series objects is using
the :meth:`~google.cloud.monitoring.client.Client.time_series` factory
method.
Example::
>>> client.write_time_series([ts1, ts2])
If you only need to write a single time series object, consider using
the :meth:`~google.cloud.monitoring.client.Client.write_point` method
instead.
:type timeseries_list:
list of :class:`~google.cloud.monitoring.timeseries.TimeSeries`
:param timeseries_list:
A list of time series object to be written
to the API. Each time series must contain exactly one point.
"""
path = '/projects/{project}/timeSeries/'.format(project=self.project)
timeseries_dict = [
timeseries._to_dict() for timeseries in timeseries_list
]
self._connection.api_request(method='POST',
path=path,
data={'timeSeries': timeseries_dict})
def write_point(self,
metric,
resource,
value,
end_time=None,
start_time=None):
"""Write a single point for a metric to the API.
This is a convenience method to write a single time series object to
the API. To write multiple time series objects to the API as a batch
operation, use the
:meth:`~google.cloud.monitoring.client.Client.time_series`
factory method to create time series objects and the
:meth:`~google.cloud.monitoring.client.Client.write_time_series`
method to write the objects.
Example::
>>> client.write_point(metric, resource, 3.14)
:type metric: :class:`~google.cloud.monitoring.metric.Metric`
:param metric: A :class:`~google.cloud.monitoring.metric.Metric`
object.
:type resource: :class:`~google.cloud.monitoring.resource.Resource`
:param resource: A :class:`~google.cloud.monitoring.resource.Resource`
object.
:type value: bool, int, string, or float
:param value:
The value of the data point to create for the
:class:`~google.cloud.monitoring.timeseries.TimeSeries`.
.. note::
The Python type of the value will determine the
:class:`~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 :data:`ValueType.DOUBLE`.
:type end_time: :class:`~datetime.datetime`
:param end_time:
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
:meth:`datetime.datetime.utcnow`.
:type start_time: :class:`~datetime.datetime`
:param start_time:
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.
"""
timeseries = self.time_series(metric, resource, value, end_time,
start_time)
self.write_time_series([timeseries])
class Client(JSONClient):
"""Client to bundle configuration needed for API requests.
:type project: str
:param project: The target project. If not passed, falls back to the
default inferred from the environment.
:type credentials: :class:`~google.auth.credentials.Credentials`
:param credentials: (Optional) The OAuth2 Credentials to use for this
client. If not passed (and if no ``http`` object is
passed), falls back to the default inferred from the
environment.
:type http: :class:`~httplib2.Http`
:param http: (Optional) HTTP object to make requests. Can be any object
that defines ``request()`` with the same interface as
:meth:`~httplib2.Http.request`. If not passed, an
``http`` object is created that is bound to the
``credentials`` for the current object.
"""
def __init__(self, project=None, credentials=None, http=None):
super(Client, self).__init__(
project=project, credentials=credentials, http=http)
self._connection = Connection(
credentials=self._credentials, http=self._http)
def query(self,
metric_type=Query.DEFAULT_METRIC_TYPE,
end_time=None,
days=0, hours=0, minutes=0):
"""Construct a query object for retrieving metric data.
Example::
>>> query = client.query(minutes=5)
>>> print(query.as_dataframe()) # Requires pandas.
:type metric_type: str
:param metric_type: The metric type name. The default value is
:data:`Query.DEFAULT_METRIC_TYPE
<google.cloud.monitoring.query.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`_.
:type end_time: :class:`datetime.datetime`
:param end_time:
(Optional) 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
:meth:`~google.cloud.monitoring.query.Query.select_interval`
must be called before the query is executed.
:type days: int
:param days: The number of days in the time interval.
:type hours: int
:param hours: The number of hours in the time interval.
:type minutes: int
:param minutes: The number of minutes in the time interval.
:rtype: :class:`~google.cloud.monitoring.query.Query`
:returns: The query object.
:raises: :exc:`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
:meth:`~google.cloud.monitoring.query.Query.select_interval`.
.. _supported metrics: https://cloud.google.com/monitoring/api/metrics
"""
return Query(self, metric_type,
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:`~google.cloud.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_: str
:param type_:
The metric type including a DNS name prefix. For example:
``"custom.googleapis.com/my_metric"``
:type metric_kind: str
:param metric_kind:
The kind of measurement. It must be one of
:data:`MetricKind.GAUGE`, :data:`MetricKind.DELTA`,
or :data:`MetricKind.CUMULATIVE`.
See :class:`~google.cloud.monitoring.metric.MetricKind`.
:type value_type: str
: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:`~google.cloud.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: str
:param unit: An optional unit in which the metric value is reported.
:type description: str
:param description: An optional detailed description of the metric.
:type display_name: str
:param display_name: An optional concise name for the metric.
:rtype: :class:`MetricDescriptor`
:returns: The metric descriptor created with the passed-in arguments.
"""
return MetricDescriptor(
self, type_,
metric_kind=metric_kind,
value_type=value_type,
labels=labels,
unit=unit,
description=description,
display_name=display_name,
)
@staticmethod
def metric(type_, labels):
"""Factory for constructing metric objects.
:class:`~google.cloud.monitoring.metric.Metric` objects are typically
created to write custom metric values. The type should match the
metric type specified in the
:class:`~google.cloud.monitoring.metric.MetricDescriptor` used to
create the custom metric::
>>> metric = client.metric('custom.googleapis.com/my_metric',
... labels={
... 'status': 'successful',
... })
:type type_: str
:param type_: The metric type name.
:type labels: dict
:param labels: A mapping from label names to values for all labels
enumerated in the associated
:class:`~.metric.MetricDescriptor`.
:rtype: :class:`~google.cloud.monitoring.metric.Metric`
:returns: The metric object.
"""
return Metric(type=type_, labels=labels)
@staticmethod
def resource(type_, labels):
"""Factory for constructing monitored resource objects.
A monitored resource object (
:class:`~google.cloud.monitoring.resource.Resource`) is
typically used to create a
:class:`~google.cloud.monitoring.timeseries.TimeSeries` object.
For a list of possible monitored resource types and their associated
labels, see:
https://cloud.google.com/monitoring/api/resources
:type type_: str
:param type_: The monitored resource type name.
:type labels: dict
:param labels: A mapping from label names to values for all labels
enumerated in the associated
:class:`~.resource.ResourceDescriptor`,
except that ``project_id`` can and should be omitted
when writing time series data.
:rtype: :class:`~google.cloud.monitoring.resource.Resource`
:returns: A monitored resource object.
"""
return Resource(type_, labels)
@staticmethod
def time_series(metric, resource, value,
end_time=None, start_time=None):
"""Construct a time series object for a single data point.
.. note::
While :class:`~google.cloud.monitoring.timeseries.TimeSeries`
objects returned by the API typically have multiple data points,
:class:`~google.cloud.monitoring.timeseries.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:
https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
:type metric: :class:`~google.cloud.monitoring.metric.Metric`
:param metric: A :class:`~google.cloud.monitoring.metric.Metric`.
:type resource: :class:`~google.cloud.monitoring.resource.Resource`
:param resource: A :class:`~google.cloud.monitoring.resource.Resource`
object.
:type value: bool, int, string, or float
:param value:
The value of the data point to create for the
:class:`~google.cloud.monitoring.timeseries.TimeSeries`.
.. note::
The Python type of the value will determine the
:class:`~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 :data:`ValueType.DOUBLE`.
:type end_time: :class:`~datetime.datetime`
:param end_time:
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
:meth:`datetime.datetime.utcnow`.
:type start_time: :class:`~datetime.datetime`
:param start_time:
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.
:rtype: :class:`~google.cloud.monitoring.timeseries.TimeSeries`
:returns: A time series object.
"""
if end_time is None:
end_time = _UTCNOW()
end_time = _datetime_to_rfc3339(end_time, ignore_zone=False)
if start_time:
start_time = _datetime_to_rfc3339(start_time, ignore_zone=False)
point = Point(value=value, start_time=start_time, end_time=end_time)
return TimeSeries(metric=metric, resource=resource, metric_kind=None,
value_type=None, points=[point])
def fetch_metric_descriptor(self, metric_type):
"""Look up a metric descriptor by type.
Example::
>>> METRIC = 'compute.googleapis.com/instance/cpu/utilization'
>>> print(client.fetch_metric_descriptor(METRIC))
:type metric_type: str
:param metric_type: The metric type name.
:rtype: :class:`~google.cloud.monitoring.metric.MetricDescriptor`
:returns: The metric descriptor instance.
:raises: :class:`google.cloud.exceptions.NotFound` if the metric
descriptor is not found.
"""
return MetricDescriptor._fetch(self, metric_type)
def list_metric_descriptors(self, filter_string=None, type_prefix=None):
"""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)
:type filter_string: str
:param filter_string:
(Optional) An optional filter expression describing the metric
descriptors to be returned. See the `filter documentation`_.
:type type_prefix: str
:param type_prefix:
(Optional) An optional prefix constraining the selected metric
types. This adds ``metric.type = starts_with("<prefix>")`` to the
filter.
:rtype:
list of :class:`~google.cloud.monitoring.metric.MetricDescriptor`
:returns: A list of metric descriptor instances.
.. _filter documentation:
https://cloud.google.com/monitoring/api/v3/filters
"""
return MetricDescriptor._list(self, filter_string,
type_prefix=type_prefix)
def fetch_resource_descriptor(self, resource_type):
"""Look up a monitored resource descriptor by type.
Example::
>>> print(client.fetch_resource_descriptor('gce_instance'))
:type resource_type: str
:param resource_type: The resource type name.
:rtype: :class:`~google.cloud.monitoring.resource.ResourceDescriptor`
:returns: The resource descriptor instance.
:raises: :class:`google.cloud.exceptions.NotFound` if the resource
descriptor is not found.
"""
return ResourceDescriptor._fetch(self, resource_type)
def list_resource_descriptors(self, filter_string=None):
"""List all monitored resource descriptors for the project.
Example::
>>> for descriptor in client.list_resource_descriptors():
... print(descriptor.type)
:type filter_string: str
:param filter_string:
(Optional) An optional filter expression describing the resource
descriptors to be returned. See the `filter documentation`_.
:rtype: list of
:class:`~google.cloud.monitoring.resource.ResourceDescriptor`
:returns: A list of resource descriptor instances.
.. _filter documentation:
https://cloud.google.com/monitoring/api/v3/filters
"""
return ResourceDescriptor._list(self, filter_string)
def group(self, group_id=None, display_name=None, parent_id=None,
filter_string=None, is_cluster=False):
"""Factory constructor for group object.
.. note::
This will not make an HTTP request; it simply instantiates
a group object owned by this client.
:type group_id: str
:param group_id: (Optional) The ID of the group.
:type display_name: str
:param display_name:
(Optional) A user-assigned name for this group, used only for
display purposes.
:type parent_id: str
:param parent_id:
(Optional) The ID of the group's parent, if it has one.
:type filter_string: str
:param filter_string:
(Optional) The filter string used to determine which monitored
resources belong to this group.
:type is_cluster: bool
:param is_cluster:
If true, the members of this group are considered to be a cluster.
The system can perform additional analysis on groups that are
clusters.
:rtype: :class:`Group`
:returns: The group created with the passed-in arguments.
:raises:
:exc:`ValueError` if both ``group_id`` and ``name`` are specified.
"""
return Group(
self,
group_id=group_id,
display_name=display_name,
parent_id=parent_id,
filter_string=filter_string,
is_cluster=is_cluster,
)
def fetch_group(self, group_id):
"""Fetch a group from the API based on it's ID.
Example::
>>> try:
>>> group = client.fetch_group('1234')
>>> except google.cloud.exceptions.NotFound:
>>> print('That group does not exist!')
:type group_id: str
:param group_id: The ID of the group.
:rtype: :class:`~google.cloud.monitoring.group.Group`
:returns: The group instance.
:raises: :class:`google.cloud.exceptions.NotFound` if the group
is not found.
"""
return Group._fetch(self, group_id)
def list_groups(self):
"""List all groups for the project.
Example::
>>> for group in client.list_groups():
... print((group.display_name, group.name))
:rtype: list of :class:`~google.cloud.monitoring.group.Group`
:returns: A list of group instances.
"""
return Group._list(self)
def write_time_series(self, timeseries_list):
"""Write a list of time series objects to the API.
The recommended approach to creating time series objects is using
the :meth:`~google.cloud.monitoring.client.Client.time_series` factory
method.
Example::
>>> client.write_time_series([ts1, ts2])
If you only need to write a single time series object, consider using
the :meth:`~google.cloud.monitoring.client.Client.write_point` method
instead.
:type timeseries_list:
list of :class:`~google.cloud.monitoring.timeseries.TimeSeries`
:param timeseries_list:
A list of time series object to be written
to the API. Each time series must contain exactly one point.
"""
path = '/projects/{project}/timeSeries/'.format(
project=self.project)
timeseries_dict = [timeseries._to_dict()
for timeseries in timeseries_list]
self._connection.api_request(method='POST', path=path,
data={'timeSeries': timeseries_dict})
def write_point(self, metric, resource, value,
end_time=None,
start_time=None):
"""Write a single point for a metric to the API.
This is a convenience method to write a single time series object to
the API. To write multiple time series objects to the API as a batch
operation, use the
:meth:`~google.cloud.monitoring.client.Client.time_series`
factory method to create time series objects and the
:meth:`~google.cloud.monitoring.client.Client.write_time_series`
method to write the objects.
Example::
>>> client.write_point(metric, resource, 3.14)
:type metric: :class:`~google.cloud.monitoring.metric.Metric`
:param metric: A :class:`~google.cloud.monitoring.metric.Metric`
object.
:type resource: :class:`~google.cloud.monitoring.resource.Resource`
:param resource: A :class:`~google.cloud.monitoring.resource.Resource`
object.
:type value: bool, int, string, or float
:param value:
The value of the data point to create for the
:class:`~google.cloud.monitoring.timeseries.TimeSeries`.
.. note::
The Python type of the value will determine the
:class:`~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 :data:`ValueType.DOUBLE`.
:type end_time: :class:`~datetime.datetime`
:param end_time:
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
:meth:`datetime.datetime.utcnow`.
:type start_time: :class:`~datetime.datetime`
:param start_time:
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.
"""
timeseries = self.time_series(
metric, resource, value, end_time, start_time)
self.write_time_series([timeseries])
