From 4c951daa415da727ce04e189f381daadbf451b76 Mon Sep 17 00:00:00 2001
From: Tigor Hutasuhut <tigor.hutasuhut@gmail.com>
Date: Tue, 27 Aug 2024 18:17:04 +0700
Subject: [PATCH] proto: update notification proto

---
 core/ztelemetry/ztelemetry.go                 |  1 +
 .../proto/notify/v1/send_notification.proto   | 57 +++++++++++++++++--
 2 files changed, 54 insertions(+), 4 deletions(-)
 create mode 100644 core/ztelemetry/ztelemetry.go

diff --git a/core/ztelemetry/ztelemetry.go b/core/ztelemetry/ztelemetry.go
new file mode 100644
index 0000000..85a8fa5
--- /dev/null
+++ b/core/ztelemetry/ztelemetry.go
@@ -0,0 +1 @@
+package ztelemetry
diff --git a/schemas/proto/notify/v1/send_notification.proto b/schemas/proto/notify/v1/send_notification.proto
index 20b3d49..bf64cb5 100644
--- a/schemas/proto/notify/v1/send_notification.proto
+++ b/schemas/proto/notify/v1/send_notification.proto
@@ -21,12 +21,23 @@ message SendNotificationResponse {
 }
 
 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;
-  optional int64 code = 3;
+  int64 code = 3;
   // details adds context to the message.
   //
-  // like timestamps, invalid inputs,
+  // like invalid inputs,
   // request payloads, backend response, etc.
   //
   // Anything that can enrich why this message
@@ -36,18 +47,52 @@ message Payload {
   // 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 failed to do so since GRPC
+  // 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 {
@@ -70,7 +115,11 @@ message Service {
   // will help zen to categorize messages when building
   // reports.
   ServiceDomain domain = 5;
-  repeated Attribute attributes = 6;
+
+  // attributes are informations that enriches the service.
+  //
+  // like Session ID, Region, User-Agent, etc.
+  map<string, string> attributes = 6;
 }
 
 enum ServiceDomain {