Define database and RPC exception events

.chloggen/exception-events.yaml

@@ -0,0 +1,9 @@
+change_type: enhancement
+component: db, rpc
+note: Define domain-specific exception events for database and RPC
+issues: [3426]
+subtext: |
+  These domain-specific exception events provide a structured way to record
+  exceptions that occur during operations in each area:
+  - `db.client.operation.exception` for database client operations
+  - `rpc.client.call.exception` and `rpc.server.call.exception` for RPC

docs/db/README.md

@@ -39,6 +39,7 @@ Semantic conventions for database operations are defined for the following signa
 
 * [DB Spans](database-spans.md): Semantic Conventions for database client *spans*.
 * [DB Metrics](database-metrics.md): Semantic Conventions for database operation *metrics*.
+* [DB Exceptions](database-exceptions.md): Semantic Conventions for database client *exceptions*.
 
 Technology specific semantic conventions are defined for the following databases:
 

docs/db/database-exceptions.md

@@ -0,0 +1,56 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Exceptions
+--->
+
+# Semantic conventions for database exceptions
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for recording exceptions on database client operations.
+
+<!-- toc -->
+
+- [Database client operation exception](#database-client-operation-exception)
+
+<!-- tocstop -->
+
+## Database client operation exception
+
+<!-- semconv event.db.client.operation.exception -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `db.client.operation.exception`.
+
+This event represents an exception that occurred during a database client operation, such as connection failures, query errors, timeouts, or other errors that prevent the operation from completing successfully.
+
+This event SHOULD be recorded when an exception occurs during database client operations.
+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 database client 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.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/rpc/README.md

@@ -38,6 +38,7 @@ Semantic conventions for RPC are defined for the following signals:
 
 * [RPC Spans](rpc-spans.md): Semantic Conventions for RPC client and server *spans*.
 * [RPC Metrics](rpc-metrics.md): Semantic Conventions for RPC *metrics*.
+* [RPC Exceptions](rpc-exceptions.md): Semantic Conventions for RPC client and server *exceptions*.
 
 Technology specific semantic conventions are defined for the following RPC systems:
 

docs/rpc/rpc-exceptions.md

@@ -0,0 +1,96 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Exceptions
+--->
+
+# Semantic conventions for RPC exceptions
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for recording exceptions on RPC operations.
+
+<!-- toc -->
+
+- [RPC client call exception](#rpc-client-call-exception)
+- [RPC server call exception](#rpc-server-call-exception)
+
+<!-- tocstop -->
+
+## RPC client call exception
+
+<!-- semconv event.rpc.client.call.exception -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `rpc.client.call.exception`.
+
+This event represents an exception that occurred during an outgoing RPC call, such as network failures, timeouts, serialization errors, or other errors that prevent the call from completing successfully.
+
+This event SHOULD be recorded when an exception occurs during RPC client call operations.
+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 RPC client 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.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## RPC server call exception
+
+<!-- semconv event.rpc.server.call.exception -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `rpc.server.call.exception`.
+
+This event represents an exception that occurred during incoming RPC call processing, such as application errors, internal failures, or other exceptions that prevent the server from successfully handling the call.
+
+This event SHOULD be recorded when an exception occurs during RPC server call processing.
+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 RPC server 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.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

model/db/events.yaml

@@ -0,0 +1,24 @@
+groups:
+  - id: event.db.client.operation.exception
+    name: db.client.operation.exception
+    stability: development
+    type: event
+    brief: >
+      This event represents an exception that occurred during a database client operation,
+      such as connection failures, query errors, timeouts, or other errors that prevent
+      the operation from completing successfully.
+    note: >
+      This event SHOULD be recorded when an exception occurs during database client operations.
+
+      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 database client 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

model/rpc/events.yaml

@@ -0,0 +1,48 @@
+groups:
+  - id: event.rpc.client.call.exception
+    name: rpc.client.call.exception
+    stability: development
+    type: event
+    brief: >
+      This event represents an exception that occurred during an outgoing RPC call,
+      such as network failures, timeouts, serialization errors, or other errors that
+      prevent the call from completing successfully.
+    note: >
+      This event SHOULD be recorded when an exception occurs during RPC client call operations.
+
+      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 RPC client 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.rpc.server.call.exception
+    name: rpc.server.call.exception
+    stability: development
+    type: event
+    brief: >
+      This event represents an exception that occurred during incoming RPC call processing,
+      such as application errors, internal failures, or other exceptions that prevent
+      the server from successfully handling the call.
+    note: >
+      This event SHOULD be recorded when an exception occurs during RPC server call processing.
+
+      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 RPC server 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