Query(
client,
project,
metric_type="compute.googleapis.com/instance/cpu/utilization",
end_time=None,
days=0,
hours=0,
minutes=0,
)Query object for retrieving metric data.
Parameters | |
|---|---|
| Name | Description |
client |
:class:
The client to use. |
project |
str
The project ID or number. |
metric_type |
str
The metric type name. The default value is :data: |
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 |
int
The number of days in the time interval. |
hours |
int
The number of hours in the time interval. |
minutes |
int
The number of minutes in the time interval. |
Properties
filter
The filter string.
This is constructed from the metric type, the resource type, and selectors for the group ID, monitored projects, resource labels, and metric labels.
metric_type
The metric type name.
Methods
__deepcopy__
__deepcopy__(memo)Create a deepcopy of the query object.
The client attribute is copied by reference only.
| Parameter | |
|---|---|
| Name | Description |
memo |
dict
the memo dict to avoid excess copying in case the object is referenced from its member. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. |
align
align(per_series_aligner, seconds=0, minutes=0, hours=0)Copy the query and add temporal alignment.
If per_series_aligner is not :data:Aligner.ALIGN_NONE, each time
series will contain data points only on the period boundaries.
Example::
from google.cloud import monitoring
query = query.align(
monitoring.Aggregation.Aligner.ALIGN_MEAN, minutes=5)
It is also possible to specify the aligner as a literal string::
query = query.align('ALIGN_MEAN', minutes=5)
| Parameters | |
|---|---|
| Name | Description |
per_series_aligner |
str or Aligner
The approach to be used to align individual time series. For example: :data: |
seconds |
int
The number of seconds in the alignment period. |
minutes |
int
The number of minutes in the alignment period. |
hours |
int
The number of hours in the alignment period. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. .. _supported aligners: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/ projects.timeSeries/list#Aligner |
as_dataframe
as_dataframe(label=None, labels=None)Return all the selected time series as a pandas dataframe.
Generate a dataframe with a multi-level column header including
# the resource type and all available resource and metric labels.
# This can be useful for seeing what labels are available.
dataframe = query.as_dataframe()
# Generate a dataframe using a particular label for the column
# names.
dataframe = query.as_dataframe(label='instance_name')
# Generate a dataframe with a multi-level column header.
dataframe = query.as_dataframe(labels=['zone', 'instance_name'])
# Generate a dataframe with a multi-level column header, assuming
# the metric is issued by more than one type of resource.
dataframe = query.as_dataframe(
labels=['resource_type', 'instance_id'])
| Parameters | |
|---|---|
| Name | Description |
label |
str
(Optional) The label name to use for the dataframe header. This can be the name of a resource label or metric label (e.g., |
labels |
list of strings, or None
A list or tuple of label names to use for the dataframe header. If more than one label name is provided, the resulting dataframe will have a multi-level column header. Providing values for both |
| Returns | |
|---|---|
| Type | Description |
| A dataframe where each column represents one time series. |
iter
iter(headers_only=False, page_size=None)Yield all time series objects selected by the query.
The generator returned iterates over xref_TimeSeries objects containing points ordered from oldest to newest.
Note that the Query object itself is an iterable, such that
the following are equivalent::
for timeseries in query:
...
for timeseries in query.iter():
...
| Parameters | |
|---|---|
| Name | Description |
headers_only |
bool
Whether to omit the point data from the time series objects. |
page_size |
int
(Optional) The maximum number of points in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API. |
| Exceptions | |
|---|---|
| Type | Description |
`ValueError | if the query time interval has not been specified. |
reduce
reduce(cross_series_reducer, *group_by_fields)Copy the query and add cross-series reduction.
Cross-series reduction combines time series by aggregating their data points.
For example, you could request an aggregated time series for each combination of project and zone as follows::
from google.cloud import monitoring
query = query.reduce(monitoring.Aggregation.Reducer.REDUCE_MEAN,
'resource.project_id', 'resource.zone')
| Parameters | |
|---|---|
| Name | Description |
group_by_fields |
strs
Fields to be preserved by the reduction. For example, specifying just |
cross_series_reducer |
str or Reducer
The approach to be used to combine time series. For example: :data: |
| Returns | |
|---|---|
| Type | Description |
| The new query object. .. _supported reducers: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/ projects.timeSeries/list#Reducer |
select_group
select_group(group_id)Copy the query and add filtering by group.
Example::
query = query.select_group('1234567')
| Parameter | |
|---|---|
| Name | Description |
group_id |
str
The ID of a group to filter by. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. |
select_interval
select_interval(end_time, start_time=None)Copy the query and set the query time interval.
Example::
import datetime
now = datetime.datetime.utcnow()
query = query.select_interval(
end_time=now,
start_time=now - datetime.timedelta(minutes=5))
As a convenience, you can alternatively specify the end time and an interval duration when you create the query initially.
| Parameters | |
|---|---|
| Name | Description |
end_time |
The end time (inclusive) of the time interval for which results should be returned, as a datetime object. |
start_time |
(Optional) The start time (exclusive) of the time interval for which results should be returned, as a datetime object. If not specified, the interval is a point in time. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. |
select_metrics
select_metrics(*args, **kwargs)Copy the query and add filtering by metric labels.
Examples::
query = query.select_metrics(instance_name='myinstance')
query = query.select_metrics(instance_name_prefix='mycluster-')
A keyword argument <label>=<value> ordinarily generates a filter
expression of the form::
metric.label.<label> = "<value>"
However, by adding "_notequal" to the keyword, you can inequality:
<label>_notequal=<value> generates::
metric.label.<label> != <value>
By adding "_prefix" or "_suffix" to the keyword, you can specify
a partial match.
<label>_prefix=<value> generates::
metric.label.<label> = starts_with("<value>")
<label>_suffix=<value> generates::
metric.label.<label> = ends_with("<value>")
If the label's value type is INT64, a similar notation can be
used to express inequalities:
<label>_less=<value> generates::
metric.label.<label> < <value>
<label>_lessequal=<value> generates::
metric.label.<label> <= <value>
<label>_greater=<value> generates::
metric.label.<label> > <value>
<label>_greaterequal=<value> generates::
metric.label.<label> >= <value>
| Parameter | |
|---|---|
| Name | Description |
args |
tuple
Raw filter expression strings to include in the conjunction. If just one is provided and no keyword arguments are provided, it can be a disjunction. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. |
select_projects
select_projects(*args)Copy the query and add filtering by monitored projects.
This is only useful if the target project represents a Stackdriver account containing the specified monitored projects.
Examples::
query = query.select_projects('project-1')
query = query.select_projects('project-1', 'project-2')
| Parameter | |
|---|---|
| Name | Description |
args |
tuple
Project IDs limiting the resources to be included in the query. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. |
select_resources
select_resources(*args, **kwargs)Copy the query and add filtering by resource labels.
See more documentation at: https://cloud.google.com/monitoring/api/v3/filters#comparisons.
Examples::
query = query.select_resources(zone='us-central1-a')
query = query.select_resources(zone_prefix='europe-')
query = query.select_resources(resource_type='gce_instance')
A keyword argument <label>=<value> ordinarily generates a filter
expression of the form::
resource.label.<label> = "<value>"
However, by adding "_prefix" or "_suffix" to the keyword,
you can specify a partial match.
<label>_prefix=<value> generates::
resource.label.<label> = starts_with("<value>")
<label>_suffix=<value> generates::
resource.label.<label> = ends_with("<value>")
As a special case, "resource_type" is treated as a special
pseudo-label corresponding to the filter object resource.type.
For example, resource_type=<value> generates::
resource.type = "<value>"
See the defined resource types_.
| Parameter | |
|---|---|
| Name | Description |
args |
tuple
Raw filter expression strings to include in the conjunction. If just one is provided and no keyword arguments are provided, it can be a disjunction. |
| Returns | |
|---|---|
| Type | Description |
| The new query object. .. _defined resource types: https://cloud.google.com/monitoring/api/v3/monitored-resources |