From 21c13644ad8a0ba9b2931651c4c7eaecfbce8b7a Mon Sep 17 00:00:00 2001
From: Anne <102554163+alovew@users.noreply.github.com>
Date: Tue, 3 May 2022 14:11:50 -0700
Subject: [PATCH] Add AirbyteTraceMessage to Airbyte protocol (#12458)

* Add AirbyteTraceMessage to protocol
Co-authored-by: Lake Mossman <lake@airbyte.io>
---
 .../airbyte_protocol/airbyte_protocol.yaml    | 43 +++++++++++++++++++
 .../airbyte-specification.md                  |  5 ++-
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/airbyte-protocol/models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml b/airbyte-protocol/models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml
index cea7e57cfc8b6..1eabc18c01ebe 100644
--- a/airbyte-protocol/models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml
+++ b/airbyte-protocol/models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml
@@ -26,6 +26,7 @@ definitions:
           - SPEC
           - CONNECTION_STATUS
           - CATALOG
+          - TRACE
       log:
         description: "log message: any kind of logging you want the platform to know about."
         "$ref": "#/definitions/AirbyteLogMessage"
@@ -43,6 +44,9 @@ definitions:
       state:
         description: "schema message: the state. Must be the last message produced. The platform uses this information"
         "$ref": "#/definitions/AirbyteStateMessage"
+      trace:
+        description: "trace message: a message to communicate information about the status and performance of a connector"
+        "$ref": "#/definitions/AirbyteTraceMessage"
   AirbyteRecordMessage:
     type: object
     additionalProperties: true
@@ -94,6 +98,45 @@ definitions:
       message:
         description: "the log message"
         type: string
+  AirbyteTraceMessage:
+    type: object
+    additionalProperties: true
+    required:
+      - type
+      - emitted_at
+    properties:
+      type:
+        description: "the type of trace message"
+        type: string
+        enum:
+          - ERROR
+      emitted_at:
+        description: "the time in ms that the message was emitted"
+        type: number
+      error:
+        description: "error trace message: the error object"
+        "$ref": "#/definitions/AirbyteErrorTraceMessage"
+  AirbyteErrorTraceMessage:
+    type: object
+    additionalProperties: true
+    required:
+      - message
+    properties:
+      message:
+        description: A user-friendly message that indicates the cause of the error
+        type: string
+      internal_message:
+        description: The internal error that caused the failure
+        type: string
+      stack_trace:
+        description: The full stack trace of the error
+        type: string
+      failure_type:
+        description: The type of error
+        type: string
+        enum:
+          - system_error
+          - config_error
   AirbyteConnectionStatus:
     description: Airbyte connection status
     type: object
diff --git a/docs/understanding-airbyte/airbyte-specification.md b/docs/understanding-airbyte/airbyte-specification.md
index 351613b03ef14..a06f66520411e 100644
--- a/docs/understanding-airbyte/airbyte-specification.md
+++ b/docs/understanding-airbyte/airbyte-specification.md
@@ -214,8 +214,9 @@ For the sake of brevity, we will not re-describe `spec` and `check`. They are ex
 ## The Airbyte Protocol
 
 * All messages passed to and from connectors must be wrapped in an `AirbyteMessage` envelope and serialized as JSON. The JsonSchema specification for these messages can be found [here](https://github.com/airbytehq/airbyte/blob/922bfd08a9182443599b78dbb273d70cb9f63d30/airbyte-protocol/models/src/main/resources/airbyte_protocol/airbyte_protocol.yaml#L13-L45).
-* Even if a record is wrapped in an `AirbyteMessage` it will only be processed if it appropriate for the given command. e.g. If a source `read` action includes AirbyteMessages in its stream of type Catalog for instance, these messages will be ignored as the `read` interface only expects `AirbyteRecordMessage`s and `AirbyteStateMessage`s. The appropriate `AirbyteMessage` types have been described in each command above.
-* **ALL** actions are allowed to return `AirbyteLogMessage`s on stdout. For brevity, we have not mentioned these log messages in the description of each action, but they are always allowed. An `AirbyteLogMessage` wraps any useful logging that the connector wants to provide. These logs will be written to Airbyte's log files and output to the console.
+* Even if a record is wrapped in an `AirbyteMessage` it will only be processed if it is appropriate for the given command. e.g. If a source `read` action includes AirbyteMessages in its stream of type Catalog for instance, these messages will be ignored as the `read` interface only expects `AirbyteRecordMessage`s and `AirbyteStateMessage`s. The appropriate `AirbyteMessage` types have been described in each command above.
+* **ALL** actions are allowed to return `AirbyteLogMessage`s and `AirbyteTraceMessage`s on stdout. For brevity, we have not mentioned these messages in the description of each action, but they are always allowed. An `AirbyteLogMessage` wraps any useful logging that the connector wants to provide. These logs will be written to Airbyte's log files and output to the console. An `AirbyteTraceMessage` provides structured information about the performance and status of a connector, such as the failure reason in the event of an error. 
+
 * I/O:
   * Connectors receive arguments on the command line via JSON files. `e.g. --catalog catalog.json`
   * They read `AirbyteMessage`s from stdin. The destination `write` action is the only command that consumes `AirbyteMessage`s.