Skip to content

Commit babab51

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Added support for retriggering notifications in AlertPolicy
feat: Added support for forecast options in AlertPolicy feat: Added support for promQL condition type in AlertPolicy PiperOrigin-RevId: 564411592
1 parent 15b48f9 commit babab51

6 files changed

Lines changed: 265 additions & 43 deletions

File tree

‎google/monitoring/v3/alert.proto‎

Lines changed: 176 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2023 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -36,6 +36,7 @@ option ruby_package = "Google::Cloud::Monitoring::V3";
3636
// considered to be "unhealthy" and the ways to notify people or services about
3737
// this state. For an overview of alert policies, see
3838
// [Introduction to Alerting](https://cloud.google.com/monitoring/alerts/).
39+
//
3940
message AlertPolicy {
4041
option (google.api.resource) = {
4142
type: "monitoring.googleapis.com/AlertPolicy"
@@ -48,7 +49,7 @@ message AlertPolicy {
4849
// A content string and a MIME type that describes the content string's
4950
// format.
5051
message Documentation {
51-
// The text of the documentation, interpreted according to `mime_type`.
52+
// The body of the documentation, interpreted according to `mime_type`.
5253
// The content may not exceed 8,192 Unicode characters and may not exceed
5354
// more than 10,240 bytes when encoded in UTF-8 format, whichever is
5455
// smaller. This text can be [templatized by using
@@ -59,6 +60,21 @@ message AlertPolicy {
5960
// `"text/markdown"` is supported. See
6061
// [Markdown](https://en.wikipedia.org/wiki/Markdown) for more information.
6162
string mime_type = 2;
63+
64+
// Optional. The subject line of the notification. The subject line may not
65+
// exceed 10,240 bytes. In notifications generated by this policy, the
66+
// contents of the subject line after variable expansion will be truncated
67+
// to 255 bytes or shorter at the latest UTF-8 character boundary. The
68+
// 255-byte limit is recommended by [this
69+
// thread](https://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit).
70+
// It is both the limit imposed by some third-party ticketing products and
71+
// it is common to define textual fields in databases as VARCHAR(255).
72+
//
73+
// The contents of the subject line can be [templatized by using
74+
// variables](https://cloud.google.com/monitoring/alerts/doc-variables).
75+
// If this field is missing or empty, a default subject line will be
76+
// generated.
77+
string subject = 3 [(google.api.field_behavior) = OPTIONAL];
6278
}
6379

6480
// A condition is a true/false test that determines when an alerting policy
@@ -111,7 +127,20 @@ message AlertPolicy {
111127
// A condition type that compares a collection of time series
112128
// against a threshold.
113129
message MetricThreshold {
114-
// Required. A [filter](https://cloud.google.com/monitoring/api/v3/filters) that
130+
// Options used when forecasting the time series and testing
131+
// the predicted value against the threshold.
132+
message ForecastOptions {
133+
// Required. The length of time into the future to forecast whether a
134+
// time series will violate the threshold. If the predicted value is
135+
// found to violate the threshold, and the violation is observed in all
136+
// forecasts made for the configured `duration`, then the time series is
137+
// considered to be failing.
138+
google.protobuf.Duration forecast_horizon = 1
139+
[(google.api.field_behavior) = REQUIRED];
140+
}
141+
142+
// Required. A
143+
// [filter](https://cloud.google.com/monitoring/api/v3/filters) that
115144
// identifies which time series should be compared with the threshold.
116145
//
117146
// The filter is similar to the one that is specified in the
@@ -159,6 +188,13 @@ message AlertPolicy {
159188
// and produce time series that have the same periodicity and labels.
160189
repeated Aggregation denominator_aggregations = 10;
161190

191+
// When this field is present, the `MetricThreshold` condition forecasts
192+
// whether the time series is predicted to violate the threshold within
193+
// the `forecast_horizon`. When this field is not set, the
194+
// `MetricThreshold` tests the current value of the timeseries against the
195+
// threshold.
196+
ForecastOptions forecast_options = 12;
197+
162198
// The comparison to apply between the time series (indicated by `filter`
163199
// and `aggregation`) and the threshold (indicated by `threshold_value`).
164200
// The comparison is applied on each time series, with the time series
@@ -201,7 +237,8 @@ message AlertPolicy {
201237
// when a time series for the specified metric of a monitored
202238
// resource does not include any data in the specified `duration`.
203239
message MetricAbsence {
204-
// Required. A [filter](https://cloud.google.com/monitoring/api/v3/filters) that
240+
// Required. A
241+
// [filter](https://cloud.google.com/monitoring/api/v3/filters) that
205242
// identifies which time series should be compared with the threshold.
206243
//
207244
// The filter is similar to the one that is specified in the
@@ -298,6 +335,100 @@ message AlertPolicy {
298335
EvaluationMissingData evaluation_missing_data = 4;
299336
}
300337

338+
// A condition type that allows alert policies to be defined using
339+
// [Prometheus Query Language
340+
// (PromQL)](https://prometheus.io/docs/prometheus/latest/querying/basics/).
341+
//
342+
// The PrometheusQueryLanguageCondition message contains information
343+
// from a Prometheus alerting rule and its associated rule group.
344+
//
345+
// A Prometheus alerting rule is described
346+
// [here](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/).
347+
// The semantics of a Prometheus alerting rule is described
348+
// [here](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#rule).
349+
//
350+
// A Prometheus rule group is described
351+
// [here](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/).
352+
// The semantics of a Prometheus rule group is described
353+
// [here](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#rule_group).
354+
//
355+
// Because Cloud Alerting has no representation of a Prometheus rule
356+
// group resource, we must embed the information of the parent rule
357+
// group inside each of the conditions that refer to it. We must also
358+
// update the contents of all Prometheus alerts in case the information
359+
// of their rule group changes.
360+
//
361+
// The PrometheusQueryLanguageCondition protocol buffer combines the
362+
// information of the corresponding rule group and alerting rule.
363+
// The structure of the PrometheusQueryLanguageCondition protocol buffer
364+
// does NOT mimic the structure of the Prometheus rule group and alerting
365+
// rule YAML declarations. The PrometheusQueryLanguageCondition protocol
366+
// buffer may change in the future to support future rule group and/or
367+
// alerting rule features. There are no new such features at the present
368+
// time (2023-06-26).
369+
message PrometheusQueryLanguageCondition {
370+
// Required. The PromQL expression to evaluate. Every evaluation cycle
371+
// this expression is evaluated at the current time, and all resultant
372+
// time series become pending/firing alerts. This field must not be empty.
373+
string query = 1 [(google.api.field_behavior) = REQUIRED];
374+
375+
// Optional. Alerts are considered firing once their PromQL expression was
376+
// evaluated to be "true" for this long.
377+
// Alerts whose PromQL expression was not evaluated to be "true" for
378+
// long enough are considered pending.
379+
// Must be a non-negative duration or missing.
380+
// This field is optional. Its default value is zero.
381+
google.protobuf.Duration duration = 2
382+
[(google.api.field_behavior) = OPTIONAL];
383+
384+
// Optional. How often this rule should be evaluated.
385+
// Must be a positive multiple of 30 seconds or missing.
386+
// This field is optional. Its default value is 30 seconds.
387+
// If this PrometheusQueryLanguageCondition was generated from a
388+
// Prometheus alerting rule, then this value should be taken from the
389+
// enclosing rule group.
390+
google.protobuf.Duration evaluation_interval = 3
391+
[(google.api.field_behavior) = OPTIONAL];
392+
393+
// Optional. Labels to add to or overwrite in the PromQL query result.
394+
// Label names [must be
395+
// valid](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels).
396+
// Label values can be [templatized by using
397+
// variables](https://cloud.google.com/monitoring/alerts/doc-variables).
398+
// The only available variable names are the names of the labels in the
399+
// PromQL result, including "__name__" and "value". "labels" may be empty.
400+
map<string, string> labels = 4 [(google.api.field_behavior) = OPTIONAL];
401+
402+
// Optional. The rule group name of this alert in the corresponding
403+
// Prometheus configuration file.
404+
//
405+
// Some external tools may require this field to be populated correctly
406+
// in order to refer to the original Prometheus configuration file.
407+
// The rule group name and the alert name are necessary to update the
408+
// relevant AlertPolicies in case the definition of the rule group changes
409+
// in the future.
410+
//
411+
// This field is optional. If this field is not empty, then it must
412+
// contain a valid UTF-8 string.
413+
// This field may not exceed 2048 Unicode characters in length.
414+
string rule_group = 5 [(google.api.field_behavior) = OPTIONAL];
415+
416+
// Optional. The alerting rule name of this alert in the corresponding
417+
// Prometheus configuration file.
418+
//
419+
// Some external tools may require this field to be populated correctly
420+
// in order to refer to the original Prometheus configuration file.
421+
// The rule group name and the alert name are necessary to update the
422+
// relevant AlertPolicies in case the definition of the rule group changes
423+
// in the future.
424+
//
425+
// This field is optional. If this field is not empty, then it must be a
426+
// [valid Prometheus label
427+
// name](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels).
428+
// This field may not exceed 2048 Unicode characters in length.
429+
string alert_rule = 6 [(google.api.field_behavior) = OPTIONAL];
430+
}
431+
301432
// Required if the condition exists. The unique resource name for this
302433
// condition. Its format is:
303434
//
@@ -346,6 +477,9 @@ message AlertPolicy {
346477
// A condition that uses the Monitoring Query Language to define
347478
// alerts.
348479
MonitoringQueryLanguageCondition condition_monitoring_query_language = 19;
480+
481+
// A condition that uses the Prometheus query language to define alerts.
482+
PrometheusQueryLanguageCondition condition_prometheus_query_language = 21;
349483
}
350484
}
351485

@@ -380,6 +514,23 @@ message AlertPolicy {
380514
google.protobuf.Duration period = 1;
381515
}
382516

517+
// Control over how the notification channels in `notification_channels`
518+
// are notified when this alert fires, on a per-channel basis.
519+
message NotificationChannelStrategy {
520+
// The full REST resource name for the notification channels that these
521+
// settings apply to. Each of these correspond to the name field in one
522+
// of the NotificationChannel objects referenced in the
523+
// notification_channels field of this AlertPolicy.
524+
// The format is:
525+
//
526+
// projects/[PROJECT_ID_OR_NUMBER]/notificationChannels/[CHANNEL_ID]
527+
repeated string notification_channel_names = 1;
528+
529+
// The frequency at which to send reminder notifications for open
530+
// incidents.
531+
google.protobuf.Duration renotify_interval = 2;
532+
}
533+
383534
// Required for alert policies with a `LogMatch` condition.
384535
//
385536
// This limit is not implemented for alert policies that are not log-based.
@@ -388,6 +539,9 @@ message AlertPolicy {
388539
// If an alert policy that was active has no data for this long, any open
389540
// incidents will close
390541
google.protobuf.Duration auto_close = 3;
542+
543+
// Control how notifications will be sent out, on a per-channel basis.
544+
repeated NotificationChannelStrategy notification_channel_strategy = 4;
391545
}
392546

393547
// Required if the policy exists. The resource name for this policy. The
@@ -406,6 +560,12 @@ message AlertPolicy {
406560
// notifications, and incidents. To avoid confusion, don't use the same
407561
// display name for multiple policies in the same project. The name is
408562
// limited to 512 Unicode characters.
563+
//
564+
// The convention for the display_name of a PrometheusQueryLanguageCondition
565+
// is "{rule group name}/{alert name}", where the {rule group name} and
566+
// {alert name} should be taken from the corresponding Prometheus
567+
// configuration file. This convention is not enforced.
568+
// In any case the display_name is not a unique key of the AlertPolicy.
409569
string display_name = 2;
410570

411571
// Documentation that is included with notifications and incidents related to
@@ -422,6 +582,13 @@ message AlertPolicy {
422582
// 63 Unicode characters or 128 bytes, whichever is smaller. Labels and
423583
// values can contain only lowercase letters, numerals, underscores, and
424584
// dashes. Keys must begin with a letter.
585+
//
586+
// Note that Prometheus {alert name} is a
587+
// [valid Prometheus label
588+
// names](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels),
589+
// whereas Prometheus {rule group} is an unrestricted UTF-8 string.
590+
// This means that they cannot be stored as-is in user labels, because
591+
// they may contain characters that are not allowed in user-label values.
425592
map<string, string> user_labels = 16;
426593

427594
// A list of conditions for the policy. The conditions are combined by AND or
@@ -430,6 +597,8 @@ message AlertPolicy {
430597
// conditions.
431598
// If `condition_time_series_query_language` is present, it must be the only
432599
// `condition`.
600+
// If `condition_monitoring_query_language` is present, it must be the only
601+
// `condition`.
433602
repeated Condition conditions = 12;
434603

435604
// How to combine the results of multiple conditions to determine if an
@@ -445,8 +614,9 @@ message AlertPolicy {
445614
// a field projection has been specified that strips it out.
446615
google.protobuf.BoolValue enabled = 17;
447616

448-
// Read-only description of how the alert policy is invalid. OK if the alert
449-
// policy is valid. If not OK, the alert policy will not generate incidents.
617+
// Read-only description of how the alert policy is invalid. This field is
618+
// only set when the alert policy is invalid. An invalid alert policy will not
619+
// generate incidents.
450620
google.rpc.Status validity = 18;
451621

452622
// Identifies the notification channels to which notifications should be sent

‎google/monitoring/v3/alert_service.proto‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2023 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -49,7 +49,8 @@ service AlertPolicyService {
4949
"https://www.googleapis.com/auth/monitoring.read";
5050

5151
// Lists the existing alerting policies for the workspace.
52-
rpc ListAlertPolicies(ListAlertPoliciesRequest) returns (ListAlertPoliciesResponse) {
52+
rpc ListAlertPolicies(ListAlertPoliciesRequest)
53+
returns (ListAlertPoliciesResponse) {
5354
option (google.api.http) = {
5455
get: "/v3/{name=projects/*}/alertPolicies"
5556
};
@@ -65,6 +66,10 @@ service AlertPolicyService {
6566
}
6667

6768
// Creates a new alerting policy.
69+
//
70+
// Design your application to single-thread API calls that modify the state of
71+
// alerting policies in a single project. This includes calls to
72+
// CreateAlertPolicy, DeleteAlertPolicy and UpdateAlertPolicy.
6873
rpc CreateAlertPolicy(CreateAlertPolicyRequest) returns (AlertPolicy) {
6974
option (google.api.http) = {
7075
post: "/v3/{name=projects/*}/alertPolicies"
@@ -74,7 +79,12 @@ service AlertPolicyService {
7479
}
7580

7681
// Deletes an alerting policy.
77-
rpc DeleteAlertPolicy(DeleteAlertPolicyRequest) returns (google.protobuf.Empty) {
82+
//
83+
// Design your application to single-thread API calls that modify the state of
84+
// alerting policies in a single project. This includes calls to
85+
// CreateAlertPolicy, DeleteAlertPolicy and UpdateAlertPolicy.
86+
rpc DeleteAlertPolicy(DeleteAlertPolicyRequest)
87+
returns (google.protobuf.Empty) {
7888
option (google.api.http) = {
7989
delete: "/v3/{name=projects/*/alertPolicies/*}"
8090
};
@@ -85,6 +95,10 @@ service AlertPolicyService {
8595
// a new one or replace only certain fields in the current alerting policy by
8696
// specifying the fields to be updated via `updateMask`. Returns the
8797
// updated alerting policy.
98+
//
99+
// Design your application to single-thread API calls that modify the state of
100+
// alerting policies in a single project. This includes calls to
101+
// CreateAlertPolicy, DeleteAlertPolicy and UpdateAlertPolicy.
88102
rpc UpdateAlertPolicy(UpdateAlertPolicyRequest) returns (AlertPolicy) {
89103
option (google.api.http) = {
90104
patch: "/v3/{alert_policy.name=projects/*/alertPolicies/*}"
@@ -96,8 +110,9 @@ service AlertPolicyService {
96110

97111
// The protocol for the `CreateAlertPolicy` request.
98112
message CreateAlertPolicyRequest {
99-
// Required. The [project](https://cloud.google.com/monitoring/api/v3#project_name) in
100-
// which to create the alerting policy. The format is:
113+
// Required. The
114+
// [project](https://cloud.google.com/monitoring/api/v3#project_name) in which
115+
// to create the alerting policy. The format is:
101116
//
102117
// projects/[PROJECT_ID_OR_NUMBER]
103118
//
@@ -115,9 +130,9 @@ message CreateAlertPolicyRequest {
115130
}
116131
];
117132

118-
// Required. The requested alerting policy. You should omit the `name` field in this
119-
// policy. The name will be returned in the new policy, including
120-
// a new `[ALERT_POLICY_ID]` value.
133+
// Required. The requested alerting policy. You should omit the `name` field
134+
// in this policy. The name will be returned in the new policy, including a
135+
// new `[ALERT_POLICY_ID]` value.
121136
AlertPolicy alert_policy = 2 [(google.api.field_behavior) = REQUIRED];
122137
}
123138

@@ -136,8 +151,9 @@ message GetAlertPolicyRequest {
136151

137152
// The protocol for the `ListAlertPolicies` request.
138153
message ListAlertPoliciesRequest {
139-
// Required. The [project](https://cloud.google.com/monitoring/api/v3#project_name)
140-
// whose alert policies are to be listed. The format is:
154+
// Required. The
155+
// [project](https://cloud.google.com/monitoring/api/v3#project_name) whose
156+
// alert policies are to be listed. The format is:
141157
//
142158
// projects/[PROJECT_ID_OR_NUMBER]
143159
//

0 commit comments

Comments
 (0)