From 34edf1b967a99d58d516fcbc9438818012b1b9ef Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 5 Apr 2024 10:29:01 -0700 Subject: [PATCH] Replace constraints with requirement levels on exceptions (#862) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/862.yaml | 4 ++++ docs/exceptions/exceptions-logs.md | 9 ++++----- docs/exceptions/exceptions-spans.md | 17 ++++++++--------- model/logs/log-exception.yaml | 9 ++++----- model/trace/trace-exception.yaml | 8 ++++---- 5 files changed, 24 insertions(+), 23 deletions(-) create mode 100644 .chloggen/862.yaml diff --git a/.chloggen/862.yaml b/.chloggen/862.yaml new file mode 100644 index 0000000000..828a88899e --- /dev/null +++ b/.chloggen/862.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: exception +note: Replace constraints with requirement levels on exceptions. +issues: [ 862 ] diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index e19e35330c..6f1d98f92c 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -38,14 +38,13 @@ The table below indicates which attributes should be added to the | 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. ### Stacktrace Representation diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index c438e9951b..0dbb2e7313 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/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) ### Stacktrace Representation diff --git a/model/logs/log-exception.yaml b/model/logs/log-exception.yaml index d0b251552a..ab20cb7250 100644 --- a/model/logs/log-exception.yaml +++ b/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" diff --git a/model/trace/trace-exception.yaml b/model/trace/trace-exception.yaml index 8de3abb818..32c53f4b30 100644 --- a/model/trace/trace-exception.yaml +++ b/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"