diff --git a/.chloggen/messaging-exception-events.yaml b/.chloggen/messaging-exception-events.yaml new file mode 100644 index 0000000000..0753f6ae64 --- /dev/null +++ b/.chloggen/messaging-exception-events.yaml @@ -0,0 +1,12 @@ +change_type: enhancement +component: messaging +note: Define domain-specific exception events for messaging +issues: [3435] +subtext: | + These domain-specific exception events provide a structured way to record + exceptions that occur during messaging operations: + - `messaging.create.exception` for messaging create operations + - `messaging.send.exception` for messaging send operations + - `messaging.receive.exception` for messaging receive operations + - `messaging.settle.exception` for messaging settle operations + - `messaging.process.exception` for messaging process operations diff --git a/docs/messaging/README.md b/docs/messaging/README.md index 6c26629fac..4c16ff1ce1 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -40,6 +40,7 @@ Semantic conventions for messaging systems are defined for the following signals * [Messaging Spans](messaging-spans.md): Semantic Conventions for messaging *spans*. * [Messaging Metrics](messaging-metrics.md): Semantic Conventions for messaging *metrics*. +* [Messaging Exceptions](messaging-exceptions.md): Semantic Conventions for messaging *exceptions*. Technology specific semantic conventions are defined for the following messaging systems: diff --git a/docs/messaging/messaging-exceptions.md b/docs/messaging/messaging-exceptions.md new file mode 100644 index 0000000000..587917e461 --- /dev/null +++ b/docs/messaging/messaging-exceptions.md @@ -0,0 +1,216 @@ + + +# Semantic conventions for messaging exceptions + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for recording exceptions on messaging operations. + + + +- [Messaging create exception](#messaging-create-exception) +- [Messaging send exception](#messaging-send-exception) +- [Messaging receive exception](#messaging-receive-exception) +- [Messaging settle exception](#messaging-settle-exception) +- [Messaging process exception](#messaging-process-exception) + + + +## Messaging create exception + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `messaging.create.exception`. + +This event represents an exception that occurred during a messaging create operation. + +This event SHOULD be recorded when an exception occurs during a messaging create operation. +Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. +Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding messaging create span. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | +| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | 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` | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | 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)` | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.message`:** + +> [!WARNING] +> +> This attribute may contain sensitive information. + +**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + + + + +## Messaging send exception + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `messaging.send.exception`. + +This event represents an exception that occurred during a messaging send operation. + +This event SHOULD be recorded when an exception occurs during a messaging send operation. +Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. +Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding messaging send span. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | +| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | 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` | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | 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)` | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.message`:** + +> [!WARNING] +> +> This attribute may contain sensitive information. + +**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + + + + +## Messaging receive exception + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `messaging.receive.exception`. + +This event represents an exception that occurred during a messaging receive operation. + +This event SHOULD be recorded when an exception occurs during a messaging receive operation. +Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. +Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding messaging receive span. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | +| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | 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` | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | 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)` | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.message`:** + +> [!WARNING] +> +> This attribute may contain sensitive information. + +**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + + + + +## Messaging settle exception + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `messaging.settle.exception`. + +This event represents an exception that occurred during a messaging settle operation. + +This event SHOULD be recorded when an exception occurs during a messaging settle operation. +Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. +Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding messaging settle span. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | +| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | 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` | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | 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)` | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.message`:** + +> [!WARNING] +> +> This attribute may contain sensitive information. + +**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + + + + +## Messaging process exception + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `messaging.process.exception`. + +This event represents an exception that occurred during messaging process operations. + +This event SHOULD be recorded when an exception occurs during messaging process operations. +Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. +Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding messaging process span. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | +| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | 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` | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | 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)` | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.message`:** + +> [!WARNING] +> +> This attribute may contain sensitive information. + +**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/messaging/events.yaml b/model/messaging/events.yaml new file mode 100644 index 0000000000..93048ad51d --- /dev/null +++ b/model/messaging/events.yaml @@ -0,0 +1,110 @@ +groups: + - id: event.messaging.create.exception + name: messaging.create.exception + stability: development + type: event + brief: > + This event represents an exception that occurred during a messaging create operation. + note: > + This event SHOULD be recorded when an exception occurs during a messaging create operation. + + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + + Instrumentations MAY provide a configuration option to populate exception events + with the attributes captured on the corresponding messaging create 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 + + - id: event.messaging.send.exception + name: messaging.send.exception + stability: development + type: event + brief: > + This event represents an exception that occurred during a messaging send operation. + note: > + This event SHOULD be recorded when an exception occurs during a messaging send operation. + + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + + Instrumentations MAY provide a configuration option to populate exception events + with the attributes captured on the corresponding messaging send 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 + + - id: event.messaging.receive.exception + name: messaging.receive.exception + stability: development + type: event + brief: > + This event represents an exception that occurred during a messaging receive operation. + note: > + This event SHOULD be recorded when an exception occurs during a messaging receive operation. + + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + + Instrumentations MAY provide a configuration option to populate exception events + with the attributes captured on the corresponding messaging receive 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 + + - id: event.messaging.settle.exception + name: messaging.settle.exception + stability: development + type: event + brief: > + This event represents an exception that occurred during a messaging settle operation. + note: > + This event SHOULD be recorded when an exception occurs during a messaging settle operation. + + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + + Instrumentations MAY provide a configuration option to populate exception events + with the attributes captured on the corresponding messaging settle 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 + + - id: event.messaging.process.exception + name: messaging.process.exception + stability: development + type: event + brief: > + This event represents an exception that occurred during messaging process operations. + note: > + This event SHOULD be recorded when an exception occurs during messaging process operations. + + Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. + + Instrumentations MAY provide a configuration option to populate exception events + with the attributes captured on the corresponding messaging process 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