From 98bd326c23f060d962821bca982bbb881e32c540 Mon Sep 17 00:00:00 2001
From: Francesco Guardiani <me@slinkydeveloper.com>
Date: Tue, 16 Apr 2024 11:15:08 +0200
Subject: [PATCH] Entry names + specify the entry that caused the failure in
 ErrorMessage (#86)

---
 dev/restate/service/protocol.proto | 45 +++++++++++++++++++++++++++++-
 service-invocation-protocol.md     | 10 +++++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/dev/restate/service/protocol.proto b/dev/restate/service/protocol.proto
index 71ca06c..02fe428 100644
--- a/dev/restate/service/protocol.proto
+++ b/dev/restate/service/protocol.proto
@@ -75,6 +75,14 @@ message ErrorMessage {
   string message = 2;
   // Contains a verbose error description, e.g. the exception stacktrace.
   string description = 3;
+
+  // Entry that caused the failure. This may be outside the current stored journal size.
+  // If no specific entry caused the failure, the current replayed/processed entry can be used.
+  uint32 related_entry_index = 4;
+  // Name of the entry that caused the failure. Empty if no name was set.
+  string related_entry_name = 5;
+  // Entry type. 0 if unknown.
+  uint32 related_entry_type = 6;
 }
 
 // Type: 0x0000 + 4
@@ -96,7 +104,7 @@ message EndMessage {
 //   * bytes value = 14 for carrying the result value
 //   * Failure failure = 15 for carrying a failure
 //
-// The tag numbers 13, 14 and 15 are reserved and shouldn't be used for other fields.
+// The tag numbers 12, 13, 14 and 15 are reserved and shouldn't be used for other fields.
 
 // ------ Input and output ------
 
@@ -107,6 +115,9 @@ message InputEntryMessage {
   repeated Header headers = 1;
 
   bytes value = 14;
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: No
@@ -117,6 +128,9 @@ message OutputEntryMessage {
     bytes value = 14;
     Failure failure = 15;
   };
+
+  // Entry name
+  string name = 12;
 }
 
 // ------ State access ------
@@ -132,6 +146,9 @@ message GetStateEntryMessage {
     bytes value = 14;
     Failure failure = 15;
   };
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: No
@@ -140,6 +157,9 @@ message GetStateEntryMessage {
 message SetStateEntryMessage {
   bytes key = 1;
   bytes value = 3;
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: No
@@ -147,12 +167,17 @@ message SetStateEntryMessage {
 // Type: 0x0800 + 2
 message ClearStateEntryMessage {
   bytes key = 1;
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: No
 // Fallible: No
 // Type: 0x0800 + 3
 message ClearAllStateEntryMessage {
+  // Entry name
+  string name = 12;
 }
 
 // Completable: Yes
@@ -167,6 +192,9 @@ message GetStateKeysEntryMessage {
     StateKeys value = 14;
     Failure failure = 15;
   };
+
+  // Entry name
+  string name = 12;
 }
 
 // ------ Syscalls ------
@@ -183,6 +211,9 @@ message SleepEntryMessage {
     Empty empty = 13;
     Failure failure = 15;
   }
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: Yes
@@ -203,6 +234,9 @@ message InvokeEntryMessage {
     bytes value = 14;
     Failure failure = 15;
   };
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: No
@@ -224,6 +258,9 @@ message BackgroundInvokeEntryMessage {
 
   // If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
   string key = 6;
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: Yes
@@ -235,6 +272,9 @@ message AwakeableEntryMessage {
     bytes value = 14;
     Failure failure = 15;
   };
+
+  // Entry name
+  string name = 12;
 }
 
 // Completable: No
@@ -248,6 +288,9 @@ message CompleteAwakeableEntryMessage {
     bytes value = 5;
     Failure failure = 6;
   };
+
+  // Entry name
+  string name = 12;
 }
 
 // --- Nested messages
diff --git a/service-invocation-protocol.md b/service-invocation-protocol.md
index 293a129..17278c0 100644
--- a/service-invocation-protocol.md
+++ b/service-invocation-protocol.md
@@ -297,6 +297,11 @@ index of the corresponding entry.
     |                             Length                            |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
+#### Entry names
+
+Every Journal entry has a field `string name = 12`, which can be set by the SDK when recording the entry. This field is
+used for observability purposes by Restate observability tools.
+
 ### Journal entries reference
 
 The following tables describe the currently available journal entries. For more details, check the protobuf message
@@ -387,6 +392,11 @@ additional features to the users.
 The protocol allows the SDK to register an arbitrary entry type within the journal. The type MUST be `>= 0xFC00`. The
 runtime will treat this entry as any other entry, persisting it and sending it during replay in the correct order.
 
+Custom entries MAY have the entry name field `12`, as described in [entry names](#entry-names).
+
+The field numbers 13, 14 and 15 MUST not be used, as they're reserved for completable journal entries, as described in
+[completable journal entries](#completable-journal-entries-and-completionmessage).
+
 **Header**
 
     0                   1                   2                   3