Skip to content

Commit 4ffee8f

Browse files
trasktrask
committed
Define HTTP exception events
1 parent 573ec5f commit 4ffee8f

4 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎.chloggen/http-exception-events.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
change_type: enhancement
2+
component: http
3+
note: Define `http.client.exception` and `http.server.exception` events for recording exceptions during HTTP operations
4+
issues: [3414]
5+
subtext: |
6+
These domain-specific exception events provide a structured way to record
7+
exceptions that occur during HTTP client requests (network failures, timeouts)
8+
and HTTP server request processing (application errors, internal failures).

‎docs/http/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ Semantic conventions for HTTP are defined for the following signals:
4040

4141
* [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*.
4242
* [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*.
43+
* [HTTP Exceptions](http-exceptions.md): Semantic Conventions for HTTP client and server *exceptions*.
4344

4445
For help migrating from non-stable to stable conventions, see [the migration guide](../non-normative/http-migration.md).
4546

‎docs/http/http-exceptions.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
linkTitle: Exceptions
3+
--->
4+
5+
# Semantic conventions for HTTP exceptions
6+
7+
**Status**: [Development][DocumentStatus]
8+
9+
This document defines semantic conventions for recording exceptions on HTTP operations.
10+
11+
<!-- toc -->
12+
13+
- [HTTP client exception](#http-client-exception)
14+
- [HTTP server exception](#http-server-exception)
15+
16+
<!-- tocstop -->
17+
18+
## HTTP client exception
19+
20+
The `http.client.exception` event represents an exception that occurred during
21+
an HTTP client request, such as network failures, timeouts, or other errors that
22+
prevent the request from completing successfully.
23+
24+
<!-- semconv event.http.client.exception -->
25+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
26+
<!-- see templates/registry/markdown/snippet.md.j2 -->
27+
<!-- prettier-ignore-start -->
28+
29+
**Status:** ![Development](https://img.shields.io/badge/-development-blue)
30+
31+
The event name MUST be `http.client.exception`.
32+
33+
This event represents an exception that occurred during an HTTP client request.
34+
35+
This event SHOULD be recorded when an exception occurs during HTTP client operations, such as network failures, timeouts, or other errors that prevent the request from completing successfully.
36+
37+
**Attributes:**
38+
39+
| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
40+
| --- | --- | --- | --- | --- | --- |
41+
| [`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` |
42+
| [`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` |
43+
| [`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)` |
44+
45+
**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
46+
47+
**[2] `exception.message`:**
48+
49+
> [!WARNING]
50+
>
51+
> This attribute may contain sensitive information.
52+
53+
**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
54+
55+
<!-- prettier-ignore-end -->
56+
<!-- END AUTOGENERATED TEXT -->
57+
<!-- endsemconv -->
58+
59+
## HTTP server exception
60+
61+
The `http.server.exception` event represents an exception that occurred during
62+
HTTP server request processing, such as application errors, internal failures, or
63+
other exceptions that prevent the server from successfully handling the request.
64+
65+
<!-- semconv event.http.server.exception -->
66+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
67+
<!-- see templates/registry/markdown/snippet.md.j2 -->
68+
<!-- prettier-ignore-start -->
69+
70+
**Status:** ![Development](https://img.shields.io/badge/-development-blue)
71+
72+
The event name MUST be `http.server.exception`.
73+
74+
This event represents an exception that occurred during HTTP server request processing.
75+
76+
This event SHOULD be recorded when an exception occurs during HTTP server request processing, such as application errors, internal failures, or other exceptions that prevent the server from successfully handling the request.
77+
78+
**Attributes:**
79+
80+
| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
81+
| --- | --- | --- | --- | --- | --- |
82+
| [`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` |
83+
| [`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` |
84+
| [`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)` |
85+
86+
**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
87+
88+
**[2] `exception.message`:**
89+
90+
> [!WARNING]
91+
>
92+
> This attribute may contain sensitive information.
93+
94+
**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
95+
96+
<!-- prettier-ignore-end -->
97+
<!-- END AUTOGENERATED TEXT -->
98+
<!-- endsemconv -->
99+
100+
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

‎model/http/events.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
groups:
2+
- id: event.http.client.exception
3+
name: http.client.exception
4+
stability: development
5+
type: event
6+
brief: >
7+
This event represents an exception that occurred during an HTTP client request.
8+
note: >
9+
This event SHOULD be recorded when an exception occurs during HTTP client operations,
10+
such as network failures, timeouts, or other errors that prevent the request
11+
from completing successfully.
12+
attributes:
13+
- ref: exception.type
14+
requirement_level:
15+
conditionally_required: Required if `exception.message` is not set, recommended otherwise.
16+
- ref: exception.message
17+
requirement_level:
18+
conditionally_required: Required if `exception.type` is not set, recommended otherwise.
19+
- ref: exception.stacktrace
20+
21+
- id: event.http.server.exception
22+
name: http.server.exception
23+
stability: development
24+
type: event
25+
brief: >
26+
This event represents an exception that occurred during HTTP server request processing.
27+
note: >
28+
This event SHOULD be recorded when an exception occurs during HTTP server request
29+
processing, such as application errors, internal failures, or other exceptions
30+
that prevent the server from successfully handling the request.
31+
attributes:
32+
- ref: exception.type
33+
requirement_level:
34+
conditionally_required: Required if `exception.message` is not set, recommended otherwise.
35+
- ref: exception.message
36+
requirement_level:
37+
conditionally_required: Required if `exception.type` is not set, recommended otherwise.
38+
- ref: exception.stacktrace

0 commit comments

Comments
 (0)