Migrate exception attributes to registry (#574)

Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>

CHANGELOG.md

@@ -9,6 +9,8 @@ release.
 
 - Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations
   ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354))
+- Move Exceptions to attribute registry
+  ([#574](https://github.com/open-telemetry/semantic-conventions/pull/574))
 
 ### Breaking
 

docs/attributes-registry/README.md

@@ -36,6 +36,7 @@ Currently, the following namespaces exist:
 * [Device](device.md)
 * [Disk](disk.md)
 * [Error](error.md)
+* [Exception](exception.md)
 * [Host](host.md)
 * [HTTP](http.md)
 * [K8s](k8s.md)

docs/attributes-registry/exception.md

@@ -0,0 +1,37 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Exceptions
+
+## Exception Attributes
+
+<!-- semconv registry.exception(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  |
+| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` |
+| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
+| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` |
+
+**[1]:** An exception is considered to have escaped (or left) the scope of a span,
+if that span is ended while the exception is still logically "in flight".
+This may be actually "in flight" in some languages (e.g. if the exception
+is passed to a Context manager's `__exit__` method in Python) but will
+usually be caught at the point of recording the exception in most languages.
+
+It is usually not possible to determine at the point where an exception is thrown
+whether it will escape the scope of a span.
+However, it is trivial to know that an exception
+will escape, if one checks for an active exception just before ending the span,
+as done in the [example for recording span exceptions](#recording-an-exception).
+
+It follows that an exception may still escape the scope of the span
+even if the `exception.escaped` attribute was not set or set to false,
+since the event might have been recorded at a time where it was not
+clear whether the exception will escape.
+<!-- endsemconv -->
+
+### Recording An Exception
+
+The `exception.escaped` attribute has special semantics in the context of
+a span. Please read the [details here](../exceptions/exceptions-spans.md#recording-an-exception).

docs/exceptions/exceptions-logs.md

@@ -38,14 +38,14 @@ The table below indicates which attributes should be added to the
 <!-- semconv log-exception -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
+| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
-| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
+| [`exception.stacktrace`](../attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
-| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
+| [`exception.type`](../attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
-* `exception.type`
+* [`exception.type`](../attributes-registry/exception.md)
-* `exception.message`
+* [`exception.message`](../attributes-registry/exception.md)
 <!-- endsemconv -->
 
 ### Stacktrace Representation

docs/exceptions/exceptions-spans.md

@@ -48,10 +48,10 @@ The event name MUST be `exception`.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  | Recommended |
+| [`exception.escaped`](../attributes-registry/exception.md) | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  | Recommended |
-| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
+| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
-| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
+| [`exception.stacktrace`](../attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
-| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
+| [`exception.type`](../attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
 
 **[1]:** An exception is considered to have escaped (or left) the scope of a span,
 if that span is ended while the exception is still logically "in flight".
@@ -63,7 +63,7 @@ It is usually not possible to determine at the point where an exception is throw
 whether it will escape the scope of a span.
 However, it is trivial to know that an exception
 will escape, if one checks for an active exception just before ending the span,
-as done in the [example above](#recording-an-exception).
+as done in the [example for recording span exceptions](#recording-an-exception).
 
 It follows that an exception may still escape the scope of the span
 even if the `exception.escaped` attribute was not set or set to false,
@@ -72,8 +72,8 @@ clear whether the exception will escape.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
-* `exception.type`
+* [`exception.type`](../attributes-registry/exception.md)
-* `exception.message`
+* [`exception.message`](../attributes-registry/exception.md)
 <!-- endsemconv -->
 
 ### Stacktrace Representation

model/exception.yaml

@@ -1,33 +0,0 @@
-groups:
-  - id: exception
-    type: span
-    prefix: exception
-    brief: >
-      This document defines the shared attributes used to
-      report a single exception associated with a span or log.
-    attributes:
-      - id: type
-        type: string
-        brief: >
-          The type of the exception (its fully-qualified class name, if applicable).
-          The dynamic type of the exception should be preferred over the static type
-          in languages that support it.
-        examples: ["java.net.ConnectException", "OSError"]
-      - id: message
-        type: string
-        brief: The exception message.
-        examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
-      - id: stacktrace
-        type: string
-        brief: >
-          A stacktrace as a string in the natural representation for the language runtime.
-          The representation is to be determined and documented by each language SIG.
-        examples: 'Exception in thread "main" java.lang.RuntimeException: Test exception\n
-        at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n
-        at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n
-        at com.example.GenerateTrace.main(GenerateTrace.java:5)'
-
-    constraints:
-      - any_of:
-          - "exception.type"
-          - "exception.message"

model/registry/exception.yaml

@@ -0,0 +1,50 @@
+groups:
+  - id: registry.exception
+    type: attribute_group
+    prefix: exception
+    brief: >
+      This document defines the shared attributes used to
+      report a single exception associated with a span or log.
+    attributes:
+      - id: type
+        type: string
+        brief: >
+          The type of the exception (its fully-qualified class name, if applicable).
+          The dynamic type of the exception should be preferred over the static type
+          in languages that support it.
+        examples: ["java.net.ConnectException", "OSError"]
+      - id: message
+        type: string
+        brief: The exception message.
+        examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
+      - id: stacktrace
+        type: string
+        brief: >
+          A stacktrace as a string in the natural representation for the language runtime.
+          The representation is to be determined and documented by each language SIG.
+        examples: 'Exception in thread "main" java.lang.RuntimeException: Test exception\n
+        at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n
+        at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n
+        at com.example.GenerateTrace.main(GenerateTrace.java:5)'
+      - id: escaped
+        type: boolean
+        brief: >
+          SHOULD be set to true if the exception event is recorded at a point where
+          it is known that the exception is escaping the scope of the span.
+        note: |-
+          An exception is considered to have escaped (or left) the scope of a span,
+          if that span is ended while the exception is still logically "in flight".
+          This may be actually "in flight" in some languages (e.g. if the exception
+          is passed to a Context manager's `__exit__` method in Python) but will
+          usually be caught at the point of recording the exception in most languages.
+
+          It is usually not possible to determine at the point where an exception is thrown
+          whether it will escape the scope of a span.
+          However, it is trivial to know that an exception
+          will escape, if one checks for an active exception just before ending the span,
+          as done in the [example for recording span exceptions](#recording-an-exception).
+
+          It follows that an exception may still escape the scope of the span
+          even if the `exception.escaped` attribute was not set or set to false,
+          since the event might have been recorded at a time where it was not
+          clear whether the exception will escape.

model/trace/trace-exception.yaml

@@ -9,29 +9,7 @@ groups:
       - ref: exception.type
       - ref: exception.message
       - ref: exception.stacktrace
-      - id: escaped
+      - ref: exception.escaped
-        type: boolean
-        brief: >
-          SHOULD be set to true if the exception event is recorded at a point where
-          it is known that the exception is escaping the scope of the span.
-        note: |-
-          An exception is considered to have escaped (or left) the scope of a span,
-          if that span is ended while the exception is still logically "in flight".
-          This may be actually "in flight" in some languages (e.g. if the exception
-          is passed to a Context manager's `__exit__` method in Python) but will
-          usually be caught at the point of recording the exception in most languages.
-
-          It is usually not possible to determine at the point where an exception is thrown
-          whether it will escape the scope of a span.
-          However, it is trivial to know that an exception
-          will escape, if one checks for an active exception just before ending the span,
-          as done in the [example above](#recording-an-exception).
-
-          It follows that an exception may still escape the scope of the span
-          even if the `exception.escaped` attribute was not set or set to false,
-          since the event might have been recorded at a time where it was not
-          clear whether the exception will escape.
-
     constraints:
       - any_of:
           - "exception.type"