feat: add a stack_trace field to the Error messages specifying where the error occured feat: add call_log_level field to Execution messages doc: clarify requirement to escape strings within JSON arguments

protos/google/cloud/workflows/executions/v1/executions.proto

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -83,16 +83,52 @@ message Execution {
     pattern: "projects/{project}/locations/{location}/workflows/{workflow}/executions/{execution}"
   };
 
+  // A single stack element (frame) where an error occurred.
+  message StackTraceElement {
+    // Position contains source position information about the stack trace
+    // element such as line number, column number and length of the code block
+    // in bytes.
+    message Position {
+      // The source code line number the current instruction was generated from.
+      int64 line = 1;
+
+      // The source code column position (of the line) the current instruction
+      // was generated from.
+      int64 column = 2;
+
+      // The number of bytes of source code making up this stack trace element.
+      int64 length = 3;
+    }
+
+    // The step the error occurred at.
+    string step = 1;
+
+    // The routine where the error occurred.
+    string routine = 2;
+
+    // The source position information of the stack trace element.
+    Position position = 3;
+  }
+
+  // A collection of stack elements (frames) where an error occurred.
+  message StackTrace {
+    // An array of stack elements.
+    repeated StackTraceElement elements = 1;
+  }
+
   // Error describes why the execution was abnormally terminated.
   message Error {
-    // Error payload returned by the execution, represented as a JSON string.
+    // Error message and data returned represented as a JSON string.
     string payload = 1;
 
-    // Human readable error context, helpful for debugging purposes.
+    // Human-readable stack trace string.
     string context = 2;
+
+    // Stack trace with detailed information of where error was generated.
+    StackTrace stack_trace = 3;
   }
 
-  // Describes the current state of the execution. More states may be added
+  // Describes the current state of the execution. More states might be added
   // in the future.
   enum State {
     // Invalid state.
@@ -111,6 +147,20 @@ message Execution {
     CANCELLED = 4;
   }
 
+  // Describes the level of platform logging to apply to calls and call
+  // responses during workflow executions.
+  enum CallLogLevel {
+    // No call logging specified.
+    CALL_LOG_LEVEL_UNSPECIFIED = 0;
+
+    // Log all call steps within workflows, all call returns, and all exceptions
+    // raised.
+    LOG_ALL_CALLS = 1;
+
+    // Log only exceptions that are raised from call steps within workflows.
+    LOG_ERRORS_ONLY = 2;
+  }
+
   // Output only. The resource name of the execution.
   // Format:
   // projects/{project}/locations/{location}/workflows/{workflow}/executions/{execution}
@@ -127,6 +177,10 @@ message Execution {
 
   // Input parameters of the execution represented as a JSON string.
   // The size limit is 32KB.
+  //
+  // *Note*: If you are using the REST API directly to run your workflow, you
+  // must escape any JSON string value of `argument`. Example:
+  // `'{"argument":"{\"firstName\":\"FIRST\",\"lastName\":\"LAST\"}"}'`
   string argument = 5;
 
   // Output only. Output of the execution represented as a JSON string. The
@@ -140,6 +194,9 @@ message Execution {
 
   // Output only. Revision of the workflow this execution is using.
   string workflow_revision_id = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // The call logging level associated to this execution.
+  CallLogLevel call_log_level = 9;
 }
 
 // Request for the