feat: Added support for Monitoring Query Language: https://cloud.goog…

…le.com/monitoring/mql feat: Added support for units in the MetricService feat: Added total_size to the response of ListAlertPolicies. fix: Un-deprecated cluster_istio for service monitoring. feat: Added IstioCanonicalService for service monitoring. feat: Added creation and mutation records to notification channels. feat: Added support for querying metrics for folders and organizations. fix: Extended the default deadline for UpdateGroup to 180s. feat: Added support for secondary aggregation when querying metrics. (#523)

PiperOrigin-RevId: 364422694

Source-Author: Google APIs <noreply@google.com>
Source-Date: Mon Mar 22 15:30:13 2021 -0700
Source-Repo: googleapis/googleapis
Source-Sha: 2124b6251e56e2ec8dd5c47e7d3815d7d5841880
Source-Link: googleapis/googleapis@2124b62

Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

protos/google/monitoring/v3/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;
     }
   }
 

protos/google/monitoring/v3/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.

protos/google/monitoring/v3/common.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.
@@ -51,28 +51,34 @@ message TypedValue {
   }
 }
 
-// A closed time interval. It extends from the start time to the end time, and
-// includes both: `[startTime, endTime]`. Valid time intervals depend on the
-// [`MetricKind`](https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricKind)
-// of the metric value. In no case can the end time be earlier than the start
-// time.
+// A closed time interval. It extends from the start time to the end time, and includes both: `[startTime, endTime]`. Valid time intervals depend on the [`MetricKind`](/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricKind) of the metric value. The end time must not be earlier than the start time. When writing data points, the start time must not be more than 25 hours in the past and the end time must not be more than five minutes in the future.
 //
-// * For a `GAUGE` metric, the `startTime` value is technically optional; if
+// * For `GAUGE` metrics, the `startTime` value is technically optional; if
 //   no value is specified, the start time defaults to the value of the
 //   end time, and the interval represents a single point in time. If both
 //   start and end times are specified, they must be identical. Such an
 //   interval is valid only for `GAUGE` metrics, which are point-in-time
-//   measurements.
+//   measurements. The end time of a new interval must be at least a
+//   millisecond after the end time of the previous interval.
 //
-// * For `DELTA` and `CUMULATIVE` metrics, the start time must be earlier
-//   than the end time.
+// * For `DELTA` metrics, the start time and end time must specify a
+//   non-zero interval, with subsequent points specifying contiguous and
+//   non-overlapping intervals. For `DELTA` metrics, the start time of
+//   the next interval must be at least a millisecond after the end time
+//   of the previous interval.
 //
-// * In all cases, the start time of the next interval must be
-//   at least a millisecond after the end time of the previous interval.
-//   Because the interval is closed, if the start time of a new interval
-//   is the same as the end time of the previous interval, data written
-//   at the new start time could overwrite data written at the previous
-//   end time.
+// * For `CUMULATIVE` metrics, the start time and end time must specify a
+//   a non-zero interval, with subsequent points specifying the same
+//   start time and increasing end times, until an event resets the
+//   cumulative value to zero and sets a new start time for the following
+//   points. The new start time must be at least a millisecond after the
+//   end time of the previous interval.
+//
+// * The start time of a new interval must be at least a millisecond after the
+//   end time of the previous interval because intervals are closed. If the
+//   start time of a new interval is the same as the end time of the previous
+//   interval, then data written at the new start time could overwrite data
+//   written at the previous end time.
 message TimeInterval {
   // Required. The end of the time interval.
   google.protobuf.Timestamp end_time = 2;
@@ -370,10 +376,13 @@ message Aggregation {
   // time. This will be done before the per-series aligner can be applied to
   // the data.
   //
-  // The value must be at least 60 seconds. If a per-series aligner other than
-  // `ALIGN_NONE` is specified, this field is required or an error is returned.
-  // If no per-series aligner is specified, or the aligner `ALIGN_NONE` is
-  // specified, then this field is ignored.
+  // The value must be at least 60 seconds. If a per-series
+  // aligner other than `ALIGN_NONE` is specified, this field is required or an
+  // error is returned. If no per-series aligner is specified, or the aligner
+  // `ALIGN_NONE` is specified, then this field is ignored.
+  //
+  // The maximum value of the `alignment_period` is 104 weeks (2 years) for
+  // charts, and 90,000 seconds (25 hours) for alerting policies.
   google.protobuf.Duration alignment_period = 1;
 
   // An `Aligner` describes how to bring the data points in a single

protos/google/monitoring/v3/dropped_labels.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.
@@ -24,16 +24,17 @@ option java_package = "com.google.monitoring.v3";
 option php_namespace = "Google\\Cloud\\Monitoring\\V3";
 option ruby_package = "Google::Cloud::Monitoring::V3";
 
-// A set of (label, value) pairs which were dropped during aggregation, attached
-// to google.api.Distribution.Exemplars in google.api.Distribution values during
-// aggregation.
+// A set of (label, value) pairs that were removed from a Distribution
+// time series during aggregation and then added as an attachment to a
+// Distribution.Exemplar.
 //
-// These values are used in combination with the label values that remain on the
-// aggregated Distribution timeseries to construct the full label set for the
-// exemplar values.  The resulting full label set may be used to identify the
-// specific task/job/instance (for example) which may be contributing to a
-// long-tail, while allowing the storage savings of only storing aggregated
-// distribution values for a large group.
+// The full label set for the exemplars is constructed by using the dropped
+// pairs in combination with the label values that remain on the aggregated
+// Distribution time series. The constructed full label set can be used to
+// identify the specific entity, such as the instance or job, which might be
+// contributing to a long-tail. However, with dropped labels, the storage
+// requirements are reduced because only the aggregated distribution values for
+// a large group of time series are stored.
 //
 // Note that there are no guarantees on ordering of the labels from
 // exemplar-to-exemplar and from distribution-to-distribution in the same

protos/google/monitoring/v3/group.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.

protos/google/monitoring/v3/group_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.

protos/google/monitoring/v3/metric.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.
@@ -62,8 +62,8 @@ message TimeSeries {
   google.api.MonitoredResource resource = 2;
 
   // Output only. The associated monitored resource metadata. When reading a
-  // a timeseries, this field will include metadata labels that are explicitly
-  // named in the reduction. When creating a timeseries, this field is ignored.
+  // time series, this field will include metadata labels that are explicitly
+  // named in the reduction. When creating a time series, this field is ignored.
   google.api.MonitoredResourceMetadata metadata = 7;
 
   // The metric kind of the time series. When listing time series, this metric
@@ -94,9 +94,14 @@ message TimeSeries {
   // the value type of the descriptor is determined by the point's type, which
   // must be `BOOL`, `INT64`, `DOUBLE`, or `DISTRIBUTION`.
   repeated Point points = 5;
+
+  // The units in which the metric value is reported. It is only applicable
+  // if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`
+  // defines the representation of the stored metric values.
+  string unit = 8;
 }
 
-// A descriptor for the labels and points in a timeseries.
+// A descriptor for the labels and points in a time series.
 message TimeSeriesDescriptor {
   // A descriptor for the value columns in a data point.
   message ValueDescriptor {
@@ -108,6 +113,12 @@ message TimeSeriesDescriptor {
 
     // The value stream kind.
     google.api.MetricDescriptor.MetricKind metric_kind = 3;
+
+    // The unit in which `time_series` point values are reported. `unit`
+    // follows the UCUM format for units as seen in
+    // https://unitsofmeasure.org/ucum.html.
+    // `unit` is only valid if `value_type` is INTEGER, DOUBLE, DISTRIBUTION.
+    string unit = 4;
   }
 
   // Descriptors for the labels.