diff --git a/.chloggen/http-exception-events.yaml b/.chloggen/http-exception-events.yaml new file mode 100644 index 0000000000..c6eb1c368d --- /dev/null +++ b/.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). diff --git a/docs/http/README.md b/docs/http/README.md index b493cb348f..53a2d679d0 100644 --- a/docs/http/README.md +++ b/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). diff --git a/docs/http/http-exceptions.md b/docs/http/http-exceptions.md new file mode 100644 index 0000000000..ed832fe956 --- /dev/null +++ b/docs/http/http-exceptions.md @@ -0,0 +1,97 @@ + + +# Semantic conventions for HTTP exceptions + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for recording exceptions on HTTP operations. + + + +- [HTTP client request exception](#http-client-request-exception) +- [HTTP server request exception](#http-server-request-exception) + + + +## HTTP client request exception + + + + + + +**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. + + + + + +## HTTP server request exception + + + + + + +**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. + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/http/events.yaml b/model/http/events.yaml new file mode 100644 index 0000000000..de4368c641 --- /dev/null +++ b/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