Stackdriver Monitoring Client#
Client for interacting with the Google Stackdriver Monitoring API (V3).
Example:
>>> from google.cloud 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
google.cloud.monitoring.client.
Client
(project=None, credentials=None, http=None)[source]# Bases:
google.cloud.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
orNoneType
) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if nohttp
object is passed), falls back to the default inferred from the environment. - http (
httplib2.Http
or class that definesrequest()
) – An optional HTTP object to make requests. If not passed, anhttp
object is created that is bound to thecredentials
for the current object.
-
fetch_group
(group_id)[source]# 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!')
Parameters: group_id (string) – The ID of the group. Return type: Group
Returns: The group instance. Raises: google.cloud.exceptions.NotFound
if the group is not found.
-
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: google.cloud.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: google.cloud.exceptions.NotFound
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.
Note
This will not make an HTTP request; it simply instantiates a group object owned by this client.
Parameters: - 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: Group
Returns: The group created with the passed-in arguments.
Raises: ValueError
if bothgroup_id
andname
are specified.
-
list_groups
()[source]# List all groups for the project.
Example:
>>> for group in client.list_groups(): ... print((group.display_name, group.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.
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.
-
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 theMetricDescriptor
used to create the custom metric:>>> metric = client.metric('custom.googleapis.com/my_metric', ... labels={ ... 'status': 'successful', ... })
Parameters: - 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: Returns: 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( ... '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
, orMetricKind.CUMULATIVE
. SeeMetricKind
. - value_type (string) – The value type of the metric. It must be one of
ValueType.BOOL
,ValueType.INT64
,ValueType.DOUBLE
,ValueType.STRING
, orValueType.DISTRIBUTION
. SeeValueType
. - 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: MetricDescriptor
Returns: The metric descriptor created with the passed-in arguments.
- type (string) – The metric type including a DNS name prefix. For example:
-
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
, andminutes
, 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: Returns: The query object.
Raises: ValueError
ifend_time
is specified butdays
,hours
, andminutes
are all zero. If you really want to specify a point in time, useselect_interval()
.- metric_type (string) – The metric type name. The default value is
-
static
resource
(type_, labels)[source]# Factory for constructing monitored resource objects.
A monitored resource object (
Resource
) is typically used to create aTimeSeries
object.For a list of possible monitored resource types and their associated labels, see:
https://cloud.google.com/monitoring/api/resources
Parameters: - 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 thatproject_id
can and should be omitted when writing time series data.
Return type: Returns: 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.
Note
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:
https://cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries
Parameters: - metric (
Metric
) – AMetric
. - resource (
Resource
) – AResource
object. - value (bool, int, string, or float) –
The value of the data point to create for the
TimeSeries
.Note
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 aValueType.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 callingdatetime.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: Returns: A time series object.
- metric (
Connection#
Create / interact with Stackdriver Monitoring connections.
-
class
google.cloud.monitoring.connection.
Connection
(credentials=None, http=None)[source]# Bases:
google.cloud.connection.JSONConnection
A connection to Google Stackdriver Monitoring via the JSON REST API.
Parameters: - credentials (
oauth2client.client.OAuth2Credentials
) – (Optional) The OAuth2 Credentials to use for this connection. - http (
httplib2.Http
or class that definesrequest()
) – (Optional) HTTP object to make requests. - api_base_url (string) – The base of the API call URL. Defaults to the value
Connection.API_BASE_URL
.
-
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.
- credentials (