From 0b9c69e02f8fa87e3344084aa49bac6f81b509fa Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Oct 2023 17:37:36 -0700 Subject: [PATCH 1/5] Remove network.transport from http semconv --- CHANGELOG.md | 3 +++ docs/http/http-spans.md | 20 +------------------- model/trace/http.yaml | 3 --- 3 files changed, 4 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e7c4e4dcec..1cf7f9540c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ release. ## Unreleased +- Remove `network.protocol.name` from HTTP semconv. + ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402)) + ### Breaking ### Features diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index a127fde446..25c218c615 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -125,8 +125,7 @@ sections below. | [`http.response.status_code`](../attributes-registry/http.md) | 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. [6] | `http`; `spdy` | Recommended: if not default (`http`). | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `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). [8] | `tcp`; `udp` | Conditionally Required: [9] | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [10] | `ipv4`; `ipv6` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [8] | `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 | **[1]:** If the request fails with an error before response status code was sent or received, @@ -176,14 +175,6 @@ The attribute value MUST consist of either multiple header values as an array of **[8]:** The value SHOULD be normalized to lowercase. -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example -different processes could be listening on TCP port 12345 and UDP port 12345. - -**[9]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). - -**[10]:** The value SHOULD be normalized to lowercase. - Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * [`http.request.method`](../attributes-registry/http.md) @@ -209,15 +200,6 @@ Following attributes MUST be provided **at span creation time** (when provided a | `TRACE` | TRACE method. | | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | -`network.transport` 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 | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | -| `unix` | Unix domain socket | - `network.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 | diff --git a/model/trace/http.yaml b/model/trace/http.yaml index adb3534875..ecc01518d0 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -19,9 +19,6 @@ groups: - ref: http.request.method sampling_relevant: true requirement_level: required - - ref: network.transport - requirement_level: - conditionally_required: If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). - ref: network.type - ref: user_agent.original From 47ee62ad0ccab650511ad1a1a9a49dce5e699c39 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 16 Oct 2023 11:57:40 -0700 Subject: [PATCH 2/5] Include in table as opt-in --- docs/http/http-spans.md | 16 ++++++++++++++-- model/trace/http.yaml | 5 +++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 25c218c615..b26a3cfe3a 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -125,7 +125,8 @@ sections below. | [`http.response.status_code`](../attributes-registry/http.md) | 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. [6] | `http`; `spdy` | Recommended: if not default (`http`). | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [8] | `ipv4`; `ipv6` | 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). [8] | `tcp`; `udp` | Opt-In | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [9] | `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 | **[1]:** If the request fails with an error before response status code was sent or received, @@ -173,7 +174,9 @@ The attribute value MUST consist of either multiple header values as an array of **[7]:** `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`. -**[8]:** The value SHOULD be normalized to lowercase. +**[8]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. More obscure implementations are possible. + +**[9]:** The value SHOULD be normalized to lowercase. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: @@ -200,6 +203,15 @@ Following attributes MUST be provided **at span creation time** (when provided a | `TRACE` | TRACE method. | | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + `network.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 | diff --git a/model/trace/http.yaml b/model/trace/http.yaml index ecc01518d0..c35c175665 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -19,6 +19,11 @@ groups: - ref: http.request.method sampling_relevant: true requirement_level: required + - ref: network.transport + requirement_level: opt_in + note: > + Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. + More obscure implementations are possible. - ref: network.type - ref: user_agent.original From 2b95f4cfaf76b57c6feb645a5b9160855e58706e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 16 Oct 2023 12:03:38 -0700 Subject: [PATCH 3/5] Update change log --- CHANGELOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1cf7f9540c..1476e35d69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,15 +7,15 @@ release. ## Unreleased -- Remove `network.protocol.name` from HTTP semconv. - ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402)) - ### Breaking ### Features ### Fixes +- Change `network.transport` from recommended to opt-in in the HTTP semconv. + ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402)) + ## v1.22.0 (2023-10-12) - Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) From 5967570f3620d4d0092c7dee6c8f0899c9fa8e53 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 16 Oct 2023 12:04:33 -0700 Subject: [PATCH 4/5] Update wording --- docs/http/http-spans.md | 2 +- model/trace/http.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index b26a3cfe3a..e2f8309ad5 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -174,7 +174,7 @@ The attribute value MUST consist of either multiple header values as an array of **[7]:** `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`. -**[8]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. More obscure implementations are possible. +**[8]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. **[9]:** The value SHOULD be normalized to lowercase. diff --git a/model/trace/http.yaml b/model/trace/http.yaml index c35c175665..eb96ca2a71 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -23,7 +23,7 @@ groups: requirement_level: opt_in note: > Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. - More obscure implementations are possible. + Other obscure implementations are possible. - ref: network.type - ref: user_agent.original From da2839f3e44e20eded2d646082a810e58d847c13 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 16 Oct 2023 12:09:27 -0700 Subject: [PATCH 5/5] update --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b3ec24851c..3b7b4295ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ release. - BREAKING: Rename http.resend_count to http.request.resend_count. ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374)) -- BREAKING: Change `network.transport` from recommended to opt-in in the HTTP semconv. +- BREAKING: Change `network.transport` from recommended to opt-in in HTTP semconv. ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402)) ### Features