alert.proto

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

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";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "google/rpc/status.proto";

option csharp_namespace = "Google.Cloud.Monitoring.V3";
option go_package = "cloud.google.com/go/monitoring/apiv3/v2/monitoringpb;monitoringpb";
option java_multiple_files = true;
option java_outer_classname = "AlertProto";
option java_package = "com.google.monitoring.v3";
option php_namespace = "Google\\Cloud\\Monitoring\\V3";
option ruby_package = "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](https://cloud.google.com/monitoring/alerts/).
message AlertPolicy {
  option (google.api.resource) = {
    type: "monitoring.googleapis.com/AlertPolicy"
    pattern: "projects/{project}/alertPolicies/{alert_policy}"
    pattern: "organizations/{organization}/alertPolicies/{alert_policy}"
    pattern: "folders/{folder}/alertPolicies/{alert_policy}"
    pattern: "*"
  };

  // 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. This text can be [templatized by using
    // variables](https://cloud.google.com/monitoring/alerts/doc-variables).
    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 {
    option (google.api.resource) = {
      type: "monitoring.googleapis.com/AlertPolicyCondition"
      pattern: "projects/{project}/alertPolicies/{alert_policy}/conditions/{condition}"
      pattern: "organizations/{organization}/alertPolicies/{alert_policy}/conditions/{condition}"
      pattern: "folders/{folder}/alertPolicies/{alert_policy}/conditions/{condition}"
      pattern: "*"
    };

    // 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 control that determines how metric-threshold conditions
    // are evaluated when data stops arriving.
    // This control doesn't affect metric-absence policies.
    enum EvaluationMissingData {
      // An unspecified evaluation missing data option.  Equivalent to
      // EVALUATION_MISSING_DATA_NO_OP.
      EVALUATION_MISSING_DATA_UNSPECIFIED = 0;

      // If there is no data to evaluate the condition, then evaluate the
      // condition as false.
      EVALUATION_MISSING_DATA_INACTIVE = 1;

      // If there is no data to evaluate the condition, then evaluate the
      // condition as true.
      EVALUATION_MISSING_DATA_ACTIVE = 2;

      // Do not evaluate the condition to any value if there is no data.
      EVALUATION_MISSING_DATA_NO_OP = 3;
    }

    // A condition type that compares a collection of time series
    // against a threshold.
    message MetricThreshold {
      // 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). 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
      // 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). Multiple aggregations
      // are applied in the order specified.
      //
      // This field is similar to the one in the [`ListTimeSeries`
      // request](https://cloud.google.com/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](https://cloud.google.com/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 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.
      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., 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 = 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 control that determines how metric-threshold conditions
      // are evaluated when data stops arriving.
      EvaluationMissingData evaluation_missing_data = 11;
    }

    // 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 {
      // 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). 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
      // 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). Multiple aggregations
      // are applied in the order specified.
      //
      // This field is similar to the one in the [`ListTimeSeries`
      // request](https://cloud.google.com/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. 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;

      // 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;
    }

    // A condition type that checks whether a log message in the [scoping
    // project](https://cloud.google.com/monitoring/api/v3#project_name)
    // satisfies the given filter. Logs from other projects in the metrics
    // scope are not evaluated.
    message LogMatch {
      // Required. A logs-based filter. See [Advanced Logs
      // Queries](https://cloud.google.com/logging/docs/view/advanced-queries)
      // for how this filter should be constructed.
      string filter = 1 [(google.api.field_behavior) = REQUIRED];

      // Optional. A map from a label key to an extractor expression, which is
      // used to extract the value for this label key. Each entry in this map is
      // a specification for how data should be extracted from log entries that
      // match `filter`. Each combination of extracted values is treated as a
      // separate rule for the purposes of triggering notifications. Label keys
      // and corresponding values can be used in notifications generated by this
      // condition.
      //
      // Please see [the documentation on logs-based metric
      // `valueExtractor`s](https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.metrics#LogMetric.FIELDS.value_extractor)
      // for syntax and examples.
      map<string, string> label_extractors = 2;
    }

    // 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;

      // A condition control that determines how metric-threshold conditions
      // are evaluated when data stops arriving.
      EvaluationMissingData evaluation_missing_data = 4;
    }

    // Required if the condition exists. The unique resource name for this
    // condition. Its format is:
    //
    //     projects/[PROJECT_ID_OR_NUMBER]/alertPolicies/[POLICY_ID]/conditions/[CONDITION_ID]
    //
    // `[CONDITION_ID]` is assigned by Cloud 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. Cloud 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;

      // A condition that checks for log messages matching given constraints. If
      // set, no other conditions can be present.
      LogMatch condition_matched_log = 20;

      // A condition that uses the Monitoring Query Language to define
      // alerts.
      MonitoringQueryLanguageCondition condition_monitoring_query_language = 19;
    }
  }

  // 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 the 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;
  }

  // Control over how the notification channels in `notification_channels`
  // are notified when this alert fires.
  message AlertStrategy {
    // Control over the rate of notifications sent to this alert policy's
    // notification channels.
    message NotificationRateLimit {
      // Not more than one notification per `period`.
      google.protobuf.Duration period = 1;
    }

    // Required for alert policies with a `LogMatch` condition.
    //
    // This limit is not implemented for alert policies that are not log-based.
    NotificationRateLimit notification_rate_limit = 1;

    // If an alert policy that was active has no data for this long, any open
    // incidents will close
    google.protobuf.Duration auto_close = 3;
  }

  // Required if the policy exists. The resource name for this policy. The
  // format is:
  //
  //     projects/[PROJECT_ID_OR_NUMBER]/alertPolicies/[ALERT_POLICY_ID]
  //
  // `[ALERT_POLICY_ID]` is assigned by Cloud 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<string, string> 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.
  // If `condition_time_series_query_language` is present, it must be the only
  // `condition`.
  repeated Condition conditions = 12;

  // How to combine the results of multiple conditions to determine if an
  // incident should be opened.
  // If `condition_time_series_query_language` is present, this must be
  // `COMBINE_UNSPECIFIED`.
  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;

  // Read-only description of how the alert policy is invalid. OK if the alert
  // policy is valid. If not OK, the alert policy will not generate incidents.
  google.rpc.Status validity = 18;

  // 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 format of the entries in this field is:
  //
  //     projects/[PROJECT_ID_OR_NUMBER]/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;

  // Control over how this alert policy's notification channels are notified.
  AlertStrategy alert_strategy = 21;
}