Replace constraints with requirement levels on exceptions (#862)

Co-authored-by: Joao Grassi <[email protected]>

.chloggen/862.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: exception
+note: Replace constraints with requirement levels on exceptions.
+issues: [ 862 ]

docs/exceptions/exceptions-logs.md

@@ -38,14 +38,13 @@ The table below indicates which attributes should be added to the
 <!-- semconv log-exception -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`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` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`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 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
-**Additional attribute requirements:** At least one of the following sets of attributes is required:
+**[1]:** Required if `exception.type` is not set, recommended otherwise.
 
-* [`exception.type`](../attributes-registry/exception.md)
-* [`exception.message`](../attributes-registry/exception.md)
+**[2]:** Required if `exception.message` is not set, recommended otherwise.
 <!-- endsemconv -->
 
 ### Stacktrace Representation

docs/exceptions/exceptions-spans.md

@@ -48,12 +48,16 @@ The event name MUST be `exception`.
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`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` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`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. [3] |  | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`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 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
-**[1]:** An exception is considered to have escaped (or left) the scope of a span,
+**[1]:** Required if `exception.type` is not set, recommended otherwise.
+
+**[2]:** Required if `exception.message` is not set, recommended otherwise.
+
+**[3]:** 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
@@ -69,11 +73,6 @@ 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.
-
-**Additional attribute requirements:** At least one of the following sets of attributes is required:
-
-* [`exception.type`](../attributes-registry/exception.md)
-* [`exception.message`](../attributes-registry/exception.md)
 <!-- endsemconv -->
 
 ### Stacktrace Representation

model/logs/log-exception.yaml

@@ -7,10 +7,9 @@ groups:
       Records.
     attributes:
       - ref: exception.type
+        requirement_level:
+          conditionally_required: Required if `exception.message` is not set, recommended otherwise.
       - ref: exception.message
+        requirement_level:
+          conditionally_required: Required if `exception.type` is not set, recommended otherwise.
       - ref: exception.stacktrace
-
-    constraints:
-      - any_of:
-          - "exception.type"
-          - "exception.message"

model/trace/trace-exception.yaml

@@ -7,10 +7,10 @@ groups:
       report a single exception associated with a span.
     attributes:
       - ref: exception.type
+        requirement_level:
+          conditionally_required: Required if `exception.message` is not set, recommended otherwise.
       - ref: exception.message
+        requirement_level:
+          conditionally_required: Required if `exception.type` is not set, recommended otherwise.
       - ref: exception.stacktrace
       - ref: exception.escaped
-    constraints:
-      - any_of:
-          - "exception.type"
-          - "exception.message"