Define HTTP exception events

.chloggen/http-exception-events.yaml

@@ -0,0 +1,8 @@
+change_type: enhancement
+component: http
+note: Define `http.client.request.exception` and `http.server.request.exception` events for recording exceptions during HTTP operations
+issues: [3414]
+subtext: |
+  These domain-specific exception events provide a structured way to record
+  exceptions that occur during HTTP client requests (network failures, timeouts)
+  and HTTP server request processing (application errors, internal failures).

docs/http/README.md

@@ -40,6 +40,7 @@ Semantic conventions for HTTP are defined for the following signals:
 
 * [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*.
 * [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*.
+* [HTTP Exceptions](http-exceptions.md): Semantic Conventions for HTTP client and server *exceptions*.
 
 For help migrating from non-stable to stable conventions, see [the migration guide](../non-normative/http-migration.md).
 

docs/http/http-exceptions.md

@@ -0,0 +1,97 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Exceptions
+--->
+
+# Semantic conventions for HTTP exceptions
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for recording exceptions on HTTP operations.
+
+<!-- toc -->
+
+- [HTTP client request exception](#http-client-request-exception)
+- [HTTP server request exception](#http-server-request-exception)
+
+<!-- tocstop -->
+
+## HTTP client request exception
+
+<!-- semconv event.http.client.request.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 `http.client.request.exception`.
+
+This event represents an exception that occurred during an HTTP client request, such as network failures, timeouts, or other errors that prevent the request from completing successfully.
+
+This event SHOULD be recorded when an exception occurs during HTTP client operations.
+Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event.
+Some HTTP client frameworks generate artificial exceptions for non-successful HTTP status codes (e.g., 404 Not Found). When possible, instrumentations SHOULD NOT record these artificial exceptions, or SHOULD set the severity to DEBUG (severity number 5).
+Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP 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 -->
+
+## HTTP server request exception
+
+<!-- semconv event.http.server.request.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 `http.server.request.exception`.
+
+This event represents an exception that occurred during HTTP server request processing, such as application errors, internal failures, or other exceptions that prevent the server from successfully handling the request.
+
+This event SHOULD be recorded when an exception occurs during HTTP server request 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 HTTP 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/http/events.yaml

@@ -0,0 +1,52 @@
+groups:
+  - id: event.http.client.request.exception
+    name: http.client.request.exception
+    stability: development
+    type: event
+    brief: >
+      This event represents an exception that occurred during an HTTP client request,
+      such as network failures, timeouts, or other errors that prevent the request
+      from completing successfully.
+    note: >
+      This event SHOULD be recorded when an exception occurs during HTTP client operations.
+
+      Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event.
+
+      Some HTTP client frameworks generate artificial exceptions for non-successful HTTP status codes
+      (e.g., 404 Not Found). When possible, instrumentations SHOULD NOT record these artificial
+      exceptions, or SHOULD set the severity to DEBUG (severity number 5).
+
+      Instrumentations MAY provide a configuration option to populate exception events
+      with the attributes captured on the corresponding HTTP 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.http.server.request.exception
+    name: http.server.request.exception
+    stability: development
+    type: event
+    brief: >
+      This event represents an exception that occurred during HTTP server request processing,
+      such as application errors, internal failures, or other exceptions that prevent
+      the server from successfully handling the request.
+    note: >
+      This event SHOULD be recorded when an exception occurs during HTTP server request 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 HTTP 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