feat: Added support for Monitoring Query Language

.coveragerc

@@ -1,29 +1,11 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2020 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
-#
-#     https://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.
-
-# Generated by synthtool. DO NOT EDIT!
 [run]
 branch = True
-omit =
-  google/cloud/__init__.py
 
 [report]
 fail_under = 100
 show_missing = True
-omit = google/cloud/monitoring/__init__.py
+omit =
+    google/cloud/monitoring/__init__.py
 exclude_lines =
     # Re-enable the standard pragma
     pragma: NO COVER

docs/monitoring_v3/alert_policy_service.rst

@@ -0,0 +1,11 @@
+AlertPolicyService
+------------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.alert_policy_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.alert_policy_service.pagers
+    :members:
+    :inherited-members:

docs/monitoring_v3/group_service.rst

@@ -0,0 +1,11 @@
+GroupService
+------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.group_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.group_service.pagers
+    :members:
+    :inherited-members:

docs/monitoring_v3/metric_service.rst

@@ -0,0 +1,11 @@
+MetricService
+-------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.metric_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.metric_service.pagers
+    :members:
+    :inherited-members:

docs/monitoring_v3/notification_channel_service.rst

@@ -0,0 +1,11 @@
+NotificationChannelService
+--------------------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.notification_channel_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.notification_channel_service.pagers
+    :members:
+    :inherited-members:

docs/monitoring_v3/query_service.rst

@@ -0,0 +1,11 @@
+QueryService
+------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.query_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.query_service.pagers
+    :members:
+    :inherited-members:

docs/monitoring_v3/service_monitoring_service.rst

@@ -0,0 +1,11 @@
+ServiceMonitoringService
+------------------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.service_monitoring_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.service_monitoring_service.pagers
+    :members:
+    :inherited-members:

docs/monitoring_v3/services.rst

@@ -1,21 +1,12 @@
 Services for Google Cloud Monitoring v3 API
 ===========================================
+.. toctree::
+    :maxdepth: 2
 
-.. automodule:: google.cloud.monitoring_v3.services.alert_policy_service
-    :members:
-    :inherited-members:
-.. automodule:: google.cloud.monitoring_v3.services.group_service
-    :members:
-    :inherited-members:
-.. automodule:: google.cloud.monitoring_v3.services.metric_service
-    :members:
-    :inherited-members:
-.. automodule:: google.cloud.monitoring_v3.services.notification_channel_service
-    :members:
-    :inherited-members:
-.. automodule:: google.cloud.monitoring_v3.services.service_monitoring_service
-    :members:
-    :inherited-members:
-.. automodule:: google.cloud.monitoring_v3.services.uptime_check_service
-    :members:
-    :inherited-members:
+    alert_policy_service
+    group_service
+    metric_service
+    notification_channel_service
+    query_service
+    service_monitoring_service
+    uptime_check_service

docs/monitoring_v3/types.rst

@@ -3,4 +3,5 @@ Types for Google Cloud Monitoring v3 API
 
 .. automodule:: google.cloud.monitoring_v3.types
     :members:
+    :undoc-members:
     :show-inheritance:

docs/monitoring_v3/uptime_check_service.rst

@@ -0,0 +1,11 @@
+UptimeCheckService
+------------------------------------
+
+.. automodule:: google.cloud.monitoring_v3.services.uptime_check_service
+    :members:
+    :inherited-members:
+
+
+.. automodule:: google.cloud.monitoring_v3.services.uptime_check_service.pagers
+    :members:
+    :inherited-members:

google/cloud/monitoring/__init__.py

@@ -37,6 +37,10 @@
 from google.cloud.monitoring_v3.services.notification_channel_service.client import (
     NotificationChannelServiceClient,
 )
+from google.cloud.monitoring_v3.services.query_service.async_client import (
+    QueryServiceAsyncClient,
+)
+from google.cloud.monitoring_v3.services.query_service.client import QueryServiceClient
 from google.cloud.monitoring_v3.services.service_monitoring_service.async_client import (
     ServiceMonitoringServiceAsyncClient,
 )
@@ -283,6 +287,8 @@
     "Point",
     "QueryError",
     "QueryErrorList",
+    "QueryServiceAsyncClient",
+    "QueryServiceClient",
     "QueryTimeSeriesRequest",
     "QueryTimeSeriesResponse",
     "Range",

google/cloud/monitoring_v3/__init__.py

@@ -19,6 +19,7 @@
 from .services.group_service import GroupServiceClient
 from .services.metric_service import MetricServiceClient
 from .services.notification_channel_service import NotificationChannelServiceClient
+from .services.query_service import QueryServiceClient
 from .services.service_monitoring_service import ServiceMonitoringServiceClient
 from .services.uptime_check_service import UptimeCheckServiceClient
 from .types.alert import AlertPolicy
@@ -122,6 +123,7 @@
 __all__ = (
     "Aggregation",
     "AlertPolicy",
+    "AlertPolicyServiceClient",
     "BasicSli",
     "ComparisonType",
     "CreateAlertPolicyRequest",
@@ -183,14 +185,14 @@
     "ListUptimeCheckConfigsResponse",
     "ListUptimeCheckIpsRequest",
     "ListUptimeCheckIpsResponse",
-    "MetricServiceClient",
     "MutationRecord",
     "NotificationChannel",
     "NotificationChannelDescriptor",
     "NotificationChannelServiceClient",
     "Point",
     "QueryError",
     "QueryErrorList",
+    "QueryServiceClient",
     "QueryTimeSeriesRequest",
     "QueryTimeSeriesResponse",
     "Range",
@@ -221,5 +223,5 @@
     "UptimeCheckServiceClient",
     "VerifyNotificationChannelRequest",
     "WindowsBasedSli",
-    "AlertPolicyServiceClient",
+    "MetricServiceClient",
 )

google/cloud/monitoring_v3/proto/alert.proto

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.monitoring.v3;
 
+import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/monitoring/v3/common.proto";
 import "google/monitoring/v3/mutation_record.proto";
@@ -89,17 +90,17 @@ message AlertPolicy {
     // A condition type that compares a collection of time series
     // against a threshold.
     message MetricThreshold {
-      // A [filter](https://cloud.google.com/monitoring/api/v3/filters) that
+      // Required. A [filter](https://cloud.google.com/monitoring/api/v3/filters) that
       // identifies which time series should be compared with the threshold.
       //
       // The filter is similar to the one that is specified in the
       // [`ListTimeSeries`
       // request](https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list)
       // (that call is useful to verify the time series that will be retrieved /
-      // processed) and must specify the metric type and optionally may contain
-      // restrictions on resource type, resource labels, and metric labels.
-      // This field may not exceed 2048 Unicode characters in length.
-      string filter = 2;
+      // processed). The filter must specify the metric type and the resource
+      // type. Optionally, it can specify resource labels and metric labels.
+      // This field must not exceed 2048 Unicode characters in length.
+      string filter = 2 [(google.api.field_behavior) = REQUIRED];
 
       // Specifies the alignment of data points in individual time series as
       // well as how to combine the retrieved time series together (such as
@@ -175,17 +176,17 @@ message AlertPolicy {
     // when a time series for the specified metric of a monitored
     // resource does not include any data in the specified `duration`.
     message MetricAbsence {
-      // A [filter](https://cloud.google.com/monitoring/api/v3/filters) that
+      // Required. A [filter](https://cloud.google.com/monitoring/api/v3/filters) that
       // identifies which time series should be compared with the threshold.
       //
       // The filter is similar to the one that is specified in the
       // [`ListTimeSeries`
       // request](https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list)
       // (that call is useful to verify the time series that will be retrieved /
-      // processed) and must specify the metric type and optionally may contain
-      // restrictions on resource type, resource labels, and metric labels.
-      // This field may not exceed 2048 Unicode characters in length.
-      string filter = 1;
+      // processed). The filter must specify the metric type and the resource
+      // type. Optionally, it can specify resource labels and metric labels.
+      // This field must not exceed 2048 Unicode characters in length.
+      string filter = 1 [(google.api.field_behavior) = REQUIRED];
 
       // Specifies the alignment of data points in individual time series as
       // well as how to combine the retrieved time series together (such as
@@ -201,9 +202,10 @@ message AlertPolicy {
       repeated Aggregation aggregations = 5;
 
       // The amount of time that a time series must fail to report new
-      // data to be considered failing. Currently, only values that
-      // are a multiple of a minute--e.g.  60, 120, or 300
-      // seconds--are supported. If an invalid value is given, an
+      // data to be considered failing. The minimum value of this field
+      // is 120 seconds. Larger values that are a multiple of a
+      // minute--for example, 240 or 300 seconds--are supported.
+      // If an invalid value is given, an
       // error will be returned. The `Duration.nanos` field is
       // ignored.
       google.protobuf.Duration duration = 2;
@@ -215,6 +217,34 @@ message AlertPolicy {
       Trigger trigger = 3;
     }
 
+    // A condition type that allows alert policies to be defined using
+    // [Monitoring Query Language](https://cloud.google.com/monitoring/mql).
+    message MonitoringQueryLanguageCondition {
+      // [Monitoring Query Language](https://cloud.google.com/monitoring/mql)
+      // query that outputs a boolean stream.
+      string query = 1;
+
+      // The amount of time that a time series must violate the
+      // threshold to be considered failing. Currently, only values
+      // that are a multiple of a minute--e.g., 0, 60, 120, or 300
+      // seconds--are supported. If an invalid value is given, an
+      // error will be returned. When choosing a duration, it is useful to
+      // keep in mind the frequency of the underlying time series data
+      // (which may also be affected by any alignments specified in the
+      // `aggregations` field); a good duration is long enough so that a single
+      // outlier does not generate spurious alerts, but short enough that
+      // unhealthy states are detected and alerted on quickly.
+      google.protobuf.Duration duration = 2;
+
+      // The number/percent of time series for which the comparison must hold
+      // in order for the condition to trigger. If unspecified, then the
+      // condition will trigger if the comparison is true for any of the
+      // time series that have been identified by `filter` and `aggregations`,
+      // or by the ratio, if `denominator_filter` and `denominator_aggregations`
+      // are specified.
+      Trigger trigger = 3;
+    }
+
     // Required if the condition exists. The unique resource name for this
     // condition. Its format is:
     //
@@ -255,6 +285,10 @@ message AlertPolicy {
       // A condition that checks that a time series continues to
       // receive new data points.
       MetricAbsence condition_absent = 2;
+
+      // A condition that uses the Monitoring Query Language to define
+      // alerts.
+      MonitoringQueryLanguageCondition condition_monitoring_query_language = 19;
     }
   }
 

google/cloud/monitoring_v3/proto/alert_service.proto

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -48,7 +48,7 @@ service AlertPolicyService {
       "https://www.googleapis.com/auth/monitoring,"
       "https://www.googleapis.com/auth/monitoring.read";
 
-  // Lists the existing alerting policies for the project.
+  // Lists the existing alerting policies for the workspace.
   rpc ListAlertPolicies(ListAlertPoliciesRequest) returns (ListAlertPoliciesResponse) {
     option (google.api.http) = {
       get: "/v3/{name=projects/*}/alertPolicies"
@@ -101,10 +101,11 @@ message CreateAlertPolicyRequest {
   //     projects/[PROJECT_ID_OR_NUMBER]
   //
   // Note that this field names the parent container in which the alerting
-  // policy will be written, not the name of the created policy. The alerting
-  // policy that is returned will have a name that contains a normalized
-  // representation of this name as a prefix but adds a suffix of the form
-  // `/alertPolicies/[ALERT_POLICY_ID]`, identifying the policy in the
+  // policy will be written, not the name of the created policy. |name| must be
+  // a host project of a workspace, otherwise INVALID_ARGUMENT error will
+  // return. The alerting policy that is returned will have a name that contains
+  // a normalized representation of this name as a prefix but adds a suffix of
+  // the form `/alertPolicies/[ALERT_POLICY_ID]`, identifying the policy in the
   // container.
   string name = 3 [
     (google.api.field_behavior) = REQUIRED,
@@ -183,6 +184,10 @@ message ListAlertPoliciesResponse {
   // to a non-empty value. To see the additional results,
   // use that value as `page_token` in the next call to this method.
   string next_page_token = 2;
+
+  // The total number of alert policies in all pages. This number is only an
+  // estimate, and may change in subsequent pages. https://aip.dev/158
+  int32 total_size = 4;
 }
 
 // The protocol for the `UpdateAlertPolicy` request.