kratos/third_party/google/cloud/irm/v1alpha2/incidents.proto

// Copyright 2018 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.cloud.irm.v1alpha2;

import "google/api/annotations.proto";
import "google/monitoring/v3/metric_service.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option go_package = "google.golang.org/genproto/googleapis/cloud/irm/v1alpha2;irm";
option java_multiple_files = true;
option java_package = "com.google.irm.service.v1alpha2.api";

// A user of the IRM app.
message User {
  // One of several ways to uniquely identify a user.
  oneof user {
    // Output only. User id that will allow to get additional information from
    // People API. This field will be populated implicitly if the caller creates
    // or edits a resource (for example, posts an annotation).
    string user_id = 1;

    // Email address of the user. This must be associated with a Google account.
    // This field will be set if the user is explicitly identified (verbatim) by
    // email address in an API request (potentially sometime in the past). It
    // will not be populated based on the credentials of a caller of the API.
    string email = 2;
  }
}

// A signal is a message calling attention to a (potential) incident. An example
// is a page based on a Stackdriver Alerting policy.
message Signal {
  // An artifact associated with the Signal.
  message SignalArtifact {
    // The type of resource linked to
    oneof artifact_type {
      // A custom user type
      string user_type = 2;
    }

    // The URI for the artifact.
    string uri = 3;
  }

  // Describes whether the alerting condition is still firing.
  enum State {
    // Unspecified
    STATE_UNSPECIFIED = 0;

    // Firing
    STATE_OPEN = 1;

    // Non-firing
    STATE_CLOSED = 2;
  }

  // Resource name of the signal, for example,
  // "projects/{project_id}/signals/{signal_id}".
  string name = 1;

  // Etag to validate the object is unchanged for a read-modify-write operation.
  // An empty etag will overwrite other changes.
  string etag = 2;

  // Resource name of the incident this signal is currently assigned to.
  // May be empty if signal is unassigned.
  string incident = 3;

  // Output only. Time this signal was created.
  google.protobuf.Timestamp create_time = 4;

  // Output only. Time this signal was closed. This field is not populated
  // while the signal is still firing.
  google.protobuf.Timestamp close_time = 10;

  // The time this Signal was first detected. This is identical to create_time
  // for Signals created by Stackdriver Alerting.
  google.protobuf.Timestamp detect_time = 15;

  // Output only. The user that created this signal for manually created
  // signals. Empty if this signal was generated by a system (for example,
  // Stackdriver Alerting).
  User creator = 5;

  // One-line summary of the signal.
  // Immutable.
  string title = 6;

  // Content type string, for example, 'text/plain' or'text/html'.
  string content_type = 7;

  // Full message of the signal.
  // Immutable for Signals created by Stackdriver Alerting.
  string content = 8;

  // The state of this signal.
  // For Signals created by Stackdriver Alerting this field is output only.
  State signal_state = 9;

  // A set of artifacts to additional resources for this Signal. For example, a
  // link to Stackdriver logging for the Signal.
  // Immutable for Signals created by Stackdriver Alerting.
  repeated SignalArtifact signal_artifacts = 16;
}

// A text annotation by a user.
message Annotation {
  // Resource name of the annotation, for example,
  // "projects/{project_id}/incidents/{incident_id}/annotations/{annotation_id}".
  string name = 1;

  // Output only. Author of the annotation.
  User author = 2;

  // Output only. Time the annotation was created.
  google.protobuf.Timestamp create_time = 3;

  // Content of the annotation. Immutable.
  string content = 4;
}

// A tag by a user.
message Tag {
  // Resource name of a tag, for example,
  // "projects/{project_id}/incidents/{incident_id}/tags/{tag_id}"
  string name = 1;

  // Display name of the resource (for example, "cause:rollout"). Immutable.
  string display_name = 2;
}

// Synopsis is a summary of an incident and it contains a textual content,
// an author and a last updated timestamp.
message Synopsis {
  // Content type string, for example, 'text/plain' or 'text/html'.
  string content_type = 1;

  // Textual content of the synopsis. It can be plain text or markdown as
  // indicated by the content_type.
  string content = 2;

  // Last updated timestamp.
  google.protobuf.Timestamp update_time = 3;

  // Author of the synopsis.
  User author = 4;
}

// Representation of an incident.
message Incident {
  // CommunicationVenue is a record of where conversations about an incident
  // are happening.
  message CommunicationVenue {
    // The type of channel/venue for incident communications.
    enum ChannelType {
      // An unspecified communication channel.
      CHANNEL_TYPE_UNSPECIFIED = 0;

      // A communication channel that is represented by a generic URI.
      CHANNEL_TYPE_URI = 1;

      // A communication channel that represents a Slack channel.
      CHANNEL_TYPE_SLACK = 5;
    }

    // A URI to the web interface of the channel.
    string uri = 1;

    // A name representing the channel in IRM UI.
    string display_name = 2;

    // The type of channel/venue for incident communications.
    ChannelType channel_type = 3;
  }

  // Specifies the escalation level of this incident, within the IRM protocol
  // for handling incidents.
  enum EscalationLevel {
    // The incident has not been escalated. This is the value used by all new
    // and legacy incidents.
    ESCALATION_LEVEL_UNSPECIFIED = 0;

    // The incident has been escalated to the organizational level.
    ESCALATION_LEVEL_ORGANIZATION = 1;
  }

  // Severity of an incident.
  enum Severity {
    // Severity is not specified.
    SEVERITY_UNSPECIFIED = 0;

    // Huge incident.
    SEVERITY_HUGE = 1;

    // Major incident.
    SEVERITY_MAJOR = 2;

    // Medium incident.
    SEVERITY_MEDIUM = 3;

    // Minor incident.
    SEVERITY_MINOR = 4;

    // Negligible incident.
    SEVERITY_NEGLIGIBLE = 5;
  }

  // Stage of an incident.
  enum Stage {
    // This is the default value if no stage has been specified.
    // Note: The caller of the API should set the stage to DETECTED.
    STAGE_UNSPECIFIED = 0;

    // The incident has been detected. This is the initial stage of a new
    // incident.
    // Note: The caller still has to set the stage manually.
    STAGE_DETECTED = 4;

    // This incident has been formally characterized.
    STAGE_TRIAGED = 1;

    // This incident has been mitigated, i.e. does not affect the service level
    // anymore.
    STAGE_MITIGATED = 2;

    // This incident has been fully resolved, i.e. there are no immediate
    // follow-up tasks.
    STAGE_RESOLVED = 3;

    // Postmortem for the incident was written.
    STAGE_DOCUMENTED = 5;

    // Stage for an incident with `duplicate_incident`. This incident is not
    // authoritative anymore and the `duplicate_incident` should be used to
    // determine the stage.
    STAGE_DUPLICATE = 6;
  }

  // Output only. Resource name of the incident, for example,
  // "projects/{project_id}/incidents/{incident_id}".
  string name = 1;

  // One-line summary of the incident.
  string title = 2;

  // Escalation level of the incident.
  EscalationLevel escalation_level = 3;

  // Etag to validate the object is unchanged for a read-modify-write operation.
  // An empty etag will overwrite other changes.
  string etag = 4;

  // Severity of the incident.
  Severity severity = 5;

  // Stage of the incident.
  Stage stage = 6;

  // Resource name of the incident this incident is a duplicate of. Empty if
  // this incident is not a duplicate.
  // An incident can only be a duplicate of an incident that is not marked as a
  // duplicate already. Setting this to a non-empty value must also set the
  // stage to `STAGE_DUPLICATE`. Unsetting this value value must also update
  // `stage` to a value other than `STAGE_DUPLICATE`.
  string duplicate_incident = 9;

  // Output only. Time this incident started. Used to measure the 'elapsed
  // time'. Start time of an incident is the earliest creation time of any of
  // its Signals or the create time of the incident if no Signals are assigned.
  google.protobuf.Timestamp start_time = 7;

  // Output only. Synopsis of this incident.
  Synopsis synopsis = 8;

  // Location of communications for this incident. This is informational
  // only; IRM does not use this to send messages.
  CommunicationVenue communication_venue = 10;
}

// Describes a role that can be assigned to an incident.
message IncidentRole {
  // List of possible roles.
  enum Type {
    // The role is unspecified.
    TYPE_UNSPECIFIED = 0;

    // Incident Commander: Manages response plan, near-term and long-term
    // objectives, establishes priorities, and delegates tasks as needed.
    TYPE_INCIDENT_COMMANDER = 1;

    // Communications Lead: Keeps everybody outside and within the response team
    // informed.
    TYPE_COMMUNICATIONS_LEAD = 2;

    // Operations Lead: Figures out what to do, and gets it done.
    TYPE_OPERATIONS_LEAD = 3;

    // External Customer Communications Lead: Responsible for communicating
    // incident details to customers/public.
    TYPE_EXTERNAL_CUSTOMER_COMMUNICATIONS_LEAD = 4;

    // Primary Oncall: Responds to the initial page and handles all
    // responsibilities for pre-escalated incidents.
    TYPE_PRIMARY_ONCALL = 5;

    // Secondary Oncall: Helps the primary oncall if necessary; mostly useful
    // for pre-escalated incidents.
    TYPE_SECONDARY_ONCALL = 6;

    // User-specified roles. One example is a Planning Lead, who keeps track of
    // the incident. Another is an assistant Incident Commander.
    TYPE_OTHER = 7;
  }

  // The type of role. The role type is immutable in role assignments. Each role
  // type can only be used once per incident, except for TYPE_OTHER.
  Type type = 1;

  // Output only unless TYPE_OTHER is used. Title of the role. For TYPE_OTHER,
  // must be unique within an incident.
  string title = 2;

  // Output only unless TYPE_OTHER is used. Description of the role.
  string description = 3;
}

// Stores the assignee of a role as well as the proposed next assignee.
message IncidentRoleAssignment {
  // Output only. Resource name such as
  // "projects/{project_id}/incidents/{incident_id}/role_assignments/{role_id}".
  string name = 1;

  // Output only. Etag for this version of the resource. Must be specified in
  // update requests and match the current version in storage. Must not be
  // modified by the client.
  string etag = 2;

  // The role that is or will be assigned.
  IncidentRole role = 3;

  // The user this role is assigned to. This field can only be directly set
  // during creation request. Subsequent updates are done via the
  // IncidentRoleHandover methods.
  User assignee = 4;

  // The recipient of a requested role handoff. This field can only be directly
  // set during creation request. Subsequent updates are done via the
  // IncidentRoleHandover methods.
  //
  // `assignee` is always the current role-holder, and `proposed_assignee` is
  // used to track unfinished assignments and handoffs. Let's say Bob assigns
  // Alice to a role. Then the fields are:
  //   `assignee`: nil, `proposed_assignee`: Alice
  // If Alice accepts, then the fields are:
  //   `assignee`: Alice, `proposed_assignee`: nil
  // If she cancels, then the RoleAssignment is deleted.
  // Let's say Alice has the role. Then the fields are:
  //   `assignee`: Alice, `proposed_assignee`: nil
  // If Alice becomes incapacitated and Bob requests Carol to take over, then
  // the fields are:
  //   `assignee`: Alice, `proposed_assignee`: Carol
  // After Carol accepts the handover, the fields are:
  //   `assignee`: Carol, `proposed_assignee`: nil
  // Or if Carol refuses the handover, the fields are:
  //   `assignee`: Alice, `proposed_assignee`: nil
  User proposed_assignee = 5;
}

// External artifact associated to an incident.
message Artifact {
  // Possible types of an artifact.
  enum Type {
    // External type is unspecified.
    TYPE_UNSPECIFIED = 0;

    // URL.
    TYPE_URL = 1;

    // A JIRA issue.
    TYPE_JIRA_ISSUE = 4;
  }

  // Output only. Resource name such as
  // "projects/{project_id}/incidents/{incident_id}/artifacts/{artifact_id}".
  string name = 1;

  // User provided name of an artifact.
  string display_name = 2;

  // Output only. Etag for this version of the resource. Must be specified in
  // update requests and match the current version in storage. Must not be
  // modified by the client.
  string etag = 3;

  // URL to access the artifact.
  string url = 4;

  // Type of this artifact.
  Type type = 5;
}

// Communication Channels are mechanisms used to receive notifications
// about changes to incidents.
message CommunicationChannel {
  // A communication channel that delivers messages to an email address.
  message Email {
    // The email address, for example, "user@example.com".
    string address = 1;
  }

  // A communication channel that delivers messages to a Stackdriver
  // notification channel.
  message NotificationChannel {
    // Stackdriver notification channel name.
    string name = 1;
  }

  // An endpoint describes how messages will be delivered.
  oneof endpoint {
    // Messages will be delivered via email.
    Email email = 1;

    // Messages will be delivered via a Stackdriver notification channel.
    NotificationChannel notification_channel = 2;
  }
}

// A subscription allows users to get notifications about changes to
// an incident.
message Subscription {
  // Types of changes that users can subscribe to in an incident.
  enum EventType {
    // An event_type that's not specified is an error.
    EVENT_TYPE_UNSPECIFIED = 0;

    // The incident's title has changed.
    EVENT_TYPE_TITLE_CHANGE = 1;

    // The incident's synopsis has changed.
    EVENT_TYPE_SYNOPSIS_CHANGE = 2;

    // The incident's stage has changed.
    EVENT_TYPE_STAGE_CHANGE = 3;

    // The incident's severity has changed.
    EVENT_TYPE_SEVERITY_CHANGE = 4;

    // A new annotation has been added to the incident.
    EVENT_TYPE_ANNOTATION_ADD = 5;

    // An annotation has been modified.
    EVENT_TYPE_ANNOTATION_CHANGE = 6;
  }

  // Output only. Resource name such as
  // "projects/{project_id}/incidents/{incident_id}/subscriptions/{subscription_id}".
  string name = 1;

  // Output only. Etag for this version of the resource. Must be specified in
  // update requests and match the current version in storage. Must not be
  // modified by the client.
  string etag = 2;

  // A communications channel to send subscription messages to.
  CommunicationChannel subscription_channel = 3;

  // Types of events this subscription receives notifications for.
  repeated EventType event_types = 4;
}