zen/schemas/proto/notify/v1/send_notification.proto

syntax = "proto3";

package notify.v1;

import "notify/v1/types.proto";

message SendNotificationRequest {
  Payload payload = 1;
  Service service = 2;
}

// SendAttachmentResponse is sent when message is successful.
message SendNotificationResponse {
  // notification_id is the snowflake id of the message.
  //
  // Guaranteed to be unique even on distributed environment.
  //
  // notification_id can be used in `SendAttachment` rpc to
  // attach binary data to the message.
  string notification_id = 1;
}

message Payload {
  // message is the content of the notification.
  //
  // message should be short and concise since they are
  // intended as forefront information.
  //
  // details should go to the `details` field.
  string message = 1;
  // level is the severity of the message.
  //
  // current implementation treats LEVEL_UNSPECIFIED as LEVEL_INFO,
  // but it's recommended to set the level explicitly to avoid
  // surprises in the future.
  Level level = 2;
  int64 code = 3;
  // details adds context to the message.
  //
  // like invalid inputs,
  // request payloads, backend response, etc.
  //
  // Anything that can enrich why this message
  // appears will help.
  //
  // DO NOT INCLUDE BINARIES LIKE IMAGES, PDFS, DOCS, IN
  // THIS PAYLOAD. USE `SendAttachment` rpc
  // to attach binary values instead since they are designed
  // for streaming. Server and Client RAM
  // can be eaten alive if you ignore this predicament since GRPC
  // handles via whole messages.
  oneof details {
    // Sends JSON as details.
    //
    // In the report page, this will be rendered with JSONGrid.
    bytes d_json = 4;
    // Sends text as details.
    //
    // Markdown syntax is supported and markdown will be rendered
    // on the report page.
    string d_text = 5;
  }
  // error is the error message that is sent.
  oneof error {
    // sends error details as JSON.
    //
    // like details, do not include binaries in this field.
    //
    // In the report page, this will be rendered with JSONGrid.
    bytes e_json = 6;
    // sends error details as text.
    //
    // Markdown syntax is supported and markdown will be rendered
    // on the report page.
    string e_text = 7;
  }
  // id is the unique identifier of the message.
  //
  // message with same id is considered as the same message
  // even if the content is different.
  string id = 8;

  // trace_id is the trace id of the message.
  //
  // trace_id is used to trace the message across services.
  //
  // Leave this empty/unset if no traces are available.
  string trace_id = 9;

  // span_id is the span id of the message.
  //
  // span_id is used to trace the message within the service/scope.
  //
  // Leave this empty/unset if no spans are available.
  string span_id = 10;
}

message Service {
  // The name of the service that is sending the notification.
  //
  // This is used to identify the service that is sending the notification.
  //
  // The value of name should be related to the product or service.
  // e.g. `sbn-frontend`, `sbn-cron-job`, `payment-frontend`, `robo-frontend`.
  //
  // `name`, `type`, and `environment` combination are used to select which channel the
  // discord notification is sent.
  string name = 1;
  string type = 2;
  Environment environment = 3;
  optional string version = 4;
  // domain specifies whose message this belongs to.
  //
  // It's not required to be set, but setting this field
  // will help zen to categorize messages when building
  // reports.
  ServiceDomain domain = 5;

  // attributes are informations that enriches the service.
  //
  // like Session ID, Region, User-Agent, etc.
  map<string, string> attributes = 6;
}

enum ServiceDomain {
  SERVICE_DOMAIN_UNSPECIFIED = 0;
  SERVICE_DOMAIN_FRONTEND = 1;
  SERVICE_DOMAIN_BACKEND = 2;
}