open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Introduce request error type attribute (#205) 

Co-authored-by: Joao Grassi <joao@joaograssi.com>
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
This commit is contained in:
Liudmila Molkova 2023-09-11 08:37:09 -07:00 committed by GitHub
parent 5f6558d259
commit 2bad9afad5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 367 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -65,6 +65,8 @@ release.
([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276))
- Add host cpu resource attributes. - Add host cpu resource attributes.
([#209](https://github.com/open-telemetry/semantic-conventions/pull/209)) ([#209](https://github.com/open-telemetry/semantic-conventions/pull/209))
- Introduce `error.type` attribute and use it in HTTP conventions
([#205](https://github.com/open-telemetry/semantic-conventions/pull/205))
- BREAKING: Change HTTP span name when method is unknown (use `HTTP` instead of `_OTHER`) - BREAKING: Change HTTP span name when method is unknown (use `HTTP` instead of `_OTHER`)
([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270))
- Moved RPC streaming notes from metric brief section to notes section. - Moved RPC streaming notes from metric brief section to notes section.

252
docs/http/http-metrics.md
View File

@ -77,18 +77,35 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended |
| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In |
| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In |
| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. **[2]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[3]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -103,9 +120,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[4]:** Determined by using the first of the following that applies **[5]:** Determined by using the first of the following that applies
- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
include host identifier. include host identifier.
@ -115,13 +132,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
**[5]:** Determined by using the first of the following that applies **[6]:** Determined by using the first of the following that applies
- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
if it's sent in absolute-form. if it's sent in absolute-form.
- Port identifier of the `Host` header - Port identifier of the `Host` header
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |
@ -224,18 +247,35 @@ This metric is optional.
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended |
| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In |
| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In |
| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. **[2]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[3]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -250,9 +290,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[4]:** Determined by using the first of the following that applies **[5]:** Determined by using the first of the following that applies
- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
include host identifier. include host identifier.
@ -262,13 +302,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
**[5]:** Determined by using the first of the following that applies **[6]:** Determined by using the first of the following that applies
- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
if it's sent in absolute-form. if it's sent in absolute-form.
- Port identifier of the `Host` header - Port identifier of the `Host` header
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |
@ -303,18 +349,35 @@ This metric is optional.
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended |
| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In |
| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In |
| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. **[2]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[3]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -329,9 +392,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[4]:** Determined by using the first of the following that applies **[5]:** Determined by using the first of the following that applies
- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
include host identifier. include host identifier.
@ -341,13 +404,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
**[5]:** Determined by using the first of the following that applies **[6]:** Determined by using the first of the following that applies
- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
if it's sent in absolute-form. if it's sent in absolute-form.
- Port identifier of the `Host` header - Port identifier of the `Host` header
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |
@ -387,15 +456,32 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
<!-- semconv metric.http.client.request.duration(full) --> <!-- semconv metric.http.client.request.duration(full) -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required |
| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] |
| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. **[1]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -410,9 +496,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[3]:** Determined by using the first of the following that applies **[4]:** Determined by using the first of the following that applies
- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
if it's sent in absolute-form if it's sent in absolute-form
@ -420,13 +506,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
SHOULD NOT be set if capturing it would require an extra DNS lookup. SHOULD NOT be set if capturing it would require an extra DNS lookup.
**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
**[5]:** If not default (`80` for `http` scheme, `443` for `https`). **[6]:** If not default (`80` for `http` scheme, `443` for `https`).
**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. **[7]:** When observed from the client side, this SHOULD represent the immediate server peer address.
When observed from the server side, this SHOULD represent the physical server address. When observed from the server side, this SHOULD represent the physical server address.
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |
@ -460,15 +552,32 @@ This metric is optional.
<!-- semconv metric.http.client.request.size(full) --> <!-- semconv metric.http.client.request.size(full) -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required |
| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] |
| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. **[1]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -483,9 +592,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[3]:** Determined by using the first of the following that applies **[4]:** Determined by using the first of the following that applies
- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
if it's sent in absolute-form if it's sent in absolute-form
@ -493,13 +602,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
SHOULD NOT be set if capturing it would require an extra DNS lookup. SHOULD NOT be set if capturing it would require an extra DNS lookup.
**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
**[5]:** If not default (`80` for `http` scheme, `443` for `https`). **[6]:** If not default (`80` for `http` scheme, `443` for `https`).
**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. **[7]:** When observed from the client side, this SHOULD represent the immediate server peer address.
When observed from the server side, this SHOULD represent the physical server address. When observed from the server side, this SHOULD represent the physical server address.
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |
@ -533,15 +648,32 @@ This metric is optional.
<!-- semconv metric.http.client.response.size(full) --> <!-- semconv metric.http.client.response.size(full) -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended |
| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required |
| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] |
| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. **[1]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -556,9 +688,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[3]:** Determined by using the first of the following that applies **[4]:** Determined by using the first of the following that applies
- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
if it's sent in absolute-form if it's sent in absolute-form
@ -566,13 +698,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
SHOULD NOT be set if capturing it would require an extra DNS lookup. SHOULD NOT be set if capturing it would require an extra DNS lookup.
**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
**[5]:** If not default (`80` for `http` scheme, `443` for `https`). **[6]:** If not default (`80` for `http` scheme, `443` for `https`).
**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. **[7]:** When observed from the client side, this SHOULD represent the immediate server peer address.
When observed from the server side, this SHOULD represent the physical server address. When observed from the server side, this SHOULD represent the physical server address.
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |

84
docs/http/http-spans.md
View File

@ -29,6 +29,9 @@ and various HTTP versions like 1.1, 2 and SPDY.
* [HTTP client retries examples](#http-client-retries-examples) * [HTTP client retries examples](#http-client-retries-examples)
* [HTTP client authorization retry examples](#http-client-authorization-retry-examples) * [HTTP client authorization retry examples](#http-client-authorization-retry-examples)
* [HTTP client redirects examples](#http-client-redirects-examples) * [HTTP client redirects examples](#http-client-redirects-examples)
* [HTTP client call: DNS error](#http-client-call-dns-error)
* [HTTP client call: Internal Server Error](#http-client-call-internal-server-error)
* [HTTP server call: connection dropped before response body was sent](#http-server-call-connection-dropped-before-response-body-was-sent)
<!-- tocstop --> <!-- tocstop -->
@ -98,6 +101,12 @@ failed to interpret, span status MUST be set to `Error`.
Don't set the span status description if the reason can be inferred from `http.response.status_code`. Don't set the span status description if the reason can be inferred from `http.response.status_code`.
HTTP request may fail if it was cancelled or an error occurred preventing
the client or server from sending/receiving the request/response fully.
When instrumentation detects such errors it MUST set span status to `Error`
and MUST set the `error.type` attribute.
## Common Attributes ## Common Attributes
The common attributes listed in this section apply to both HTTP clients and servers in addition to The common attributes listed in this section apply to both HTTP clients and servers in addition to
@ -111,16 +120,33 @@ sections below.
| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] | | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] |
| `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). |
| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2`; `3` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `1.0`; `1.1`; `2`; `3` | Recommended |
| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | | [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [5] |
| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended |
**[1]:** If and only if it's different than `http.request.method`. **[1]:** If and only if it's different than `http.request.method`.
**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. **[2]:** If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
**[3]:** HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
@ -135,14 +161,20 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[4]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). **[5]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`).
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* `http.request.method` * `http.request.method`
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description |
|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. |
`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
| Value | Description | | Value | Description |
@ -540,4 +572,44 @@ GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1)
--- server (SERVER, trace=t2, span=s2) --- server (SERVER, trace=t2, span=s2)
``` ```
### HTTP client call: DNS error
As an example, if a user requested `https://does-not-exist-123.com`, we may have the following span on the client side:
| Attribute name | Value |
| :------------------- | :-------------------------------------------------------|
| `http.request.method`| `"GET"` |
| `network.protocol.version` | `"1.1"` |
| `url.full` | `"https://does-not-exist-123.com"` |
| `server.address` | `"does-not-exist-123.com"` |
| `error.type` | `"java.net.UnknownHostException"` |
### HTTP client call: Internal Server Error
As an example, if a user requested `https://example.com` and server returned 500, we may have the following span on the client side:
| Attribute name | Value |
| :------------------- | :-------------------------------------------------------|
| `http.request.method`| `"GET"` |
| `network.protocol.version` | `"1.1"` |
| `url.full` | `"https://example.com"` |
| `server.address` | `"example.com"` |
| `http.response.status_code` | `500` |
| `error.type` | `"500"` |
### HTTP server call: connection dropped before response body was sent
As an example, if a user sent a `POST` request with a body to `https://example.com:8080/uploads/4`, we may see the following span on a server side:
Span name: `POST /uploads/:document_id`.
| Attribute name | Value |
| :------------------- | :---------------------------------------------- |
| `http.request.method`| `"GET"` |
| `url.path` | `"/uploads/4"` |
| `url.scheme` | `"https"` |
| `http.route` | `"/uploads/:document_id"` |
| `http.response.status_code` | `201` |
| `error.type` | `WebSocketDisconnect` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

31
model/error.yaml Normal file
View File

@ -0,0 +1,31 @@
groups:
- id: error
type: attribute_group
prefix: error
brief: >
This document defines the shared attributes used to
report an error.
attributes:
- id: type
brief: 'Describes a class of error the operation ended with.'
type:
allow_custom_values: true
members:
- id: other
value: "_OTHER"
brief: 'A fallback error value to be used when the instrumentation does not define a custom value for it.'
examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500']
note: |
The `error.type` SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes),
it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture
all errors, regardless of whether they are defined within the domain-specific set or not.

20
model/http-common.yaml
View File

@ -62,6 +62,26 @@ groups:
conditionally_required: If and only if one was received/sent. conditionally_required: If and only if one was received/sent.
brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
examples: [200] examples: [200]
- ref: error.type
requirement_level:
conditionally_required: If request has ended with an error.
examples: ['timeout', 'name_resolution_error', '500']
note: |
If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
- ref: network.protocol.name - ref: network.protocol.name
examples: ['http', 'spdy'] examples: ['http', 'spdy']
requirement_level: requirement_level:

40
model/metrics/http.yaml
View File

@ -31,6 +31,26 @@ groups:
if it's sent in absolute-form. if it's sent in absolute-form.
- Port identifier of the `Host` header - Port identifier of the `Host` header
# todo (lmolkova) build tools don't populate grandparent attributes # todo (lmolkova) build tools don't populate grandparent attributes
- ref: error.type
requirement_level:
conditionally_required: If request has ended with an error.
examples: ['timeout', 'name_resolution_error', '500']
note: |
If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
- ref: http.request.method - ref: http.request.method
- ref: http.response.status_code - ref: http.response.status_code
- ref: network.protocol.name - ref: network.protocol.name
@ -47,6 +67,26 @@ groups:
- ref: network.protocol.name - ref: network.protocol.name
- ref: network.protocol.version - ref: network.protocol.version
- ref: server.socket.address - ref: server.socket.address
- ref: error.type
requirement_level:
conditionally_required: If request has ended with an error.
examples: ['timeout', 'name_resolution_error', '500']
note: |
If the request fails with an error before response status code was sent or received,
`error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
`error.type` SHOULD be set to the string representation of the status code, an exception type (if thrown) or a component-specific error code.
The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low, but
telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time, when no
additional filters are applied.
If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
- id: metric.http.server.request.duration - id: metric.http.server.request.duration
type: metric type: metric