diff --git a/.chloggen/exception-events.yaml b/.chloggen/exception-events.yaml new file mode 100644 index 0000000000..7f25b93465 --- /dev/null +++ b/.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 diff --git a/docs/db/README.md b/docs/db/README.md index 46407c13bc..b1bae7599e 100644 --- a/docs/db/README.md +++ b/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: diff --git a/docs/db/database-exceptions.md b/docs/db/database-exceptions.md new file mode 100644 index 0000000000..0c479da454 --- /dev/null +++ b/docs/db/database-exceptions.md @@ -0,0 +1,56 @@ + + +# Semantic conventions for database exceptions + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for recording exceptions on database client operations. + + + +- [Database client operation exception](#database-client-operation-exception) + + + +## Database client operation exception + + + + + + +**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. + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 15056b2d81..3a410f8b66 100644 --- a/docs/rpc/README.md +++ b/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: diff --git a/docs/rpc/rpc-exceptions.md b/docs/rpc/rpc-exceptions.md new file mode 100644 index 0000000000..dd1350f9a1 --- /dev/null +++ b/docs/rpc/rpc-exceptions.md @@ -0,0 +1,96 @@ + + +# Semantic conventions for RPC exceptions + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for recording exceptions on RPC operations. + + + +- [RPC client call exception](#rpc-client-call-exception) +- [RPC server call exception](#rpc-server-call-exception) + + + +## RPC client call exception + + + + + + +**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. + + + + + +## RPC server call exception + + + + + + +**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. + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/db/events.yaml b/model/db/events.yaml new file mode 100644 index 0000000000..2dd533118e --- /dev/null +++ b/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 diff --git a/model/rpc/events.yaml b/model/rpc/events.yaml new file mode 100644 index 0000000000..edf295ddec --- /dev/null +++ b/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