From c874ef7ca5cc38dcd3367679765e847b05ef6ee2 Mon Sep 17 00:00:00 2001
From: Supriya Garg <supriyagarg@google.com>
Date: Wed, 24 Jan 2018 17:25:29 -0500
Subject: [PATCH 1/5] Add support for the Query class, and creating Pandas
 DataFrame.

Most of the code was ported over from the master branch, and updated
to use the autogenerated code.

Also, add utf-8 encoding to proto/common_pb2.py.
---
 .../google/cloud/monitoring/__init__.py       |   2 +
 .../google/cloud/monitoring/_dataframe.py     | 143 +++++
 monitoring/google/cloud/monitoring/query.py   | 604 ++++++++++++++++++
 .../cloud/monitoring_v3/proto/common_pb2.py   |   1 +
 4 files changed, 750 insertions(+)
 create mode 100644 monitoring/google/cloud/monitoring/_dataframe.py
 create mode 100644 monitoring/google/cloud/monitoring/query.py

diff --git a/monitoring/google/cloud/monitoring/__init__.py b/monitoring/google/cloud/monitoring/__init__.py
index a0f3fbfc22ab..80bd1f78383b 100644
--- a/monitoring/google/cloud/monitoring/__init__.py
+++ b/monitoring/google/cloud/monitoring/__init__.py
@@ -14,6 +14,7 @@
 
 from __future__ import absolute_import
 
+from google.cloud.monitoring.query import Query
 from google.cloud.monitoring_v3 import GroupServiceClient
 from google.cloud.monitoring_v3 import MetricServiceClient
 from google.cloud.monitoring_v3 import enums
@@ -23,4 +24,5 @@
     'enums',
     'types',
     'GroupServiceClient',
+    'Query',
     'MetricServiceClient', )
diff --git a/monitoring/google/cloud/monitoring/_dataframe.py b/monitoring/google/cloud/monitoring/_dataframe.py
new file mode 100644
index 000000000000..3ccc7e1eaa4c
--- /dev/null
+++ b/monitoring/google/cloud/monitoring/_dataframe.py
@@ -0,0 +1,143 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Time series as :mod:`pandas` dataframes."""
+
+import itertools
+
+from google.cloud.monitoring_v3.types import TimeSeries
+
+TOP_RESOURCE_LABELS = (
+    'project_id',
+    'aws_account',
+    'location',
+    'region',
+    'zone',
+)
+
+
+def _extract_header(time_series):
+    """Return a copy of time_series with the points removed."""
+    return TimeSeries(
+        metric=time_series.metric,
+        resource=time_series.resource,
+        metric_kind=time_series.metric_kind,
+        value_type=time_series.value_type
+    )
+
+
+def _extract_labels(time_series):
+    """Build the combined resource and metric labels, with resource_type."""
+    labels = {'resource_type': time_series.resource.type}
+    labels.update(time_series.resource.labels)
+    labels.update(time_series.metric.labels)
+    return labels
+
+
+def _extract_value(typed_value):
+     """Extract the value from a TypedValue."""
+     value_type = typed_value.WhichOneof('value')
+     return typed_value.__getattribute__(value_type)
+
+
+def _build_dataframe(time_series_iterable,
+                     label=None, labels=None):  # pragma: NO COVER
+    """Build a :mod:`pandas` dataframe out of time series.
+
+    :type time_series_iterable:
+        iterable over :class:`~google.cloud.monitoring_v3.types.TimeSeries`
+    :param time_series_iterable:
+        An iterable (e.g., a query object) yielding time series.
+
+    :type label: str
+    :param label:
+        (Optional) The label name to use for the dataframe header. This can be
+        the name of a resource label or metric label (e.g.,
+        ``"instance_name"``), or the string ``"resource_type"``.
+
+    :type labels: list of strings, or None
+    :param labels:
+        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.
+
+        Specifying neither ``label`` or ``labels`` results in a dataframe
+        with a multi-level column header including the resource type and
+        all available resource and metric labels.
+
+        Specifying both ``label`` and ``labels`` is an error.
+
+    :rtype: :class:`pandas.DataFrame`
+    :returns: A dataframe where each column represents one time series.
+    """
+    import pandas   # pylint: disable=import-error
+
+    if labels is not None:
+        if label is not None:
+            raise ValueError('Cannot specify both "label" and "labels".')
+        elif not labels:
+            raise ValueError('"labels" must be non-empty or None.')
+
+    columns = []
+    headers = []
+    for time_series in time_series_iterable:
+        pandas_series = pandas.Series(
+            data=[_extract_value(point.value) for point in time_series.points],
+            index=[point.interval.end_time.ToNanoseconds()
+                   for point in time_series.points],
+        )
+        columns.append(pandas_series)
+        headers.append(_extract_header(time_series))
+
+    # Implement a smart default of using all available labels.
+    if label is None and labels is None:
+        resource_labels = set(itertools.chain.from_iterable(
+            header.resource.labels for header in headers))
+        metric_labels = set(itertools.chain.from_iterable(
+            header.metric.labels for header in headers))
+        labels = (['resource_type'] +
+                  _sorted_resource_labels(resource_labels) +
+                  sorted(metric_labels))
+
+    # Assemble the columns into a DataFrame.
+    dataframe = pandas.DataFrame.from_records(columns).T
+
+    # Convert the timestamp strings into a DatetimeIndex.
+    dataframe.index = pandas.to_datetime(dataframe.index)
+
+    # Build a multi-level stack of column headers. Some labels may
+    # be undefined for some time series.
+    levels = []
+    for key in labels or [label]:
+        level = [_extract_labels(header).get(key, '') for header in headers]
+        levels.append(level)
+
+    # Build a column Index or MultiIndex. Do not include level names
+    # in the column header if the user requested a single-level header
+    # by specifying "label".
+    dataframe.columns = pandas.MultiIndex.from_arrays(
+        levels,
+        names=labels or None)
+
+    # Sort the rows just in case (since the API doesn't guarantee the
+    # ordering), and sort the columns lexicographically.
+    return dataframe.sort_index(axis=0).sort_index(axis=1)
+
+
+def _sorted_resource_labels(labels):
+    """Sort label names, putting well-known resource labels first."""
+    head = [label for label in TOP_RESOURCE_LABELS if label in labels]
+    tail = sorted(label for label in labels
+                  if label not in TOP_RESOURCE_LABELS)
+    return head + tail
diff --git a/monitoring/google/cloud/monitoring/query.py b/monitoring/google/cloud/monitoring/query.py
new file mode 100644
index 000000000000..4675fb9b2a82
--- /dev/null
+++ b/monitoring/google/cloud/monitoring/query.py
@@ -0,0 +1,604 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Time series query for the `Google Stackdriver Monitoring API (V3)`_.
+
+.. _Google Stackdriver Monitoring API (V3):
+    https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+    projects.timeSeries/list
+"""
+
+import copy
+import datetime
+
+import six
+
+from google.cloud.monitoring._dataframe import _build_dataframe
+from google.cloud.monitoring_v3 import types
+from google.cloud.monitoring_v3.gapic import enums
+
+_UTCNOW = datetime.datetime.utcnow  # To be replaced by tests.
+
+
+class Query(object):
+    """Query object for retrieving metric data.
+
+    :type client: :class:`google.cloud.monitoring_v3.gapic.metric_service_client.MetricServiceClient`
+    :param client: The client to use.
+
+    :type project: str
+    :param project: The project ID or number.
+
+    :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.
+
+    :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
+    """
+
+    DEFAULT_METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
+
+    def __init__(self, client, project,
+                 metric_type=DEFAULT_METRIC_TYPE,
+                 end_time=None, days=0, hours=0, minutes=0):
+        start_time = None
+        if days or hours or minutes:
+            if end_time is None:
+                end_time = _UTCNOW().replace(second=0, microsecond=0)
+            start_time = end_time - datetime.timedelta(days=days,
+                                                       hours=hours,
+                                                       minutes=minutes)
+        elif end_time is not None:
+            raise ValueError('Non-zero duration required for time interval.')
+
+        self._client = client
+        self._project_path = self._client.project_path(project)
+        self._end_time = end_time
+        self._start_time = start_time
+        self._filter = _Filter(metric_type)
+
+        self._per_series_aligner = 0
+        self._alignment_period_seconds = 0
+        self._cross_series_reducer = 0
+        self._group_by_fields = ()
+
+    def __iter__(self):
+        return self.iter()
+
+    @property
+    def metric_type(self):
+        """The metric type name."""
+        return self._filter.metric_type
+
+    @property
+    def filter(self):
+        """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.
+        """
+        return str(self._filter)
+
+    def select_interval(self, 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.
+
+        :type end_time: :class:`datetime.datetime`
+        :param end_time: The end time (inclusive) of the time interval
+            for which results should be returned, as a datetime object.
+
+        :type start_time: :class:`datetime.datetime`
+        :param 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.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._end_time = end_time
+        new_query._start_time = start_time
+        return new_query
+
+    def select_group(self, group_id):
+        """Copy the query and add filtering by group.
+
+        Example::
+
+            query = query.select_group('1234567')
+
+        :type group_id: str
+        :param group_id: The ID of a group to filter by.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.group_id = group_id
+        return new_query
+
+    def select_projects(self, *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')
+
+        :type args: tuple
+        :param args: Project IDs limiting the resources to be included
+            in the query.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.projects = args
+        return new_query
+
+    def select_resources(self, *args, **kwargs):
+        """Copy the query and add filtering by resource labels.
+
+        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`_.
+
+        .. note::
+
+            The label ``"instance_name"`` is a metric label,
+            not a resource label. You would filter on it using
+            ``select_metrics(instance_name=...)``.
+
+        :type args: tuple
+        :param args: 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.
+
+        :type kwargs: dict
+        :param kwargs: Label filters to include in the conjunction as
+            described above.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+
+        .. _defined resource types:
+            https://cloud.google.com/monitoring/api/v3/monitored-resources
+        """
+        new_query = self.copy()
+        new_query._filter.select_resources(*args, **kwargs)
+        return new_query
+
+    def select_metrics(self, *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 ``"_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>
+
+        :type args: tuple
+        :param args: 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.
+
+        :type kwargs: dict
+        :param kwargs: Label filters to include in the conjunction as
+            described above.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        new_query = self.copy()
+        new_query._filter.select_metrics(*args, **kwargs)
+        return new_query
+
+    def align(self, 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.monitoring import enums
+            query = query.align(enums.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)
+
+        :type per_series_aligner: str or
+            :class:`~google.cloud.monitoring_v3.gapic.enums.Aggregation.Aligner`
+        :param per_series_aligner: The approach to be used to align
+            individual time series. For example: :data:`Aligner.ALIGN_MEAN`. See
+            :class:`~google.cloud.monitoring_v3.gapic.enums.Aggregation.Aligner`
+            and the descriptions of the `supported aligners`_.
+
+        :type seconds: int
+        :param seconds: The number of seconds in the alignment period.
+
+        :type minutes: int
+        :param minutes: The number of minutes in the alignment period.
+
+        :type hours: int
+        :param hours: The number of hours in the alignment period.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+
+        .. _supported aligners:
+            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+            projects.timeSeries/list#Aligner
+        """
+        new_query = self.copy()
+        new_query._per_series_aligner = per_series_aligner
+        new_query._alignment_period_seconds = seconds + 60 * (minutes +
+                                                              60 * hours)
+        return new_query
+
+    def reduce(self, 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.monitoring import enums
+            query = query.reduce(enums.Aggregation.Reducer.REDUCE_MEAN,
+                                 'resource.project_id', 'resource.zone')
+
+        :type cross_series_reducer: str or
+            :class:`~google.cloud.monitoring_v3.gapic.enums.Aggregation.Reducer`
+        :param cross_series_reducer:
+            The approach to be used to combine time series. For example:
+            :data:`Reducer.REDUCE_MEAN`. See
+            :class:`~google.cloud.monitoring_v3.gapic.enums.Aggregation.Reducer`
+            and the descriptions of the `supported reducers`_.
+
+        :type group_by_fields: strs
+        :param group_by_fields:
+            Fields to be preserved by the reduction. For example, specifying
+            just ``"resource.zone"`` will result in one time series per zone.
+            The default is to aggregate all of the time series into just one.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+
+        .. _supported reducers:
+            https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
+            projects.timeSeries/list#Reducer
+        """
+        new_query = self.copy()
+        new_query._cross_series_reducer = cross_series_reducer
+        new_query._group_by_fields = group_by_fields
+        return new_query
+
+    def iter(self, headers_only=False, page_size=None):
+        """Yield all time series objects selected by the query.
+
+        The generator returned iterates over
+        :class:`~google.cloud.monitoring_v3.types.TimeSeries` objects
+        containing points ordered from oldest to newest.
+
+        Note that the :class:`Query` object itself is an iterable, such that
+        the following are equivalent::
+
+            for timeseries in query:
+                ...
+
+            for timeseries in query.iter():
+                ...
+
+        :type headers_only: bool
+        :param headers_only:
+             Whether to omit the point data from the time series objects.
+
+        :type page_size: int
+        :param page_size:
+            (Optional) Positive number specifying the maximum number of points
+            to return per page. This can be used to control how far the
+            iterator reads ahead.
+
+        :raises: :exc:`ValueError` if the query time interval has not been
+            specified.
+        """
+        if self._end_time is None:
+            raise ValueError('Query time interval not specified.')
+
+        params = self._build_query_params(headers_only, page_size)
+        for ts in self._client.list_time_series(**params):
+            yield ts
+
+    def _build_query_params(self, headers_only=False, page_size=None):
+        """Return key-value pairs for the list_time_series API call.
+
+        :type headers_only: bool
+        :param headers_only:
+             Whether to omit the point data from the
+             :class:`~google.cloud.monitoring_v3.types.TimeSeries` objects.
+
+        :type page_size: int
+        :param page_size:
+            (Optional) A limit on the number of points to return per page.
+        """
+        params = {'name': self._project_path, 'filter_': self.filter}
+
+        params['interval'] = types.TimeInterval()
+        params['interval'].end_time.FromDatetime(self._end_time)
+        if self._start_time:
+          params['interval'].start_time.FromDatetime(self._start_time)
+
+        params['aggregation'] = types.Aggregation(
+            per_series_aligner=self._per_series_aligner,
+            cross_series_reducer=self._cross_series_reducer,
+            group_by_fields=self._group_by_fields,
+            alignment_period={'seconds': self._alignment_period_seconds},
+        )
+
+        if headers_only:
+            params['view'] = enums.ListTimeSeriesRequest.TimeSeriesView.HEADERS
+        else:
+            params['view'] = enums.ListTimeSeriesRequest.TimeSeriesView.FULL
+
+        if page_size is not None:
+            params['page_size'] = page_size
+
+        return params
+
+    def as_dataframe(self, label=None, labels=None):
+        """Return all the selected time series as a :mod:`pandas` dataframe.
+
+        .. note::
+
+            Use of this method requires that you have :mod:`pandas` installed.
+
+        Examples::
+
+            # 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'])
+
+        :type label: str
+        :param label:
+            (Optional) The label name to use for the dataframe header.
+            This can be the name of a resource label or metric label
+            (e.g., ``"instance_name"``), or the string ``"resource_type"``.
+
+        :type labels: list of strings, or None
+        :param labels: 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 ``label`` and ``labels`` is an error.
+
+        :rtype: :class:`pandas.DataFrame`
+        :returns: A dataframe where each column represents one time series.
+        """
+        return _build_dataframe(self, label, labels)  # pragma: NO COVER
+
+    def copy(self):
+        """Copy the query object.
+
+        :rtype: :class:`Query`
+        :returns: The new query object.
+        """
+        # Using copy.deepcopy() would be appropriate, except that we want
+        # to copy self._client only as a reference.
+        new_query = copy.copy(self)
+        new_query._filter = copy.copy(self._filter)
+        return new_query
+
+
+class _Filter(object):
+    """Helper for assembling a filter string."""
+
+    def __init__(self, metric_type):
+        self.metric_type = metric_type
+        self.group_id = None
+        self.projects = ()
+        self.resource_label_filter = None
+        self.metric_label_filter = None
+
+    def select_resources(self, *args, **kwargs):
+        """Select by resource labels.
+
+        See :meth:`Query.select_resources`.
+        """
+        self.resource_label_filter = _build_label_filter('resource',
+                                                         *args, **kwargs)
+
+    def select_metrics(self, *args, **kwargs):
+        """Select by metric labels.
+
+        See :meth:`Query.select_metrics`.
+        """
+        self.metric_label_filter = _build_label_filter('metric',
+                                                       *args, **kwargs)
+
+    def __str__(self):
+        filters = ['metric.type = "{type}"'.format(type=self.metric_type)]
+        if self.group_id is not None:
+            filters.append('group.id = "{id}"'.format(id=self.group_id))
+        if self.projects:
+            filters.append(
+                ' OR '.join('project = "{project}"'.format(project=project)
+                            for project in self.projects))
+        if self.resource_label_filter:
+            filters.append(self.resource_label_filter)
+        if self.metric_label_filter:
+            filters.append(self.metric_label_filter)
+
+        # Parentheses are never actually required, because OR binds more
+        # tightly than AND in the Monitoring API's filter syntax.
+        return ' AND '.join(filters)
+
+
+def _build_label_filter(category, *args, **kwargs):
+    """Construct a filter string to filter on metric or resource labels."""
+    terms = list(args)
+    for key, value in six.iteritems(kwargs):
+        if value is None:
+            continue
+
+        suffix = None
+        if key.endswith(('_prefix', '_suffix', '_greater', '_greaterequal',
+                         '_less', '_lessequal')):
+            key, suffix = key.rsplit('_', 1)
+
+        if category == 'resource' and key == 'resource_type':
+            key = 'resource.type'
+        else:
+            key = '.'.join((category, 'label', key))
+
+        if suffix == 'prefix':
+            term = '{key} = starts_with("{value}")'
+        elif suffix == 'suffix':
+            term = '{key} = ends_with("{value}")'
+        elif suffix == 'greater':
+            term = '{key} > {value}'
+        elif suffix == 'greaterequal':
+            term = '{key} >= {value}'
+        elif suffix == 'less':
+            term = '{key} < {value}'
+        elif suffix == 'lessequal':
+            term = '{key} <= {value}'
+        else:
+            term = '{key} = "{value}"'
+
+        terms.append(term.format(key=key, value=value))
+
+    return ' AND '.join(sorted(terms))
diff --git a/monitoring/google/cloud/monitoring_v3/proto/common_pb2.py b/monitoring/google/cloud/monitoring_v3/proto/common_pb2.py
index 49b466f6cf18..4c93ec47f556 100644
--- a/monitoring/google/cloud/monitoring_v3/proto/common_pb2.py
+++ b/monitoring/google/cloud/monitoring_v3/proto/common_pb2.py
@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: google/cloud/monitoring_v3/proto/common.proto
 

From dfc929f914913be1b6644444d8945d233da5b6ef Mon Sep 17 00:00:00 2001
From: Supriya Garg <supriyagarg@google.com>
Date: Wed, 24 Jan 2018 18:33:59 -0500
Subject: [PATCH 2/5] Update the doc files for monitoring to reflect the
 autogen code.

---
 docs/monitoring/client.rst     | 3 ++-
 docs/monitoring/enums.rst      | 6 ++++++
 docs/monitoring/group.rst      | 2 +-
 docs/monitoring/label.rst      | 6 ------
 docs/monitoring/metric.rst     | 6 ------
 docs/monitoring/resource.rst   | 6 ------
 docs/monitoring/timeseries.rst | 6 ------
 docs/monitoring/types.rst      | 6 ++++++
 docs/monitoring/usage.rst      | 6 ++----
 9 files changed, 17 insertions(+), 30 deletions(-)
 create mode 100644 docs/monitoring/enums.rst
 delete mode 100644 docs/monitoring/label.rst
 delete mode 100644 docs/monitoring/metric.rst
 delete mode 100644 docs/monitoring/resource.rst
 delete mode 100644 docs/monitoring/timeseries.rst
 create mode 100644 docs/monitoring/types.rst

diff --git a/docs/monitoring/client.rst b/docs/monitoring/client.rst
index adc83974e6b2..ebeef3e9efc5 100644
--- a/docs/monitoring/client.rst
+++ b/docs/monitoring/client.rst
@@ -1,6 +1,7 @@
 Stackdriver Monitoring Client
 =============================
 
-.. automodule:: google.cloud.monitoring.client
+.. automodule:: google.cloud.monitoring_v3.gapic.metric_service_client
+
   :members:
   :show-inheritance:
diff --git a/docs/monitoring/enums.rst b/docs/monitoring/enums.rst
new file mode 100644
index 000000000000..523608febf4d
--- /dev/null
+++ b/docs/monitoring/enums.rst
@@ -0,0 +1,6 @@
+Enums
+=====
+
+.. automodule:: google.cloud.monitoring_v3.gapic.enums
+  :members:
+  :show-inheritance:
diff --git a/docs/monitoring/group.rst b/docs/monitoring/group.rst
index ff49077008cc..c49cd2e70b03 100644
--- a/docs/monitoring/group.rst
+++ b/docs/monitoring/group.rst
@@ -1,6 +1,6 @@
 Groups
 ======
 
-.. automodule:: google.cloud.monitoring.group
+.. automodule:: google.cloud.monitoring_v3.gapic.group_service_client
   :members:
   :show-inheritance:
diff --git a/docs/monitoring/label.rst b/docs/monitoring/label.rst
deleted file mode 100644
index 67b7c16b7689..000000000000
--- a/docs/monitoring/label.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Label Descriptors
-=================
-
-.. automodule:: google.cloud.monitoring.label
-  :members:
-  :show-inheritance:
diff --git a/docs/monitoring/metric.rst b/docs/monitoring/metric.rst
deleted file mode 100644
index abb6395f864c..000000000000
--- a/docs/monitoring/metric.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Metric Descriptors
-==================
-
-.. automodule:: google.cloud.monitoring.metric
-  :members:
-  :show-inheritance:
diff --git a/docs/monitoring/resource.rst b/docs/monitoring/resource.rst
deleted file mode 100644
index b7faf93e68df..000000000000
--- a/docs/monitoring/resource.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Monitored Resource Descriptors
-==============================
-
-.. automodule:: google.cloud.monitoring.resource
-  :members:
-  :show-inheritance:
diff --git a/docs/monitoring/timeseries.rst b/docs/monitoring/timeseries.rst
deleted file mode 100644
index e580f8067d69..000000000000
--- a/docs/monitoring/timeseries.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Time Series
-===========
-
-.. automodule:: google.cloud.monitoring.timeseries
-  :members:
-  :show-inheritance:
diff --git a/docs/monitoring/types.rst b/docs/monitoring/types.rst
new file mode 100644
index 000000000000..140917ee4aa6
--- /dev/null
+++ b/docs/monitoring/types.rst
@@ -0,0 +1,6 @@
+Types
+=====
+
+.. automodule:: google.cloud.monitoring_v3.types
+  :members:
+  :show-inheritance:
diff --git a/docs/monitoring/usage.rst b/docs/monitoring/usage.rst
index 6a7fed856cba..9c01d77eba4a 100644
--- a/docs/monitoring/usage.rst
+++ b/docs/monitoring/usage.rst
@@ -7,12 +7,10 @@ Stackdriver Monitoring
 
   releases
   client
-  metric
-  resource
   group
   query
-  timeseries
-  label
+  types
+  enums
 
 Introduction
 ------------

From 09a8f1de78157a374d0369dfd5f428b5f6438d29 Mon Sep 17 00:00:00 2001
From: Supriya Garg <supriyagarg@google.com>
Date: Wed, 31 Jan 2018 17:15:14 -0500
Subject: [PATCH 3/5] Address comments on _dataframe.py

---
 .../google/cloud/monitoring/_dataframe.py     | 24 ++++++++++++-------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/monitoring/google/cloud/monitoring/_dataframe.py b/monitoring/google/cloud/monitoring/_dataframe.py
index 3ccc7e1eaa4c..dc07a690b098 100644
--- a/monitoring/google/cloud/monitoring/_dataframe.py
+++ b/monitoring/google/cloud/monitoring/_dataframe.py
@@ -15,6 +15,10 @@
 """Time series as :mod:`pandas` dataframes."""
 
 import itertools
+try:
+    import pandas
+except ImportError:
+    pandas = None
 
 from google.cloud.monitoring_v3.types import TimeSeries
 
@@ -80,14 +84,16 @@ def _build_dataframe(time_series_iterable,
 
     :rtype: :class:`pandas.DataFrame`
     :returns: A dataframe where each column represents one time series.
+
+    :raises: :exc:`RuntimeError` if `pandas` is not installed.
     """
-    import pandas   # pylint: disable=import-error
+    if pandas is None:
+        raise RuntimeError('This method requires `pandas` to be installed.')
 
-    if labels is not None:
-        if label is not None:
-            raise ValueError('Cannot specify both "label" and "labels".')
-        elif not labels:
-            raise ValueError('"labels" must be non-empty or None.')
+    if label is not None:
+        if labels:
+            raise ValueError('Cannot specify both `label` and `labels`.')
+        labels = (label,)
 
     columns = []
     headers = []
@@ -101,7 +107,7 @@ def _build_dataframe(time_series_iterable,
         headers.append(_extract_header(time_series))
 
     # Implement a smart default of using all available labels.
-    if label is None and labels is None:
+    if labels is None:
         resource_labels = set(itertools.chain.from_iterable(
             header.resource.labels for header in headers))
         metric_labels = set(itertools.chain.from_iterable(
@@ -119,7 +125,7 @@ def _build_dataframe(time_series_iterable,
     # Build a multi-level stack of column headers. Some labels may
     # be undefined for some time series.
     levels = []
-    for key in labels or [label]:
+    for key in labels:
         level = [_extract_labels(header).get(key, '') for header in headers]
         levels.append(level)
 
@@ -128,7 +134,7 @@ def _build_dataframe(time_series_iterable,
     # by specifying "label".
     dataframe.columns = pandas.MultiIndex.from_arrays(
         levels,
-        names=labels or None)
+        names=labels if not label else None)
 
     # Sort the rows just in case (since the API doesn't guarantee the
     # ordering), and sort the columns lexicographically.

From 18b9e3797be400a5d6f2def74aa1b11fc1c77298 Mon Sep 17 00:00:00 2001
From: Supriya Garg <supriyagarg@google.com>
Date: Wed, 31 Jan 2018 18:22:14 -0500
Subject: [PATCH 4/5] Update the copy method to __deepcopy__()

Also, populat the 'aggregation' field is now populated only if at least
one of its components has been set.
---
 monitoring/google/cloud/monitoring/query.py | 42 ++++++++++++---------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/monitoring/google/cloud/monitoring/query.py b/monitoring/google/cloud/monitoring/query.py
index 4675fb9b2a82..ff45e35734f6 100644
--- a/monitoring/google/cloud/monitoring/query.py
+++ b/monitoring/google/cloud/monitoring/query.py
@@ -151,7 +151,7 @@ def select_interval(self, end_time, start_time=None):
         :rtype: :class:`Query`
         :returns: The new query object.
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._end_time = end_time
         new_query._start_time = start_time
         return new_query
@@ -169,7 +169,7 @@ def select_group(self, group_id):
         :rtype: :class:`Query`
         :returns: The new query object.
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._filter.group_id = group_id
         return new_query
 
@@ -191,7 +191,7 @@ def select_projects(self, *args):
         :rtype: :class:`Query`
         :returns: The new query object.
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._filter.projects = args
         return new_query
 
@@ -249,7 +249,7 @@ def select_resources(self, *args, **kwargs):
         .. _defined resource types:
             https://cloud.google.com/monitoring/api/v3/monitored-resources
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._filter.select_resources(*args, **kwargs)
         return new_query
 
@@ -308,7 +308,7 @@ def select_metrics(self, *args, **kwargs):
         :rtype: :class:`Query`
         :returns: The new query object.
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._filter.select_metrics(*args, **kwargs)
         return new_query
 
@@ -350,7 +350,7 @@ def align(self, per_series_aligner, seconds=0, minutes=0, hours=0):
             https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
             projects.timeSeries/list#Aligner
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._per_series_aligner = per_series_aligner
         new_query._alignment_period_seconds = seconds + 60 * (minutes +
                                                               60 * hours)
@@ -390,7 +390,7 @@ def reduce(self, cross_series_reducer, *group_by_fields):
             https://cloud.google.com/monitoring/api/ref_v3/rest/v3/\
             projects.timeSeries/list#Reducer
         """
-        new_query = self.copy()
+        new_query = copy.deepcopy(self)
         new_query._cross_series_reducer = cross_series_reducer
         new_query._group_by_fields = group_by_fields
         return new_query
@@ -450,12 +450,14 @@ def _build_query_params(self, headers_only=False, page_size=None):
         if self._start_time:
           params['interval'].start_time.FromDatetime(self._start_time)
 
-        params['aggregation'] = types.Aggregation(
-            per_series_aligner=self._per_series_aligner,
-            cross_series_reducer=self._cross_series_reducer,
-            group_by_fields=self._group_by_fields,
-            alignment_period={'seconds': self._alignment_period_seconds},
-        )
+        if (self._per_series_aligner or self._alignment_period_seconds or
+                self._cross_series_reducer or self._group_by_fields):
+            params['aggregation'] = types.Aggregation(
+                per_series_aligner=self._per_series_aligner,
+                cross_series_reducer=self._cross_series_reducer,
+                group_by_fields=self._group_by_fields,
+                alignment_period={'seconds': self._alignment_period_seconds},
+            )
 
         if headers_only:
             params['view'] = enums.ListTimeSeriesRequest.TimeSeriesView.HEADERS
@@ -510,16 +512,20 @@ def as_dataframe(self, label=None, labels=None):
         """
         return _build_dataframe(self, label, labels)  # pragma: NO COVER
 
-    def copy(self):
-        """Copy the query object.
+    def __deepcopy__(self, memo):
+        """Create a deepcopy of the query object.
+
+        The `client` attribute is copied by reference only.
+
+        :type memo: dict
+        :param memo: the memo dict to avoid excess copying in case  the object
+            is referenced from its member.
 
         :rtype: :class:`Query`
         :returns: The new query object.
         """
-        # Using copy.deepcopy() would be appropriate, except that we want
-        # to copy self._client only as a reference.
         new_query = copy.copy(self)
-        new_query._filter = copy.copy(self._filter)
+        new_query._filter = copy.deepcopy(self._filter, memo)
         return new_query
 
 

From bc3f82f5eed2d4b7dc93e6e8fc76cb78bba1b38f Mon Sep 17 00:00:00 2001
From: Supriya Garg <supriyagarg@google.com>
Date: Thu, 1 Feb 2018 13:02:38 -0500
Subject: [PATCH 5/5] Add unit tests for the manual code in Monitoring.

---
 monitoring/tests/unit/test__dataframe.py | 228 +++++++++
 monitoring/tests/unit/test_query.py      | 593 +++++++++++++++++++++++
 2 files changed, 821 insertions(+)
 create mode 100644 monitoring/tests/unit/test__dataframe.py
 create mode 100644 monitoring/tests/unit/test_query.py

diff --git a/monitoring/tests/unit/test__dataframe.py b/monitoring/tests/unit/test__dataframe.py
new file mode 100644
index 000000000000..898ad30fdf45
--- /dev/null
+++ b/monitoring/tests/unit/test__dataframe.py
@@ -0,0 +1,228 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+try:
+    import pandas
+except ImportError:
+    HAVE_PANDAS = False
+else:
+    HAVE_PANDAS = True  # pragma: NO COVER
+
+import unittest
+
+
+PROJECT = 'my-project'
+
+INSTANCE_NAMES = ['instance-1', 'instance-2']
+INSTANCE_ZONES = ['us-east1-a', 'us-east1-b']
+INSTANCE_IDS = ['1234567890123456789', '9876543210987654321']
+
+METRIC_TYPE = 'compute.googleapis.com/instance/cpu/utilization'
+METRIC_LABELS = list({'instance_name': name} for name in INSTANCE_NAMES)
+
+RESOURCE_TYPE = 'gce_instance'
+RESOURCE_LABELS = list({
+    'project_id': PROJECT,
+    'zone': zone,
+    'instance_id': instance_id,
+} for zone, instance_id in zip(INSTANCE_ZONES, INSTANCE_IDS))
+
+METRIC_KIND = 'GAUGE'
+VALUE_TYPE = 'DOUBLE'
+
+TIMESTAMPS = [
+    '2016-04-06T22:05:00.042Z',
+    '2016-04-06T22:05:01.042Z',
+    '2016-04-06T22:05:02.042Z',
+]
+
+DIMENSIONS = len(TIMESTAMPS), len(INSTANCE_NAMES)
+VALUES = list(0.1 * i for i in range(DIMENSIONS[1]))
+ARRAY = [VALUES] * DIMENSIONS[0]
+
+
+def parse_timestamps():  # pragma: NO COVER
+    import datetime
+    from google.cloud._helpers import _RFC3339_MICROS
+
+    return [datetime.datetime.strptime(t, _RFC3339_MICROS)
+            for t in TIMESTAMPS]
+
+
+def generate_query_results():  # pragma: NO COVER
+    from google.cloud.monitoring import types
+
+    def P(timestamp, value):
+        interval = types.TimeInterval()
+        interval.start_time.FromJsonString(timestamp)
+        interval.end_time.FromJsonString(timestamp)
+        return types.Point(interval=interval, value={'double_value': value})
+
+    for metric_labels, resource_labels, value in zip(
+            METRIC_LABELS, RESOURCE_LABELS, VALUES):
+        yield types.TimeSeries(
+            metric=types.Metric(type=METRIC_TYPE, labels=metric_labels),
+            resource=types.MonitoredResource(
+                type=RESOURCE_TYPE, labels=resource_labels),
+            metric_kind=METRIC_KIND,
+            value_type=VALUE_TYPE,
+            points=[P(t, value) for t in TIMESTAMPS],
+        )
+
+
+@unittest.skipUnless(HAVE_PANDAS, 'No pandas')
+class Test__build_dataframe(unittest.TestCase):  # pragma: NO COVER
+
+    def _call_fut(self, *args, **kwargs):
+        from google.cloud.monitoring._dataframe import _build_dataframe
+
+        return _build_dataframe(*args, **kwargs)
+
+    def test_both_label_and_labels_illegal(self):
+        with self.assertRaises(ValueError):
+            self._call_fut([], label='instance_name', labels=['zone'])
+
+    def test_empty_labels_illegal(self):
+        with self.assertRaises(ValueError):
+            self._call_fut([], labels=[])
+
+    def test_simple_label(self):
+        iterable = generate_query_results()
+        dataframe = self._call_fut(iterable, label='instance_name')
+
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
+
+        self.assertEqual(list(dataframe.columns), INSTANCE_NAMES)
+        self.assertIsNone(dataframe.columns.name)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_multiple_labels(self):
+        NAMES = ['resource_type', 'instance_id']
+
+        iterable = generate_query_results()
+        dataframe = self._call_fut(iterable, labels=NAMES)
+
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
+
+        expected_headers = [(RESOURCE_TYPE, instance_id)
+                            for instance_id in INSTANCE_IDS]
+        self.assertEqual(list(dataframe.columns), expected_headers)
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertIsNone(dataframe.columns.name)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_multiple_labels_with_just_one(self):
+        NAME = 'instance_id'
+        NAMES = [NAME]
+
+        iterable = generate_query_results()
+        dataframe = self._call_fut(iterable, labels=NAMES)
+
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
+
+        self.assertEqual(list(dataframe.columns), INSTANCE_IDS)
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertEqual(dataframe.columns.name, NAME)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_smart_labels(self):
+        NAMES = ['resource_type', 'project_id',
+                 'zone', 'instance_id',
+                 'instance_name']
+
+        iterable = generate_query_results()
+        dataframe = self._call_fut(iterable)
+
+        self.assertEqual(dataframe.shape, DIMENSIONS)
+        self.assertEqual(dataframe.values.tolist(), ARRAY)
+
+        expected_headers = [
+            (RESOURCE_TYPE, PROJECT, zone, instance_id, instance_name)
+            for zone, instance_id, instance_name
+            in zip(INSTANCE_ZONES, INSTANCE_IDS, INSTANCE_NAMES)]
+        self.assertEqual(list(dataframe.columns), expected_headers)
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertIsNone(dataframe.columns.name)
+
+        self.assertEqual(list(dataframe.index), parse_timestamps())
+        self.assertIsNone(dataframe.index.name)
+
+    def test_empty_table_simple_label(self):
+        dataframe = self._call_fut([], label='instance_name')
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertIsNone(dataframe.columns.name)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+    def test_empty_table_multiple_labels(self):
+        NAMES = ['resource_type', 'instance_id']
+        dataframe = self._call_fut([], labels=NAMES)
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertIsNone(dataframe.columns.name)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+    def test_empty_table_multiple_labels_with_just_one(self):
+        NAME = 'instance_id'
+        NAMES = [NAME]
+        dataframe = self._call_fut([], labels=NAMES)
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertEqual(dataframe.columns.name, NAME)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+    def test_empty_table_smart_labels(self):
+        NAME = 'resource_type'
+        NAMES = [NAME]
+        dataframe = self._call_fut([])
+        self.assertEqual(dataframe.shape, (0, 0))
+        self.assertEqual(dataframe.columns.names, NAMES)
+        self.assertEqual(dataframe.columns.name, NAME)
+        self.assertIsNone(dataframe.index.name)
+        self.assertIsInstance(dataframe.index, pandas.DatetimeIndex)
+
+
+class Test__sorted_resource_labels(unittest.TestCase):
+
+    def _call_fut(self, labels):
+        from google.cloud.monitoring._dataframe import _sorted_resource_labels
+
+        return _sorted_resource_labels(labels)
+
+    def test_empty(self):
+        self.assertEqual(self._call_fut([]), [])
+
+    def test_sorted(self):
+        from google.cloud.monitoring._dataframe import TOP_RESOURCE_LABELS
+
+        EXPECTED = TOP_RESOURCE_LABELS + ('other-1', 'other-2')
+        self.assertSequenceEqual(self._call_fut(EXPECTED), EXPECTED)
+
+    def test_reversed(self):
+        from google.cloud.monitoring._dataframe import TOP_RESOURCE_LABELS
+
+        EXPECTED = TOP_RESOURCE_LABELS + ('other-1', 'other-2')
+        INPUT = list(reversed(EXPECTED))
+        self.assertSequenceEqual(self._call_fut(INPUT), EXPECTED)
diff --git a/monitoring/tests/unit/test_query.py b/monitoring/tests/unit/test_query.py
new file mode 100644
index 000000000000..e3ca6bbaaccc
--- /dev/null
+++ b/monitoring/tests/unit/test_query.py
@@ -0,0 +1,593 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import copy
+import datetime
+import unittest
+import mock
+
+PROJECT = 'my-project'
+
+METRIC_TYPE = 'compute.googleapis.com/instance/uptime'
+METRIC_LABELS = {'instance_name': 'instance-1'}
+METRIC_LABELS2 = {'instance_name': 'instance-2'}
+
+RESOURCE_TYPE = 'gce_instance'
+RESOURCE_LABELS = {
+    'project_id': 'my-project',
+    'zone': 'us-east1-a',
+    'instance_id': '1234567890123456789',
+}
+RESOURCE_LABELS2 = {
+    'project_id': 'my-project',
+    'zone': 'us-east1-b',
+    'instance_id': '9876543210987654321',
+}
+
+METRIC_KIND = 'DELTA'
+VALUE_TYPE = 'DOUBLE'
+
+TS0 = datetime.datetime(2016, 4, 6, 22, 5, 0, 42)
+TS1 = datetime.datetime(2016, 4, 6, 22, 5, 1, 42)
+TS2 = datetime.datetime(2016, 4, 6, 22, 5, 2, 42)
+
+
+class MultiCallableStub(object):
+    """Stub for the grpc.UnaryUnaryMultiCallable interface."""
+
+    def __init__(self, method, channel_stub):
+        self.method = method
+        self.channel_stub = channel_stub
+
+    def __call__(self, request, timeout=None, metadata=None, credentials=None):
+        self.channel_stub.requests.append((self.method, request))
+
+        response = None
+        if self.channel_stub.responses:
+            response = self.channel_stub.responses.pop()
+
+        if isinstance(response, Exception):
+            raise response
+
+        if response:
+            return response
+
+
+class ChannelStub(object):
+    """Stub for the grpc.Channel interface."""
+
+    def __init__(self, responses=[]):
+        from google.cloud.monitoring_v3.proto import metric_service_pb2
+
+        self.responses = responses
+        self.responses = [
+            metric_service_pb2.ListTimeSeriesResponse(**response)
+            for response in responses
+        ]
+        self.requests = []
+
+    def unary_unary(self,
+                    method,
+                    request_serializer=None,
+                    response_deserializer=None):
+        return MultiCallableStub(method, self)
+
+
+class TestQuery(unittest.TestCase):
+
+    @staticmethod
+    def _get_target_class():
+        from google.cloud.monitoring.query import Query
+
+        return Query
+
+    def _make_one(self, *args, **kwargs):
+        return self._get_target_class()(*args, **kwargs)
+
+    @staticmethod
+    def _make_interval(end_time, start_time=None):
+        from google.cloud.monitoring_v3 import types
+
+        interval = types.TimeInterval()
+        interval.end_time.FromDatetime(end_time)
+        if start_time is not None:
+          interval.start_time.FromDatetime(start_time)
+        return interval
+
+    def test_constructor_minimal(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        # Mock the API response
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+
+        query = self._make_one(client, PROJECT)
+
+        self.assertEqual(query._client, client)
+        self.assertEqual(query._filter.metric_type,
+                         self._get_target_class().DEFAULT_METRIC_TYPE)
+
+        self.assertIsNone(query._start_time)
+        self.assertIsNone(query._end_time)
+
+        self.assertEqual(query._per_series_aligner, 0)
+        self.assertEqual(query._alignment_period_seconds, 0)
+        self.assertEqual(query._cross_series_reducer, 0)
+        self.assertEqual(query._group_by_fields, ())
+
+    def test_constructor_maximal(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
+        DAYS, HOURS, MINUTES = 1, 2, 3
+        T0 = T1 - datetime.timedelta(days=DAYS, hours=HOURS, minutes=MINUTES)
+
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE,
+                               end_time=T1,
+                               days=DAYS, hours=HOURS, minutes=MINUTES)
+
+        self.assertEqual(query._client, client)
+        self.assertEqual(query._filter.metric_type, METRIC_TYPE)
+
+        self.assertEqual(query._start_time, T0)
+        self.assertEqual(query._end_time, T1)
+
+        self.assertEqual(query._per_series_aligner, 0)
+        self.assertEqual(query._alignment_period_seconds, 0)
+        self.assertEqual(query._cross_series_reducer, 0)
+        self.assertEqual(query._group_by_fields, ())
+
+    def test_constructor_default_end_time(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        MINUTES = 5
+        NOW, T0, T1 = [
+            datetime.datetime(2016, 4, 7, 2, 30, 30),
+            datetime.datetime(2016, 4, 7, 2, 25, 0),
+            datetime.datetime(2016, 4, 7, 2, 30, 0),
+        ]
+
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        with mock.patch('google.cloud.monitoring.query._UTCNOW',
+                        new=lambda: NOW):
+            query = self._make_one(
+                client, PROJECT, METRIC_TYPE, minutes=MINUTES)
+
+        self.assertEqual(query._start_time, T0)
+        self.assertEqual(query._end_time, T1)
+
+    def test_constructor_nonzero_duration_illegal(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 30)
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        with self.assertRaises(ValueError):
+            self._make_one(client, PROJECT, METRIC_TYPE, end_time=T1)
+
+    def test_execution_without_interval_illegal(self):
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        with self.assertRaises(ValueError):
+            list(query)
+
+    def test_metric_type(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        self.assertEqual(query.metric_type, METRIC_TYPE)
+
+    def test_filter(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_group(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        GROUP = '1234567'
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_group(GROUP)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND group.id = "{group}"'
+        ).format(type=METRIC_TYPE, group=GROUP)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_projects(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        PROJECT1, PROJECT2 = 'project-1', 'project-2'
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_projects(PROJECT1, PROJECT2)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND project = "{project1}" OR project = "{project2}"'
+        ).format(type=METRIC_TYPE, project1=PROJECT1, project2=PROJECT2)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_resources(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        ZONE_PREFIX = 'europe-'
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_resources(zone_prefix=ZONE_PREFIX)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND resource.label.zone = starts_with("{prefix}")'
+        ).format(type=METRIC_TYPE, prefix=ZONE_PREFIX)
+        self.assertEqual(query.filter, expected)
+
+    def test_filter_by_metrics(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+
+        INSTANCE = 'my-instance'
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_metrics(instance_name=INSTANCE)
+        expected = (
+            'metric.type = "{type}"'
+            ' AND metric.label.instance_name = "{instance}"'
+        ).format(type=METRIC_TYPE, instance=INSTANCE)
+        self.assertEqual(query.filter, expected)
+
+    def test_request_parameters_minimal(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+        from google.cloud.monitoring_v3.gapic import enums
+
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
+
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_interval(end_time=T1)
+        actual = query._build_query_params()
+        expected = {
+            'name': u'projects/{}'.format(PROJECT),
+            'filter_': 'metric.type = "{type}"'.format(type=METRIC_TYPE),
+            'interval': self._make_interval(T1),
+            'view': enums.ListTimeSeriesRequest.TimeSeriesView.FULL,
+        }
+        self.assertEqual(actual, expected)
+
+    def test_request_parameters_maximal(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+        from google.cloud.monitoring_v3 import types
+        from google.cloud.monitoring_v3.gapic import enums
+
+        T0 = datetime.datetime(2016, 4, 7, 2, 0, 0)
+        T1 = datetime.datetime(2016, 4, 7, 2, 30, 0)
+
+        ALIGNER = 'ALIGN_DELTA'
+        MINUTES, SECONDS, PERIOD_IN_SECONDS = 1, 30, 90
+
+        REDUCER = 'REDUCE_MEAN'
+        FIELD1, FIELD2 = 'resource.zone', 'metric.instance_name'
+
+        PAGE_SIZE = 100
+        PAGE_TOKEN = 'second-page-please'
+
+        channel = ChannelStub()
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        query = query.align(ALIGNER, minutes=MINUTES, seconds=SECONDS)
+        query = query.reduce(REDUCER, FIELD1, FIELD2)
+        actual = query._build_query_params(headers_only=True,
+                                           page_size=PAGE_SIZE)
+        expected = {
+            'name': 'projects/%s' % PROJECT,
+            'filter_': 'metric.type = "{type}"'.format(type=METRIC_TYPE),
+            'interval': self._make_interval(T1, T0),
+            'aggregation': types.Aggregation(
+                per_series_aligner=ALIGNER,
+                alignment_period={'seconds': PERIOD_IN_SECONDS},
+                cross_series_reducer=REDUCER,
+                group_by_fields=[FIELD1, FIELD2],
+            ),
+            'view': enums.ListTimeSeriesRequest.TimeSeriesView.HEADERS,
+            'page_size': PAGE_SIZE,
+        }
+        self.assertEqual(actual, expected)
+
+    def test_iteration(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+        from google.cloud.monitoring_v3.gapic import enums
+        from google.cloud.monitoring_v3.proto import metric_service_pb2
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        INTERVAL1 = self._make_interval(TS1, TS0)
+        INTERVAL2 = self._make_interval(TS2, TS1)
+
+        VALUE1 = 60  # seconds
+        VALUE2 = 60.001  # seconds
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metric_kind': METRIC_KIND,
+            'value_type': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'double_value': VALUE1}},
+                {'interval': INTERVAL1, 'value': {'double_value': VALUE1}},
+            ],
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metric_kind': METRIC_KIND,
+            'value_type': VALUE_TYPE,
+            'points': [
+                {'interval': INTERVAL2, 'value': {'double_value': VALUE2}},
+                {'interval': INTERVAL1, 'value': {'double_value': VALUE2}},
+            ],
+        }
+
+        RESPONSE = {'time_series': [SERIES1, SERIES2], 'next_page_token': ''}
+
+        channel = ChannelStub(responses=[RESPONSE])
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertEqual([p.value.double_value for p in series1.points],
+                         [VALUE1, VALUE1])
+        self.assertEqual([p.value.double_value for p in series2.points],
+                         [VALUE2, VALUE2])
+        self.assertEqual([p.interval for p in series1.points],
+                         [INTERVAL2, INTERVAL1])
+        self.assertEqual([p.interval for p in series2.points],
+                         [INTERVAL2, INTERVAL1])
+
+        expected_request = metric_service_pb2.ListTimeSeriesRequest(
+            name='projects/' + PROJECT,
+            filter='metric.type = "{type}"'.format(type=METRIC_TYPE),
+            interval=self._make_interval(T1, T0),
+            view=enums.ListTimeSeriesRequest.TimeSeriesView.FULL
+        )
+        request = channel.requests[0][1]
+        self.assertEqual(request, expected_request)
+
+    def test_iteration_empty(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+        from google.cloud.monitoring_v3.gapic import enums
+        from google.cloud.monitoring_v3.proto import metric_service_pb2
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        channel = ChannelStub(responses=[{'next_page_token': ''}])
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query)
+
+        self.assertEqual(len(response), 0)
+
+        expected_request = metric_service_pb2.ListTimeSeriesRequest(
+            name='projects/' + PROJECT,
+            filter='metric.type = "{type}"'.format(type=METRIC_TYPE),
+            interval=self._make_interval(T1, T0),
+            view=enums.ListTimeSeriesRequest.TimeSeriesView.FULL
+        )
+        request = channel.requests[0][1]
+        self.assertEqual(request, expected_request)
+
+    def test_iteration_headers_only(self):
+        from google.cloud.monitoring_v3 import MetricServiceClient
+        from google.cloud.monitoring_v3.gapic import enums
+        from google.cloud.monitoring_v3.proto import metric_service_pb2
+
+        T0 = datetime.datetime(2016, 4, 6, 22, 5, 0)
+        T1 = datetime.datetime(2016, 4, 6, 22, 10, 0)
+
+        SERIES1 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS},
+            'metric_kind': METRIC_KIND,
+            'value_type': VALUE_TYPE,
+        }
+        SERIES2 = {
+            'metric': {'type': METRIC_TYPE, 'labels': METRIC_LABELS2},
+            'resource': {'type': RESOURCE_TYPE, 'labels': RESOURCE_LABELS2},
+            'metric_kind': METRIC_KIND,
+            'value_type': VALUE_TYPE,
+        }
+
+        RESPONSE = {'time_series': [SERIES1, SERIES2], 'next_page_token': ''}
+
+        channel = ChannelStub(responses=[RESPONSE])
+        client = MetricServiceClient(channel=channel)
+        query = self._make_one(client, PROJECT, METRIC_TYPE)
+        query = query.select_interval(start_time=T0, end_time=T1)
+        response = list(query.iter(headers_only=True))
+
+        self.assertEqual(len(response), 2)
+        series1, series2 = response
+
+        self.assertEqual(series1.metric.labels, METRIC_LABELS)
+        self.assertEqual(series2.metric.labels, METRIC_LABELS2)
+        self.assertEqual(series1.resource.labels, RESOURCE_LABELS)
+        self.assertEqual(series2.resource.labels, RESOURCE_LABELS2)
+
+        self.assertFalse(len(series1.points))
+        self.assertFalse(len(series2.points))
+
+        expected_request = metric_service_pb2.ListTimeSeriesRequest(
+            name='projects/' + PROJECT,
+            filter='metric.type = "{type}"'.format(type=METRIC_TYPE),
+            interval=self._make_interval(T1, T0),
+            view=enums.ListTimeSeriesRequest.TimeSeriesView.HEADERS
+        )
+        request = channel.requests[0][1]
+        self.assertEqual(request, expected_request)
+
+
+class Test_Filter(unittest.TestCase):
+
+    @staticmethod
+    def _get_target_class():
+        from google.cloud.monitoring.query import _Filter
+
+        return _Filter
+
+    def _make_one(self, metric_type):
+        return self._get_target_class()(metric_type)
+
+    def test_minimal(self):
+        obj = self._make_one(METRIC_TYPE)
+        expected = 'metric.type = "{type}"'.format(type=METRIC_TYPE)
+        self.assertEqual(str(obj), expected)
+
+    def test_maximal(self):
+        obj = self._make_one(METRIC_TYPE)
+        obj.group_id = '1234567'
+        obj.projects = 'project-1', 'project-2'
+        obj.select_resources(resource_type='some-resource',
+                             resource_label='foo')
+        obj.select_metrics(metric_label_prefix='bar-')
+
+        expected = (
+            'metric.type = "{type}"'
+            ' AND group.id = "1234567"'
+            ' AND project = "project-1" OR project = "project-2"'
+            ' AND resource.label.resource_label = "foo"'
+            ' AND resource.type = "some-resource"'
+            ' AND metric.label.metric_label = starts_with("bar-")'
+        ).format(type=METRIC_TYPE)
+
+        self.assertEqual(str(obj), expected)
+
+
+class Test__build_label_filter(unittest.TestCase):
+
+    def _call_fut(self, *args, **kwargs):
+        from google.cloud.monitoring.query import _build_label_filter
+
+        return _build_label_filter(*args, **kwargs)
+
+    def test_no_labels(self):
+        self.assertEqual(self._call_fut('resource'), '')
+
+    def test_label_is_none(self):
+        self.assertEqual(self._call_fut('resource', foo=None), '')
+
+    def test_metric_labels(self):
+        actual = self._call_fut(
+            'metric',
+            alpha_prefix='a-',
+            beta_gamma_suffix='-b',
+            delta_epsilon='xyz',
+        )
+        expected = (
+            'metric.label.alpha = starts_with("a-")'
+            ' AND metric.label.beta_gamma = ends_with("-b")'
+            ' AND metric.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_metric_label_response_code_greater_less(self):
+        actual = self._call_fut(
+            'metric',
+            response_code_greater=500,
+            response_code_less=600)
+        expected = (
+            'metric.label.response_code < 600'
+            ' AND metric.label.response_code > 500'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_metric_label_response_code_greater_less_equal(self):
+        actual = self._call_fut(
+            'metric',
+            response_code_greaterequal=500,
+            response_code_lessequal=600)
+        expected = (
+            'metric.label.response_code <= 600'
+            ' AND metric.label.response_code >= 500'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_resource_labels(self):
+        actual = self._call_fut(
+            'resource',
+            alpha_prefix='a-',
+            beta_gamma_suffix='-b',
+            delta_epsilon='xyz',
+        )
+        expected = (
+            'resource.label.alpha = starts_with("a-")'
+            ' AND resource.label.beta_gamma = ends_with("-b")'
+            ' AND resource.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_raw_label_filters(self):
+        actual = self._call_fut(
+            'resource',
+            'resource.label.alpha = starts_with("a-")',
+            'resource.label.beta_gamma = ends_with("-b")',
+            'resource.label.delta_epsilon = "xyz"',
+        )
+        expected = (
+            'resource.label.alpha = starts_with("a-")'
+            ' AND resource.label.beta_gamma = ends_with("-b")'
+            ' AND resource.label.delta_epsilon = "xyz"'
+        )
+        self.assertEqual(actual, expected)
+
+    def test_resource_type(self):
+        actual = self._call_fut('resource', resource_type='foo')
+        expected = 'resource.type = "foo"'
+        self.assertEqual(actual, expected)
+
+    def test_resource_type_prefix(self):
+        actual = self._call_fut('resource', resource_type_prefix='foo-')
+        expected = 'resource.type = starts_with("foo-")'
+        self.assertEqual(actual, expected)
+
+    def test_resource_type_suffix(self):
+        actual = self._call_fut('resource', resource_type_suffix='-foo')
+        expected = 'resource.type = ends_with("-foo")'
+        self.assertEqual(actual, expected)