diff --git a/google/monitoring/monitoring.yaml b/google/monitoring/monitoring.yaml index 443d6da7..b4bf2162 100644 --- a/google/monitoring/monitoring.yaml +++ b/google/monitoring/monitoring.yaml @@ -1,11 +1,13 @@ type: google.api.Service -config_version: 2 +config_version: 3 name: monitoring.googleapis.com title: Stackdriver Monitoring API apis: +- name: google.monitoring.v3.AlertPolicyService - name: google.monitoring.v3.GroupService - name: google.monitoring.v3.MetricService +- name: google.monitoring.v3.NotificationChannelService - name: google.monitoring.v3.UptimeCheckService documentation: @@ -16,6 +18,14 @@ documentation: backend: rules: + - selector: google.monitoring.v3.AlertPolicyService.GetAlertPolicy + deadline: 30.0 + - selector: google.monitoring.v3.AlertPolicyService.CreateAlertPolicy + deadline: 30.0 + - selector: google.monitoring.v3.AlertPolicyService.DeleteAlertPolicy + deadline: 30.0 + - selector: google.monitoring.v3.AlertPolicyService.UpdateAlertPolicy + deadline: 30.0 - selector: google.monitoring.v3.GroupService.ListGroups deadline: 30.0 - selector: google.monitoring.v3.GroupService.GetGroup @@ -44,55 +54,64 @@ backend: deadline: 30.0 - selector: google.monitoring.v3.MetricService.CreateTimeSeries deadline: 12.0 + - selector: google.monitoring.v3.NotificationChannelService.ListNotificationChannelDescriptors + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.ListNotificationChannels + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.GetNotificationChannel + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.CreateNotificationChannel + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.UpdateNotificationChannel + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.DeleteNotificationChannel + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.SendNotificationChannelVerificationCode + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.GetNotificationChannelVerificationCode + deadline: 30.0 + - selector: google.monitoring.v3.NotificationChannelService.VerifyNotificationChannel + deadline: 30.0 authentication: rules: - # Query functions that are also required by publish-only users. + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/monitoring - selector: |- - google.monitoring.v3.MetricService.ListMonitoredResourceDescriptors, + google.monitoring.v3.MetricService.GetMetricDescriptor, google.monitoring.v3.MetricService.GetMonitoredResourceDescriptor, google.monitoring.v3.MetricService.ListMetricDescriptors, - google.monitoring.v3.MetricService.GetMetricDescriptor + google.monitoring.v3.MetricService.ListMonitoredResourceDescriptors oauth: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/monitoring, https://www.googleapis.com/auth/monitoring.read, https://www.googleapis.com/auth/monitoring.write - - # Write operations that are allowed for publish-only users. - selector: |- - google.monitoring.v3.MetricService.CreateMetricDescriptor, - google.monitoring.v3.MetricService.CreateTimeSeries - oauth: - canonical_scopes: |- - https://www.googleapis.com/auth/cloud-platform, - https://www.googleapis.com/auth/monitoring, - https://www.googleapis.com/auth/monitoring.write - - # Query operations that are *not* permitted by publish-only users. - - selector: |- - google.monitoring.v3.GroupService.ListGroups, - google.monitoring.v3.GroupService.GetGroup, - google.monitoring.v3.GroupService.ListGroupMembers, - google.monitoring.v3.MetricService.ListTimeSeries + google.monitoring.v3.NotificationChannelService.GetNotificationChannel, + google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor, + google.monitoring.v3.NotificationChannelService.ListNotificationChannelDescriptors, + google.monitoring.v3.NotificationChannelService.ListNotificationChannels oauth: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/monitoring, https://www.googleapis.com/auth/monitoring.read - - # Operations that require full access. - selector: |- - google.monitoring.v3.GroupService.CreateGroup, - google.monitoring.v3.GroupService.UpdateGroup, - google.monitoring.v3.GroupService.DeleteGroup, - google.monitoring.v3.MetricService.DeleteMetricDescriptor + google.monitoring.v3.GroupService.GetGroup, + google.monitoring.v3.GroupService.ListGroupMembers, + google.monitoring.v3.GroupService.ListGroups oauth: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform, - https://www.googleapis.com/auth/monitoring - + https://www.googleapis.com/auth/monitoring, + https://www.googleapis.com/auth/monitoring.read - selector: |- google.monitoring.v3.UptimeCheckService.GetUptimeCheckConfig, google.monitoring.v3.UptimeCheckService.ListUptimeCheckConfigs, @@ -102,3 +121,25 @@ authentication: https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/monitoring, https://www.googleapis.com/auth/monitoring.read + - selector: |- + google.monitoring.v3.AlertPolicyService.GetAlertPolicy, + google.monitoring.v3.AlertPolicyService.ListAlertPolicies + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/monitoring, + https://www.googleapis.com/auth/monitoring.read + - selector: |- + google.monitoring.v3.MetricService.CreateMetricDescriptor, + google.monitoring.v3.MetricService.CreateTimeSeries + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/monitoring, + https://www.googleapis.com/auth/monitoring.write + - selector: google.monitoring.v3.MetricService.ListTimeSeries + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/monitoring, + https://www.googleapis.com/auth/monitoring.read diff --git a/google/monitoring/v3/alert.proto b/google/monitoring/v3/alert.proto new file mode 100644 index 00000000..18d87174 --- /dev/null +++ b/google/monitoring/v3/alert.proto @@ -0,0 +1,344 @@ +// Copyright 2018 Google Inc. +// +// 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. + +syntax = "proto3"; + +package google.monitoring.v3; + +import "google/api/annotations.proto"; +import "google/monitoring/v3/common.proto"; +import "google/monitoring/v3/mutation_record.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; + +option csharp_namespace = "Google.Cloud.Monitoring.V3"; +option go_package = "google.golang.org/genproto/googleapis/monitoring/v3;monitoring"; +option java_multiple_files = true; +option java_outer_classname = "AlertProto"; +option java_package = "com.google.monitoring.v3"; +option php_namespace = "Google\\Cloud\\Monitoring\\V3"; + + +// A description of the conditions under which some aspect of your system is +// considered to be "unhealthy" and the ways to notify people or services about +// this state. For an overview of alert policies, see +// [Introduction to Alerting](/monitoring/alerts/). +message AlertPolicy { + // A content string and a MIME type that describes the content string's + // format. + message Documentation { + // The text of the documentation, interpreted according to `mime_type`. + // The content may not exceed 8,192 Unicode characters and may not exceed + // more than 10,240 bytes when encoded in UTF-8 format, whichever is + // smaller. + string content = 1; + + // The format of the `content` field. Presently, only the value + // `"text/markdown"` is supported. See + // [Markdown](https://en.wikipedia.org/wiki/Markdown) for more information. + string mime_type = 2; + } + + // A condition is a true/false test that determines when an alerting policy + // should open an incident. If a condition evaluates to true, it signifies + // that something is wrong. + message Condition { + // Specifies how many time series must fail a predicate to trigger a + // condition. If not specified, then a `{count: 1}` trigger is used. + message Trigger { + // A type of trigger. + oneof type { + // The absolute number of time series that must fail + // the predicate for the condition to be triggered. + int32 count = 1; + + // The percentage of time series that must fail the + // predicate for the condition to be triggered. + double percent = 2; + } + } + + // A condition type that compares a collection of time series + // against a threshold. + message MetricThreshold { + // A [filter](/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 + // [`MetricService.ListTimeSeries` + // request](/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; + + // Specifies the alignment of data points in individual time series as + // well as how to combine the retrieved time series together (such as + // when aggregating multiple streams on each resource to a single + // stream for each resource or when aggregating streams across all + // members of a group of resrouces). Multiple aggregations + // are applied in the order specified. + // + // This field is similar to the one in the + // [`MetricService.ListTimeSeries` request](/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list). + // It is advisable to use the `ListTimeSeries` method when debugging this field. + repeated Aggregation aggregations = 8; + + // A [filter](/monitoring/api/v3/filters) that identifies a time + // series that should be used as the denominator of a ratio that will be + // compared with the threshold. If a `denominator_filter` is specified, + // the time series specified by the `filter` field will be used as the + // numerator. + // + // The filter is similar to the one that is specified in the + // [`MetricService.ListTimeSeries` + // request](/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 denominator_filter = 9; + + // Specifies the alignment of data points in individual time series + // selected by `denominatorFilter` as + // well as how to combine the retrieved time series together (such as + // when aggregating multiple streams on each resource to a single + // stream for each resource or when aggregating streams across all + // members of a group of resources). + // + // When computing ratios, the `aggregations` and + // `denominator_aggregations` fields must use the same alignment period + // and produce time series that have the same periodicity and labels. + // + // This field is similar to the one in the + // [`MetricService.ListTimeSeries` + // request](/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list). It + // is advisable to use the `ListTimeSeries` method when debugging this + // field. + repeated Aggregation denominator_aggregations = 10; + + // The comparison to apply between the time series (indicated by `filter` + // and `aggregation`) and the threshold (indicated by `threshold_value`). + // The comparison is applied on each time series, with the time series + // on the left-hand side and the threshold on the right-hand side. + // + // Only `COMPARISON_LT` and `COMPARISON_GT` are supported currently. + ComparisonType comparison = 4; + + // A value against which to compare the time series. + double threshold_value = 5; + + // 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. 60, 120, or 300 + // seconds--are supported. If an invalid value is given, an + // error will be returned. The `Duration.nanos` field is + // ignored. 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 `aggregation` 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 = 6; + + // 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 = 7; + } + + // A condition type that checks that monitored resources + // are reporting data. The configuration defines a metric and + // a set of monitored resources. The predicate is considered in violation + // 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](/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 + // [`MetricService.ListTimeSeries` + // request](/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; + + // Specifies the alignment of data points in individual time series as + // well as how to combine the retrieved time series together (such as + // when aggregating multiple streams on each resource to a single + // stream for each resource or when aggregating streams across all + // members of a group of resrouces). Multiple aggregations + // are applied in the order specified. + // + // This field is similar to the + // one in the [`MetricService.ListTimeSeries` request](/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list). + // It is advisable to use the `ListTimeSeries` method when debugging this field. + 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 + // error will be returned. The `Duration.nanos` field is + // ignored. + 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`. + Trigger trigger = 3; + } + + // Required if the condition exists. The unique resource name for this + // condition. Its syntax is: + // + // projects/[PROJECT_ID]/alertPolicies/[POLICY_ID]/conditions/[CONDITION_ID] + // + // `[CONDITION_ID]` is assigned by Stackdriver Monitoring when the + // condition is created as part of a new or updated alerting policy. + // + // When calling the + // [alertPolicies.create][google.monitoring.v3.AlertPolicyService.CreateAlertPolicy] + // method, do not include the `name` field in the conditions of the + // requested alerting policy. Stackdriver Monitoring creates the + // condition identifiers and includes them in the new policy. + // + // When calling the + // [alertPolicies.update][google.monitoring.v3.AlertPolicyService.UpdateAlertPolicy] + // method to update a policy, including a condition `name` causes the + // existing condition to be updated. Conditions without names are added to + // the updated policy. Existing conditions are deleted if they are not + // updated. + // + // Best practice is to preserve `[CONDITION_ID]` if you make only small + // changes, such as those to condition thresholds, durations, or trigger + // values. Otherwise, treat the change as a new condition and let the + // existing condition be deleted. + string name = 12; + + // A short name or phrase used to identify the condition in dashboards, + // notifications, and incidents. To avoid confusion, don't use the same + // display name for multiple conditions in the same policy. + string display_name = 6; + + // Only one of the following condition types will be specified. + oneof condition { + // A condition that compares a time series against a threshold. + MetricThreshold condition_threshold = 1; + + // A condition that checks that a time series continues to + // receive new data points. + MetricAbsence condition_absent = 2; + } + } + + // Operators for combining conditions. + enum ConditionCombinerType { + // An unspecified combiner. + COMBINE_UNSPECIFIED = 0; + + // Combine conditions using the logical `AND` operator. An + // incident is created only if all conditions are met + // simultaneously. This combiner is satisfied if all conditions are + // met, even if they are met on completely different resources. + AND = 1; + + // Combine conditions using the logical `OR` operator. An incident + // is created if any of the listed conditions is met. + OR = 2; + + // Combine conditions using logical `AND` operator, but unlike the regular + // `AND` option, an incident is created only if all conditions are met + // simultaneously on at least one resource. + AND_WITH_MATCHING_RESOURCE = 3; + } + + // Required if the policy exists. The resource name for this policy. The + // syntax is: + // + // projects/[PROJECT_ID]/alertPolicies/[ALERT_POLICY_ID] + // + // `[ALERT_POLICY_ID]` is assigned by Stackdriver Monitoring when the policy + // is created. When calling the + // [alertPolicies.create][google.monitoring.v3.AlertPolicyService.CreateAlertPolicy] + // method, do not include the `name` field in the alerting policy passed as + // part of the request. + string name = 1; + + // A short name or phrase used to identify the policy in dashboards, + // notifications, and incidents. To avoid confusion, don't use the same + // display name for multiple policies in the same project. The name is + // limited to 512 Unicode characters. + string display_name = 2; + + // Documentation that is included with notifications and incidents related to + // this policy. Best practice is for the documentation to include information + // to help responders understand, mitigate, escalate, and correct the + // underlying problems detected by the alerting policy. Notification channels + // that have limited capacity might not show this documentation. + Documentation documentation = 13; + + // User-supplied key/value data to be used for organizing and + // identifying the `AlertPolicy` objects. + // + // The field can contain up to 64 entries. Each key and value is limited to + // 63 Unicode characters or 128 bytes, whichever is smaller. Labels and + // values can contain only lowercase letters, numerals, underscores, and + // dashes. Keys must begin with a letter. + map user_labels = 16; + + // A list of conditions for the policy. The conditions are combined by AND or + // OR according to the `combiner` field. If the combined conditions evaluate + // to true, then an incident is created. A policy can have from one to six + // conditions. + repeated Condition conditions = 12; + + // How to combine the results of multiple conditions + // to determine if an incident should be opened. + ConditionCombinerType combiner = 6; + + // Whether or not the policy is enabled. On write, the default interpretation + // if unset is that the policy is enabled. On read, clients should not make + // any assumption about the state if it has not been populated. The + // field should always be populated on List and Get operations, unless + // a field projection has been specified that strips it out. + google.protobuf.BoolValue enabled = 17; + + // Identifies the notification channels to which notifications should be sent + // when incidents are opened or closed or when new violations occur on + // an already opened incident. Each element of this array corresponds to + // the `name` field in each of the + // [`NotificationChannel`][google.monitoring.v3.NotificationChannel] + // objects that are returned from the [`ListNotificationChannels`] + // [google.monitoring.v3.NotificationChannelService.ListNotificationChannels] + // method. The syntax of the entries in this field is: + // + // projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID] + repeated string notification_channels = 14; + + // A read-only record of the creation of the alerting policy. If provided + // in a call to create or update, this field will be ignored. + MutationRecord creation_record = 10; + + // A read-only record of the most recent change to the alerting policy. If + // provided in a call to create or update, this field will be ignored. + MutationRecord mutation_record = 11; +} diff --git a/google/monitoring/v3/alert_service.proto b/google/monitoring/v3/alert_service.proto new file mode 100644 index 00000000..ca2839f9 --- /dev/null +++ b/google/monitoring/v3/alert_service.proto @@ -0,0 +1,197 @@ +// Copyright 2018 Google Inc. +// +// 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. + +syntax = "proto3"; + +package google.monitoring.v3; + +import "google/api/annotations.proto"; +import "google/monitoring/v3/alert.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option csharp_namespace = "Google.Cloud.Monitoring.V3"; +option go_package = "google.golang.org/genproto/googleapis/monitoring/v3;monitoring"; +option java_multiple_files = true; +option java_outer_classname = "AlertServiceProto"; +option java_package = "com.google.monitoring.v3"; +option php_namespace = "Google\\Cloud\\Monitoring\\V3"; + + +// The AlertPolicyService API is used to manage (list, create, delete, +// edit) alert policies in Stackdriver Monitoring. An alerting policy is +// a description of the conditions under which some aspect of your +// system is considered to be "unhealthy" and the ways to notify +// people or services about this state. In addition to using this API, alert +// policies can also be managed through +// [Stackdriver Monitoring](https://cloud.google.com/monitoring/docs/), +// which can be reached by clicking the "Monitoring" tab in +// [Cloud Console](https://console.cloud.google.com/). +service AlertPolicyService { + // Lists the existing alerting policies for the project. + rpc ListAlertPolicies(ListAlertPoliciesRequest) returns (ListAlertPoliciesResponse) { + option (google.api.http) = { + get: "/v3/{name=projects/*}/alertPolicies" + }; + } + + // Gets a single alerting policy. + rpc GetAlertPolicy(GetAlertPolicyRequest) returns (AlertPolicy) { + option (google.api.http) = { + get: "/v3/{name=projects/*/alertPolicies/*}" + }; + } + + // Creates a new alerting policy. + rpc CreateAlertPolicy(CreateAlertPolicyRequest) returns (AlertPolicy) { + option (google.api.http) = { + post: "/v3/{name=projects/*}/alertPolicies" + body: "alert_policy" + }; + } + + // Deletes an alerting policy. + rpc DeleteAlertPolicy(DeleteAlertPolicyRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v3/{name=projects/*/alertPolicies/*}" + }; + } + + // Updates an alerting policy. You can either replace the entire policy with + // a new one or replace only certain fields in the current alerting policy by + // specifying the fields to be updated via `updateMask`. Returns the + // updated alerting policy. + rpc UpdateAlertPolicy(UpdateAlertPolicyRequest) returns (AlertPolicy) { + option (google.api.http) = { + patch: "/v3/{alert_policy.name=projects/*/alertPolicies/*}" + body: "alert_policy" + }; + } +} + +// The protocol for the `CreateAlertPolicy` request. +message CreateAlertPolicyRequest { + // The project in which to create the alerting policy. The format is + // `projects/[PROJECT_ID]`. + // + // 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/[POLICY_ID]`, identifying the policy in the container. + string name = 3; + + // The requested alerting policy. You should omit the `name` field in this + // policy. The name will be returned in the new policy, including + // a new [ALERT_POLICY_ID] value. + AlertPolicy alert_policy = 2; +} + +// The protocol for the `GetAlertPolicy` request. +message GetAlertPolicyRequest { + // The alerting policy to retrieve. The format is + // + // projects/[PROJECT_ID]/alertPolicies/[ALERT_POLICY_ID] + string name = 3; +} + +// The protocol for the `ListAlertPolicies` request. +message ListAlertPoliciesRequest { + // The project whose alert policies are to be listed. The format is + // + // projects/[PROJECT_ID] + // + // Note that this field names the parent container in which the alerting + // policies to be listed are stored. To retrieve a single alerting policy + // by name, use the + // [GetAlertPolicy][google.monitoring.v3.AlertPolicyService.GetAlertPolicy] + // operation, instead. + string name = 4; + + // If provided, this field specifies the criteria that must be met by + // alert policies to be included in the response. + // + // For more details, see [sorting and + // filtering](/monitoring/api/v3/sorting-and-filtering). + string filter = 5; + + // A comma-separated list of fields by which to sort the result. Supports + // the same set of field references as the `filter` field. Entries can be + // prefixed with a minus sign to sort by the field in descending order. + // + // For more details, see [sorting and + // filtering](/monitoring/api/v3/sorting-and-filtering). + string order_by = 6; + + // The maximum number of results to return in a single response. + int32 page_size = 2; + + // If this field is not empty then it must contain the `nextPageToken` value + // returned by a previous call to this method. Using this field causes the + // method to return more results from the previous method call. + string page_token = 3; +} + +// The protocol for the `ListAlertPolicies` response. +message ListAlertPoliciesResponse { + // The returned alert policies. + repeated AlertPolicy alert_policies = 3; + + // If there might be more results than were returned, then this field is set + // to a non-empty value. To see the additional results, + // use that value as `pageToken` in the next call to this method. + string next_page_token = 2; +} + +// The protocol for the `UpdateAlertPolicy` request. +message UpdateAlertPolicyRequest { + // Optional. A list of alerting policy field names. If this field is not + // empty, each listed field in the existing alerting policy is set to the + // value of the corresponding field in the supplied policy (`alert_policy`), + // or to the field's default value if the field is not in the supplied + // alerting policy. Fields not listed retain their previous value. + // + // Examples of valid field masks include `display_name`, `documentation`, + // `documentation.content`, `documentation.mime_type`, `user_labels`, + // `user_label.nameofkey`, `enabled`, `conditions`, `combiner`, etc. + // + // If this field is empty, then the supplied alerting policy replaces the + // existing policy. It is the same as deleting the existing policy and + // adding the supplied policy, except for the following: + // + // + The new policy will have the same `[ALERT_POLICY_ID]` as the former + // policy. This gives you continuity with the former policy in your + // notifications and incidents. + // + Conditions in the new policy will keep their former `[CONDITION_ID]` if + // the supplied condition includes the `name` field with that + // `[CONDITION_ID]`. If the supplied condition omits the `name` field, + // then a new `[CONDITION_ID]` is created. + google.protobuf.FieldMask update_mask = 2; + + // Required. The updated alerting policy or the updated values for the + // fields listed in `update_mask`. + // If `update_mask` is not empty, any fields in this policy that are + // not in `update_mask` are ignored. + AlertPolicy alert_policy = 3; +} + +// The protocol for the `DeleteAlertPolicy` request. +message DeleteAlertPolicyRequest { + // The alerting policy to delete. The format is: + // + // projects/[PROJECT_ID]/alertPolicies/[ALERT_POLICY_ID] + // + // For more information, see [AlertPolicy][google.monitoring.v3.AlertPolicy]. + string name = 3; +} diff --git a/google/monitoring/v3/common.proto b/google/monitoring/v3/common.proto index 1d6c9dd1..84d8423f 100644 --- a/google/monitoring/v3/common.proto +++ b/google/monitoring/v3/common.proto @@ -1,4 +1,4 @@ -// Copyright 2016 Google Inc. +// Copyright 2018 Google Inc. // // 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/annotations.proto"; import "google/api/distribution.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; @@ -66,8 +67,9 @@ message TimeInterval { // Describes how to combine multiple time series to provide different views of // the data. Aggregation consists of an alignment step on individual time -// series (`per_series_aligner`) followed by an optional reduction of the data -// across different time series (`cross_series_reducer`). For more details, see +// series (`alignment_period` and `per_series_aligner`) followed by an optional +// reduction step of the data across the aligned time series +// (`cross_series_reducer` and `group_by_fields`). For more details, see // [Aggregation](/monitoring/api/learn_more#aggregation). message Aggregation { // The Aligner describes how to bring the data points in a single @@ -83,12 +85,23 @@ message Aggregation { // delta metric to a delta metric requires that the alignment // period be increased. The value type of the result is the same // as the value type of the input. + // + // One can think of this aligner as a rate but without time units; that + // is, the output is conceptually (second_point - first_point). ALIGN_DELTA = 1; // Align and convert to a rate. This alignment is valid for // cumulative metrics and delta metrics with numeric values. The output is a // gauge metric with value type // [DOUBLE][google.api.MetricDescriptor.ValueType.DOUBLE]. + // + // One can think of this aligner as conceptually providing the slope of + // the line that passes through the value at the start and end of the + // window. In other words, this is conceptually ((y1 - y0)/(t1 - t0)), + // and the output unit is one that has a "/time" dimension. + // + // If, by rate, you are looking for percentage change, see the + // `ALIGN_PERCENT_CHANGE` aligner option. ALIGN_RATE = 2; // Align by interpolating between adjacent points around the @@ -152,6 +165,13 @@ message Aggregation { // [INT64][google.api.MetricDescriptor.ValueType.INT64]. ALIGN_COUNT_TRUE = 16; + // Align time series via aggregation. The resulting data point in + // the alignment period is the count of False-valued data points in the + // period. This alignment is valid for gauge metrics with + // Boolean values. The value type of the output is + // [INT64][google.api.MetricDescriptor.ValueType.INT64]. + ALIGN_COUNT_FALSE = 24; + // Align time series via aggregation. The resulting data point in // the alignment period is the fraction of True-valued data points in the // period. This alignment is valid for gauge metrics with Boolean values. @@ -186,6 +206,23 @@ message Aggregation { // with distribution values. The output is a gauge metric with value type // [DOUBLE][google.api.MetricDescriptor.ValueType.DOUBLE]. ALIGN_PERCENTILE_05 = 21; + + // Align and convert to a percentage change. This alignment is valid for + // gauge and delta metrics with numeric values. This alignment conceptually + // computes the equivalent of "((current - previous)/previous)*100" + // where previous value is determined based on the alignmentPeriod. + // In the event that previous is 0 the calculated value is infinity with the + // exception that if both (current - previous) and previous are 0 the + // calculated value is 0. + // A 10 minute moving mean is computed at each point of the time window + // prior to the above calculation to smooth the metric and prevent false + // positives from very short lived spikes. + // Only applicable for data that is >= 0. Any values < 0 are treated as + // no data. While delta metrics are accepted by this alignment special care + // should be taken that the values for the metric will always be positive. + // The output is a gauge metric with value type + // [DOUBLE][google.api.MetricDescriptor.ValueType.DOUBLE]. + ALIGN_PERCENT_CHANGE = 23; } // A Reducer describes how to aggregate data points from multiple @@ -238,6 +275,12 @@ message Aggregation { // the output is [INT64][google.api.MetricDescriptor.ValueType.INT64]. REDUCE_COUNT_TRUE = 7; + // Reduce by computing the count of False-valued data points across time + // series for each alignment period. This reducer is valid for delta + // and gauge metrics of Boolean value type. The value type of + // the output is [INT64][google.api.MetricDescriptor.ValueType.INT64]. + REDUCE_COUNT_FALSE = 15; + // Reduce by computing the fraction of True-valued data points across time // series for each alignment period. This reducer is valid for delta // and gauge metrics of Boolean value type. The output value is in the @@ -322,3 +365,49 @@ message Aggregation { // defined, this field is ignored. repeated string group_by_fields = 5; } + +// Specifies an ordering relationship on two arguments, here called left and +// right. +enum ComparisonType { + // No ordering relationship is specified. + COMPARISON_UNSPECIFIED = 0; + + // The left argument is greater than the right argument. + COMPARISON_GT = 1; + + // The left argument is greater than or equal to the right argument. + COMPARISON_GE = 2; + + // The left argument is less than the right argument. + COMPARISON_LT = 3; + + // The left argument is less than or equal to the right argument. + COMPARISON_LE = 4; + + // The left argument is equal to the right argument. + COMPARISON_EQ = 5; + + // The left argument is not equal to the right argument. + COMPARISON_NE = 6; +} + +// The tier of service for a Stackdriver account. Please see the +// [service tiers documentation](https://cloud.google.com/monitoring/accounts/tiers) +// for more details. +enum ServiceTier { + // An invalid sentinel value, used to indicate that a tier has not + // been provided explicitly. + SERVICE_TIER_UNSPECIFIED = 0; + + // The Stackdriver Basic tier, a free tier of service that provides basic + // features, a moderate allotment of logs, and access to built-in metrics. + // A number of features are not available in this tier. For more details, + // see [the service tiers documentation](https://cloud.google.com/monitoring/accounts/tiers). + SERVICE_TIER_BASIC = 1; + + // The Stackdriver Premium tier, a higher, more expensive tier of service + // that provides access to all Stackdriver features, lets you use Stackdriver + // with AWS accounts, and has a larger allotments for logs and metrics. For + // more details, see [the service tiers documentation](https://cloud.google.com/monitoring/accounts/tiers). + SERVICE_TIER_PREMIUM = 2; +} diff --git a/google/monitoring/v3/monitoring_gapic.yaml b/google/monitoring/v3/monitoring_gapic.yaml index a7dd33a1..e7ec1617 100644 --- a/google/monitoring/v3/monitoring_gapic.yaml +++ b/google/monitoring/v3/monitoring_gapic.yaml @@ -30,7 +30,113 @@ collections: entity_name: monitored_resource_descriptor - name_pattern: projects/{project}/groups/{group} entity_name: group +- name_pattern: projects/{project}/alertPolicies/{alert_policy} + entity_name: alert_policy +- name_pattern: projects/{project}/alertPolicies/{alert_policy}/conditions/{condition} + entity_name: alert_policy_condition +- name_pattern: projects/{project}/notificationChannels/{notification_channel} + entity_name: notification_channel +- name_pattern: projects/{project}/notificationChannelDescriptors/{channel_descriptor} + entity_name: notification_channel_descriptor interfaces: +- name: google.monitoring.v3.AlertPolicyService + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + methods: + - name: ListAlertPolicies + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: alert_policies + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetAlertPolicy + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: alert_policy + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: CreateAlertPolicy + flattening: + groups: + - parameters: + - name + - alert_policy + required_fields: + - name + - alert_policy + request_object_method: true + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: DeleteAlertPolicy + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: alert_policy + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateAlertPolicy + flattening: + groups: + - parameters: + - update_mask + - alert_policy + required_fields: + - alert_policy + request_object_method: true + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + alert_policy.name: alert_policy + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 - name: google.monitoring.v3.GroupService collections: - name_pattern: projects/{project} @@ -323,6 +429,139 @@ interfaces: name: project resource_name_treatment: STATIC_TYPES timeout_millis: 60000 +- name: google.monitoring.v3.NotificationChannelService + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + methods: + - name: ListNotificationChannelDescriptors + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: channel_descriptors + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetNotificationChannelDescriptor + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: notification_channel_descriptor + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListNotificationChannels + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: notification_channels + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetNotificationChannel + flattening: + groups: + - parameters: + - name + required_fields: + - name + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: notification_channel + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: CreateNotificationChannel + flattening: + groups: + - parameters: + - name + - notification_channel + required_fields: + - name + - notification_channel + request_object_method: true + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateNotificationChannel + flattening: + groups: + - parameters: + - update_mask + - notification_channel + required_fields: + - notification_channel + request_object_method: true + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + notification_channel.name: notification_channel + timeout_millis: 60000 + - name: DeleteNotificationChannel + flattening: + groups: + - parameters: + - name + - force + required_fields: + - name + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: notification_channel + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 - name: google.monitoring.v3.UptimeCheckService collections: - name_pattern: projects/{project} @@ -479,3 +718,42 @@ resource_name_generation: - message_name: CreateTimeSeriesRequest field_entity_map: name: project +- message_name: ListAlertPoliciesRequest + field_entity_map: + name: project +- message_name: GetAlertPolicyRequest + field_entity_map: + name: alert_policy +- message_name: CreateAlertPolicyRequest + field_entity_map: + name: project +- message_name: DeleteAlertPolicyRequest + field_entity_map: + name: alert_policy +- message_name: GetNotificationChannelDescriptorRequest + field_entity_map: + name: notification_channel_descriptor +- message_name: ListNotificationChannelDescriptorsRequest + field_entity_map: + name: project +- message_name: ListNotificationChannelsRequest + field_entity_map: + name: project +- message_name: GetNotificationChannelRequest + field_entity_map: + name: notification_channel +- message_name: CreateNotificationChannelRequest + field_entity_map: + name: project +- message_name: DeleteNotificationChannelRequest + field_entity_map: + name: notification_channel +- message_name: SendNotificationChannelVerificationCodeRequest + field_entity_map: + name: notification_channel +- message_name: GetNotificationChannelVerificationCodeRequest + field_entity_map: + name: notification_channel +- message_name: VerifyNotificationChannelRequest + field_entity_map: + name: notification_channel diff --git a/google/monitoring/v3/mutation_record.proto b/google/monitoring/v3/mutation_record.proto new file mode 100644 index 00000000..a3ba28a1 --- /dev/null +++ b/google/monitoring/v3/mutation_record.proto @@ -0,0 +1,36 @@ +// Copyright 2018 Google Inc. +// +// 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. + +syntax = "proto3"; + +package google.monitoring.v3; + +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Monitoring.V3"; +option go_package = "google.golang.org/genproto/googleapis/monitoring/v3;monitoring"; +option java_multiple_files = true; +option java_outer_classname = "MutationRecordProto"; +option java_package = "com.google.monitoring.v3"; +option php_namespace = "Google\\Cloud\\Monitoring\\V3"; + + +// Describes a change made to a configuration. +message MutationRecord { + // When the change occurred. + google.protobuf.Timestamp mutate_time = 1; + + // The email address of the user making the change. + string mutated_by = 2; +} diff --git a/google/monitoring/v3/notification.proto b/google/monitoring/v3/notification.proto new file mode 100644 index 00000000..8cbca33f --- /dev/null +++ b/google/monitoring/v3/notification.proto @@ -0,0 +1,163 @@ +// Copyright 2018 Google Inc. +// +// 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. + +syntax = "proto3"; + +package google.monitoring.v3; + +import "google/api/annotations.proto"; +import "google/api/label.proto"; +import "google/monitoring/v3/common.proto"; +import "google/protobuf/wrappers.proto"; + +option csharp_namespace = "Google.Cloud.Monitoring.V3"; +option go_package = "google.golang.org/genproto/googleapis/monitoring/v3;monitoring"; +option java_multiple_files = true; +option java_outer_classname = "NotificationProto"; +option java_package = "com.google.monitoring.v3"; +option php_namespace = "Google\\Cloud\\Monitoring\\V3"; + + +// A description of a notification channel. The descriptor includes +// the properties of the channel and the set of labels or fields that +// must be specified to configure channels of a given type. +message NotificationChannelDescriptor { + // The full REST resource name for this descriptor. The syntax is: + // + // projects/[PROJECT_ID]/notificationChannelDescriptors/[TYPE] + // + // In the above, `[TYPE]` is the value of the `type` field. + string name = 6; + + // The type of notification channel, such as "email", "sms", etc. + // Notification channel types are globally unique. + string type = 1; + + // A human-readable name for the notification channel type. This + // form of the name is suitable for a user interface. + string display_name = 2; + + // A human-readable description of the notification channel + // type. The description may include a description of the properties + // of the channel and pointers to external documentation. + string description = 3; + + // The set of labels that must be defined to identify a particular + // channel of the corresponding type. Each label includes a + // description for how that field should be populated. + repeated google.api.LabelDescriptor labels = 4; + + // The tiers that support this notification channel; the project service tier + // must be one of the supported_tiers. + repeated ServiceTier supported_tiers = 5; +} + +// A `NotificationChannel` is a medium through which an alert is +// delivered when a policy violation is detected. Examples of channels +// include email, SMS, and third-party messaging applications. Fields +// containing sensitive information like authentication tokens or +// contact info are only partially populated on retrieval. +message NotificationChannel { + // Indicates whether the channel has been verified or not. It is illegal + // to specify this field in a + // [`CreateNotificationChannel`][google.monitoring.v3.NotificationChannelService.CreateNotificationChannel] + // or an + // [`UpdateNotificationChannel`][google.monitoring.v3.NotificationChannelService.UpdateNotificationChannel] + // operation. + enum VerificationStatus { + // Sentinel value used to indicate that the state is unknown, omitted, or + // is not applicable (as in the case of channels that neither support + // nor require verification in order to function). + VERIFICATION_STATUS_UNSPECIFIED = 0; + + // The channel has yet to be verified and requires verification to function. + // Note that this state also applies to the case where the verification + // process has been initiated by sending a verification code but where + // the verification code has not been submitted to complete the process. + UNVERIFIED = 1; + + // It has been proven that notifications can be received on this + // notification channel and that someone on the project has access + // to messages that are delivered to that channel. + VERIFIED = 2; + } + + // The type of the notification channel. This field matches the + // value of the [NotificationChannelDescriptor.type][google.monitoring.v3.NotificationChannelDescriptor.type] field. + string type = 1; + + // The full REST resource name for this channel. The syntax is: + // + // projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID] + // + // The `[CHANNEL_ID]` is automatically assigned by the server on creation. + string name = 6; + + // An optional human-readable name for this notification channel. It is + // recommended that you specify a non-empty and unique name in order to + // make it easier to identify the channels in your project, though this is + // not enforced. The display name is limited to 512 Unicode characters. + string display_name = 3; + + // An optional human-readable description of this notification channel. This + // description may provide additional details, beyond the display + // name, for the channel. This may not exceeed 1024 Unicode characters. + string description = 4; + + // Configuration fields that define the channel and its behavior. The + // permissible and required labels are specified in the + // [NotificationChannelDescriptor.labels][google.monitoring.v3.NotificationChannelDescriptor.labels] of the + // `NotificationChannelDescriptor` corresponding to the `type` field. + map labels = 5; + + // User-supplied key/value data that does not need to conform to + // the corresponding `NotificationChannelDescriptor`'s schema, unlike + // the `labels` field. This field is intended to be used for organizing + // and identifying the `NotificationChannel` objects. + // + // The field can contain up to 64 entries. Each key and value is limited to + // 63 Unicode characters or 128 bytes, whichever is smaller. Labels and + // values can contain only lowercase letters, numerals, underscores, and + // dashes. Keys must begin with a letter. + map user_labels = 8; + + // Indicates whether this channel has been verified or not. On a + // [`ListNotificationChannels`][google.monitoring.v3.NotificationChannelService.ListNotificationChannels] + // or + // [`GetNotificationChannel`][google.monitoring.v3.NotificationChannelService.GetNotificationChannel] + // operation, this field is expected to be populated. + // + // If the value is `UNVERIFIED`, then it indicates that the channel is + // non-functioning (it both requires verification and lacks verification); + // otherwise, it is assumed that the channel works. + // + // If the channel is neither `VERIFIED` nor `UNVERIFIED`, it implies that + // the channel is of a type that does not require verification or that + // this specific channel has been exempted from verification because it was + // created prior to verification being required for channels of this type. + // + // This field cannot be modified using a standard + // [`UpdateNotificationChannel`][google.monitoring.v3.NotificationChannelService.UpdateNotificationChannel] + // operation. To change the value of this field, you must call + // [`VerifyNotificationChannel`][google.monitoring.v3.NotificationChannelService.VerifyNotificationChannel]. + VerificationStatus verification_status = 9; + + // Whether notifications are forwarded to the described channel. This makes + // it possible to disable delivery of notifications to a particular channel + // without removing the channel from all alerting policies that reference + // the channel. This is a more convenient approach when the change is + // temporary and you want to receive notifications from the same set + // of alerting policies on the channel at some point in the future. + google.protobuf.BoolValue enabled = 11; +} diff --git a/google/monitoring/v3/notification_service.proto b/google/monitoring/v3/notification_service.proto new file mode 100644 index 00000000..aa5d294b --- /dev/null +++ b/google/monitoring/v3/notification_service.proto @@ -0,0 +1,335 @@ +// Copyright 2018 Google Inc. +// +// 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. + +syntax = "proto3"; + +package google.monitoring.v3; + +import "google/api/annotations.proto"; +import "google/monitoring/v3/notification.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Monitoring.V3"; +option go_package = "google.golang.org/genproto/googleapis/monitoring/v3;monitoring"; +option java_multiple_files = true; +option java_outer_classname = "NotificationServiceProto"; +option java_package = "com.google.monitoring.v3"; +option php_namespace = "Google\\Cloud\\Monitoring\\V3"; + + +// The Notification Channel API provides access to configuration that +// controls how messages related to incidents are sent. +service NotificationChannelService { + // Lists the descriptors for supported channel types. The use of descriptors + // makes it possible for new channel types to be dynamically added. + rpc ListNotificationChannelDescriptors(ListNotificationChannelDescriptorsRequest) returns (ListNotificationChannelDescriptorsResponse) { + option (google.api.http) = { + get: "/v3/{name=projects/*}/notificationChannelDescriptors" + }; + } + + // Gets a single channel descriptor. The descriptor indicates which fields + // are expected / permitted for a notification channel of the given type. + rpc GetNotificationChannelDescriptor(GetNotificationChannelDescriptorRequest) returns (NotificationChannelDescriptor) { + option (google.api.http) = { + get: "/v3/{name=projects/*/notificationChannelDescriptors/*}" + }; + } + + // Lists the notification channels that have been created for the project. + rpc ListNotificationChannels(ListNotificationChannelsRequest) returns (ListNotificationChannelsResponse) { + option (google.api.http) = { + get: "/v3/{name=projects/*}/notificationChannels" + }; + } + + // Gets a single notification channel. The channel includes the relevant + // configuration details with which the channel was created. However, the + // response may truncate or omit passwords, API keys, or other private key + // matter and thus the response may not be 100% identical to the information + // that was supplied in the call to the create method. + rpc GetNotificationChannel(GetNotificationChannelRequest) returns (NotificationChannel) { + option (google.api.http) = { + get: "/v3/{name=projects/*/notificationChannels/*}" + }; + } + + // Creates a new notification channel, representing a single notification + // endpoint such as an email address, SMS number, or pagerduty service. + rpc CreateNotificationChannel(CreateNotificationChannelRequest) returns (NotificationChannel) { + option (google.api.http) = { + post: "/v3/{name=projects/*}/notificationChannels" + body: "notification_channel" + }; + } + + // Updates a notification channel. Fields not specified in the field mask + // remain unchanged. + rpc UpdateNotificationChannel(UpdateNotificationChannelRequest) returns (NotificationChannel) { + option (google.api.http) = { + patch: "/v3/{notification_channel.name=projects/*/notificationChannels/*}" + body: "notification_channel" + }; + } + + // Deletes a notification channel. + rpc DeleteNotificationChannel(DeleteNotificationChannelRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v3/{name=projects/*/notificationChannels/*}" + }; + } + + // Causes a verification code to be delivered to the channel. The code + // can then be supplied in `VerifyNotificationChannel` to verify the channel. + rpc SendNotificationChannelVerificationCode(SendNotificationChannelVerificationCodeRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v3/{name=projects/*/notificationChannels/*}:sendVerificationCode" + body: "*" + }; + } + + // Requests a verification code for an already verified channel that can then + // be used in a call to VerifyNotificationChannel() on a different channel + // with an equivalent identity in the same or in a different project. This + // makes it possible to copy a channel between projects without requiring + // manual reverification of the channel. If the channel is not in the + // verified state, this method will fail (in other words, this may only be + // used if the SendNotificationChannelVerificationCode and + // VerifyNotificationChannel paths have already been used to put the given + // channel into the verified state). + // + // There is no guarantee that the verification codes returned by this method + // will be of a similar structure or form as the ones that are delivered + // to the channel via SendNotificationChannelVerificationCode; while + // VerifyNotificationChannel() will recognize both the codes delivered via + // SendNotificationChannelVerificationCode() and returned from + // GetNotificationChannelVerificationCode(), it is typically the case that + // the verification codes delivered via + // SendNotificationChannelVerificationCode() will be shorter and also + // have a shorter expiration (e.g. codes such as "G-123456") whereas + // GetVerificationCode() will typically return a much longer, websafe base + // 64 encoded string that has a longer expiration time. + rpc GetNotificationChannelVerificationCode(GetNotificationChannelVerificationCodeRequest) returns (GetNotificationChannelVerificationCodeResponse) { + option (google.api.http) = { + post: "/v3/{name=projects/*/notificationChannels/*}:getVerificationCode" + body: "*" + }; + } + + // Verifies a `NotificationChannel` by proving receipt of the code + // delivered to the channel as a result of calling + // `SendNotificationChannelVerificationCode`. + rpc VerifyNotificationChannel(VerifyNotificationChannelRequest) returns (NotificationChannel) { + option (google.api.http) = { + post: "/v3/{name=projects/*/notificationChannels/*}:verify" + body: "*" + }; + } +} + +// The `ListNotificationChannelDescriptors` request. +message ListNotificationChannelDescriptorsRequest { + // The REST resource name of the parent from which to retrieve + // the notification channel descriptors. The expected syntax is: + // + // projects/[PROJECT_ID] + // + // Note that this names the parent container in which to look for the + // descriptors; to retrieve a single descriptor by name, use the + // [GetNotificationChannelDescriptor][google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor] + // operation, instead. + string name = 4; + + // The maximum number of results to return in a single response. If + // not set to a positive number, a reasonable value will be chosen by the + // service. + int32 page_size = 2; + + // If non-empty, `page_token` must contain a value returned as the + // `next_page_token` in a previous response to request the next set + // of results. + string page_token = 3; +} + +// The `ListNotificationChannelDescriptors` response. +message ListNotificationChannelDescriptorsResponse { + // The monitored resource descriptors supported for the specified + // project, optionally filtered. + repeated NotificationChannelDescriptor channel_descriptors = 1; + + // If not empty, indicates that there may be more results that match + // the request. Use the value in the `page_token` field in a + // subsequent request to fetch the next set of results. If empty, + // all results have been returned. + string next_page_token = 2; +} + +// The `GetNotificationChannelDescriptor` response. +message GetNotificationChannelDescriptorRequest { + // The channel type for which to execute the request. The format is + // `projects/[PROJECT_ID]/notificationChannelDescriptors/{channel_type}`. + string name = 3; +} + +// The `CreateNotificationChannel` request. +message CreateNotificationChannelRequest { + // The project on which to execute the request. The format is: + // + // projects/[PROJECT_ID] + // + // Note that this names the container into which the channel will be + // written. This does not name the newly created channel. The resulting + // channel's name will have a normalized version of this field as a prefix, + // but will add `/notificationChannels/[CHANNEL_ID]` to identify the channel. + string name = 3; + + // The definition of the `NotificationChannel` to create. + NotificationChannel notification_channel = 2; +} + +// The `ListNotificationChannels` request. +message ListNotificationChannelsRequest { + // The project on which to execute the request. The format is + // `projects/[PROJECT_ID]`. That is, this names the container + // in which to look for the notification channels; it does not name a + // specific channel. To query a specific channel by REST resource name, use + // the + // [`GetNotificationChannel`][google.monitoring.v3.NotificationChannelService.GetNotificationChannel] operation. + string name = 5; + + // If provided, this field specifies the criteria that must be met by + // notification channels to be included in the response. + // + // For more details, see [sorting and + // filtering](/monitoring/api/v3/sorting-and-filtering). + string filter = 6; + + // A comma-separated list of fields by which to sort the result. Supports + // the same set of fields as in `filter`. Entries can be prefixed with + // a minus sign to sort in descending rather than ascending order. + // + // For more details, see [sorting and + // filtering](/monitoring/api/v3/sorting-and-filtering). + string order_by = 7; + + // The maximum number of results to return in a single response. If + // not set to a positive number, a reasonable value will be chosen by the + // service. + int32 page_size = 3; + + // If non-empty, `page_token` must contain a value returned as the + // `next_page_token` in a previous response to request the next set + // of results. + string page_token = 4; +} + +// The `ListNotificationChannels` response. +message ListNotificationChannelsResponse { + // The notification channels defined for the specified project. + repeated NotificationChannel notification_channels = 3; + + // If not empty, indicates that there may be more results that match + // the request. Use the value in the `page_token` field in a + // subsequent request to fetch the next set of results. If empty, + // all results have been returned. + string next_page_token = 2; +} + +// The `GetNotificationChannel` request. +message GetNotificationChannelRequest { + // The channel for which to execute the request. The format is + // `projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]`. + string name = 3; +} + +// The `UpdateNotificationChannel` request. +message UpdateNotificationChannelRequest { + // The fields to update. + google.protobuf.FieldMask update_mask = 2; + + // A description of the changes to be applied to the specified + // notification channel. The description must provide a definition for + // fields to be updated; the names of these fields should also be + // included in the `update_mask`. + NotificationChannel notification_channel = 3; +} + +// The `DeleteNotificationChannel` request. +message DeleteNotificationChannelRequest { + // The channel for which to execute the request. The format is + // `projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]`. + string name = 3; + + // If true, the notification channel will be deleted regardless of its + // use in alert policies (the policies will be updated to remove the + // channel). If false, channels that are still referenced by an existing + // alerting policy will fail to be deleted in a delete operation. + bool force = 5; +} + +// The `SendNotificationChannelVerificationCode` request. +message SendNotificationChannelVerificationCodeRequest { + // The notification channel to which to send a verification code. + string name = 1; +} + +// The `GetNotificationChannelVerificationCode` request. +message GetNotificationChannelVerificationCodeRequest { + // The notification channel for which a verification code is to be generated + // and retrieved. This must name a channel that is already verified; if + // the specified channel is not verified, the request will fail. + string name = 1; + + // The desired expiration time. If specified, the API will guarantee that + // the returned code will not be valid after the specified timestamp; + // however, the API cannot guarantee that the returned code will be + // valid for at least as long as the requested time (the API puts an upper + // bound on the amount of time for which a code may be valid). If omitted, + // a default expiration will be used, which may be less than the max + // permissible expiration (so specifying an expiration may extend the + // code's lifetime over omitting an expiration, even though the API does + // impose an upper limit on the maximum expiration that is permitted). + google.protobuf.Timestamp expire_time = 2; +} + +// The `GetNotificationChannelVerificationCode` request. +message GetNotificationChannelVerificationCodeResponse { + // The verification code, which may be used to verify other channels + // that have an equivalent identity (i.e. other channels of the same + // type with the same fingerprint such as other email channels with + // the same email address or other sms channels with the same number). + string code = 1; + + // The expiration time associated with the code that was returned. If + // an expiration was provided in the request, this is the minimum of the + // requested expiration in the request and the max permitted expiration. + google.protobuf.Timestamp expire_time = 2; +} + +// The `VerifyNotificationChannel` request. +message VerifyNotificationChannelRequest { + // The notification channel to verify. + string name = 1; + + // The verification code that was delivered to the channel as + // a result of invoking the `SendNotificationChannelVerificationCode` API + // method or that was retrieved from a verified channel via + // `GetNotificationChannelVerificationCode`. For example, one might have + // "G-123456" or "TKNZGhhd2EyN3I1MnRnMjRv" (in general, one is only + // guaranteed that the code is valid UTF-8; one should not + // make any assumptions regarding the structure or format of the code). + string code = 2; +}