feat: add a stack_trace field to the Error messages specifying where …

…the error occurred (#113)

- [ ] Regenerate this pull request now.

Update the Execution proto with stack_trace field which is populated on output if an error occurs, and the call_log_level field can be specified on input to request that function calls and/or errors for the given execution be logged to Cloud Logging.

PiperOrigin-RevId: 407842136

Source-Link: googleapis/googleapis@cd48c16

Source-Link: googleapis/googleapis-gen@eefbcd7
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZWVmYmNkNzAzNDJhZGVlMWRmNTJlNGM1OTUyNDNkYTc1MWU1YjZhOSJ9

feat: add call_log_level field to Execution messages
doc: clarify requirement to escape strings within JSON arguments

google/cloud/workflows/executions_v1/types/executions.py

@@ -57,8 +57,13 @@ class Execution(proto.Message):
         state (google.cloud.workflows.executions_v1.types.Execution.State):
             Output only. Current state of the execution.
         argument (str):
-            Input parameters of the execution represented
-            as a JSON string. The size limit is 32KB.
+            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\"}"}'``
         result (str):
             Output only. Output of the execution represented as a JSON
             string. The value can only be present if the execution's
@@ -70,32 +75,101 @@ class Execution(proto.Message):
         workflow_revision_id (str):
             Output only. Revision of the workflow this
             execution is using.
+        call_log_level (google.cloud.workflows.executions_v1.types.Execution.CallLogLevel):
+            The call logging level associated to this
+            execution.
     """
 
     class State(proto.Enum):
-        r"""Describes the current state of the execution. More states may
-        be added in the future.
+        r"""Describes the current state of the execution. More states
+        might be added in the future.
         """
         STATE_UNSPECIFIED = 0
         ACTIVE = 1
         SUCCEEDED = 2
         FAILED = 3
         CANCELLED = 4
 
+    class CallLogLevel(proto.Enum):
+        r"""Describes the level of platform logging to apply to calls and
+        call responses during workflow executions.
+        """
+        CALL_LOG_LEVEL_UNSPECIFIED = 0
+        LOG_ALL_CALLS = 1
+        LOG_ERRORS_ONLY = 2
+
+    class StackTraceElement(proto.Message):
+        r"""A single stack element (frame) where an error occurred.
+
+        Attributes:
+            step (str):
+                The step the error occurred at.
+            routine (str):
+                The routine where the error occurred.
+            position (google.cloud.workflows.executions_v1.types.Execution.StackTraceElement.Position):
+                The source position information of the stack
+                trace element.
+        """
+
+        class Position(proto.Message):
+            r"""Position contains source position information about the stack
+            trace element such as line number, column number and length of
+            the code block in bytes.
+
+            Attributes:
+                line (int):
+                    The source code line number the current
+                    instruction was generated from.
+                column (int):
+                    The source code column position (of the line)
+                    the current instruction was generated from.
+                length (int):
+                    The number of bytes of source code making up
+                    this stack trace element.
+            """
+
+            line = proto.Field(proto.INT64, number=1,)
+            column = proto.Field(proto.INT64, number=2,)
+            length = proto.Field(proto.INT64, number=3,)
+
+        step = proto.Field(proto.STRING, number=1,)
+        routine = proto.Field(proto.STRING, number=2,)
+        position = proto.Field(
+            proto.MESSAGE, number=3, message="Execution.StackTraceElement.Position",
+        )
+
+    class StackTrace(proto.Message):
+        r"""A collection of stack elements (frames) where an error
+        occurred.
+
+        Attributes:
+            elements (Sequence[google.cloud.workflows.executions_v1.types.Execution.StackTraceElement]):
+                An array of stack elements.
+        """
+
+        elements = proto.RepeatedField(
+            proto.MESSAGE, number=1, message="Execution.StackTraceElement",
+        )
+
     class Error(proto.Message):
         r"""Error describes why the execution was abnormally terminated.
 
         Attributes:
             payload (str):
-                Error payload returned by the execution,
-                represented as a JSON string.
+                Error message and data returned represented
+                as a JSON string.
             context (str):
-                Human readable error context, helpful for
-                debugging purposes.
+                Human-readable stack trace string.
+            stack_trace (google.cloud.workflows.executions_v1.types.Execution.StackTrace):
+                Stack trace with detailed information of
+                where error was generated.
         """
 
         payload = proto.Field(proto.STRING, number=1,)
         context = proto.Field(proto.STRING, number=2,)
+        stack_trace = proto.Field(
+            proto.MESSAGE, number=3, message="Execution.StackTrace",
+        )
 
     name = proto.Field(proto.STRING, number=1,)
     start_time = proto.Field(proto.MESSAGE, number=2, message=timestamp_pb2.Timestamp,)
@@ -105,6 +179,7 @@ class Error(proto.Message):
     result = proto.Field(proto.STRING, number=6,)
     error = proto.Field(proto.MESSAGE, number=7, message=Error,)
     workflow_revision_id = proto.Field(proto.STRING, number=8,)
+    call_log_level = proto.Field(proto.ENUM, number=9, enum=CallLogLevel,)
 
 
 class ListExecutionsRequest(proto.Message):

tests/unit/gapic/executions_v1/test_executions.py

@@ -823,6 +823,7 @@ def test_create_execution(
             argument="argument_value",
             result="result_value",
             workflow_revision_id="workflow_revision_id_value",
+            call_log_level=executions.Execution.CallLogLevel.LOG_ALL_CALLS,
         )
         response = client.create_execution(request)
 
@@ -838,6 +839,7 @@ def test_create_execution(
     assert response.argument == "argument_value"
     assert response.result == "result_value"
     assert response.workflow_revision_id == "workflow_revision_id_value"
+    assert response.call_log_level == executions.Execution.CallLogLevel.LOG_ALL_CALLS
 
 
 def test_create_execution_from_dict():
@@ -881,6 +883,7 @@ async def test_create_execution_async(
                 argument="argument_value",
                 result="result_value",
                 workflow_revision_id="workflow_revision_id_value",
+                call_log_level=executions.Execution.CallLogLevel.LOG_ALL_CALLS,
             )
         )
         response = await client.create_execution(request)
@@ -897,6 +900,7 @@ async def test_create_execution_async(
     assert response.argument == "argument_value"
     assert response.result == "result_value"
     assert response.workflow_revision_id == "workflow_revision_id_value"
+    assert response.call_log_level == executions.Execution.CallLogLevel.LOG_ALL_CALLS
 
 
 @pytest.mark.asyncio
@@ -1049,6 +1053,7 @@ def test_get_execution(
             argument="argument_value",
             result="result_value",
             workflow_revision_id="workflow_revision_id_value",
+            call_log_level=executions.Execution.CallLogLevel.LOG_ALL_CALLS,
         )
         response = client.get_execution(request)
 
@@ -1064,6 +1069,7 @@ def test_get_execution(
     assert response.argument == "argument_value"
     assert response.result == "result_value"
     assert response.workflow_revision_id == "workflow_revision_id_value"
+    assert response.call_log_level == executions.Execution.CallLogLevel.LOG_ALL_CALLS
 
 
 def test_get_execution_from_dict():
@@ -1107,6 +1113,7 @@ async def test_get_execution_async(
                 argument="argument_value",
                 result="result_value",
                 workflow_revision_id="workflow_revision_id_value",
+                call_log_level=executions.Execution.CallLogLevel.LOG_ALL_CALLS,
             )
         )
         response = await client.get_execution(request)
@@ -1123,6 +1130,7 @@ async def test_get_execution_async(
     assert response.argument == "argument_value"
     assert response.result == "result_value"
     assert response.workflow_revision_id == "workflow_revision_id_value"
+    assert response.call_log_level == executions.Execution.CallLogLevel.LOG_ALL_CALLS
 
 
 @pytest.mark.asyncio
@@ -1265,6 +1273,7 @@ def test_cancel_execution(
             argument="argument_value",
             result="result_value",
             workflow_revision_id="workflow_revision_id_value",
+            call_log_level=executions.Execution.CallLogLevel.LOG_ALL_CALLS,
         )
         response = client.cancel_execution(request)
 
@@ -1280,6 +1289,7 @@ def test_cancel_execution(
     assert response.argument == "argument_value"
     assert response.result == "result_value"
     assert response.workflow_revision_id == "workflow_revision_id_value"
+    assert response.call_log_level == executions.Execution.CallLogLevel.LOG_ALL_CALLS
 
 
 def test_cancel_execution_from_dict():
@@ -1323,6 +1333,7 @@ async def test_cancel_execution_async(
                 argument="argument_value",
                 result="result_value",
                 workflow_revision_id="workflow_revision_id_value",
+                call_log_level=executions.Execution.CallLogLevel.LOG_ALL_CALLS,
             )
         )
         response = await client.cancel_execution(request)
@@ -1339,6 +1350,7 @@ async def test_cancel_execution_async(
     assert response.argument == "argument_value"
     assert response.result == "result_value"
     assert response.workflow_revision_id == "workflow_revision_id_value"
+    assert response.call_log_level == executions.Execution.CallLogLevel.LOG_ALL_CALLS
 
 
 @pytest.mark.asyncio