From 583719a20672a0a847315a2945648ca892f868aa Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 28 Feb 2023 07:52:04 -0800 Subject: [PATCH] Remove mention of net.transport from http semantic conventions (#3244) Based on @lmolkova's https://github.com/open-telemetry/opentelemetry-specification/issues/3215#issuecomment-1439068151 ## Changes Removes mention of `net.transport` from http semantic conventions. --------- Co-authored-by: Reiley Yang --- CHANGELOG.md | 2 + semantic_conventions/http-common.yaml | 3 - .../semantic_conventions/http-metrics.md | 84 ++++++++----------- .../trace/semantic_conventions/http.md | 16 ++-- 4 files changed, 45 insertions(+), 60 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 488693e42f9..d028945ff4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,8 @@ release. ([#3250](https://github.com/open-telemetry/opentelemetry-specification/pull/3250)) - Mark the attribute naming guidelines in the specification as stable. ([#3220](https://github.com/open-telemetry/opentelemetry-specification/pull/3220)) +- Remove mention of `net.transport` from HTTP semantic conventions + ([#3244](https://github.com/open-telemetry/opentelemetry-specification/pull/3244)) ### Compatibility diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index 8d1bf194494..8ca6b7b323d 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -40,9 +40,6 @@ groups: value: 'QUIC' brief: 'QUIC protocol.' brief: 'Kind of HTTP protocol used.' - note: > - If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` - is `QUIC`, in which case `IP.UDP` is assumed. - id: attributes.http.client prefix: http diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index be603a309fb..e69a78b6566 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -29,18 +29,16 @@ This metric is required. |---|---|---|---|---| | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `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.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.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. | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | **[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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. -**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -**[3]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -50,14 +48,14 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[3]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.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) if it's sent in absolute-form. - Port identifier of the `Host` header -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). `http.flavor` 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. @@ -125,18 +123,16 @@ This metric is optional. |---|---|---|---|---| | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `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.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.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. | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | **[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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. -**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -**[3]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -146,14 +142,14 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[3]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.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) if it's sent in absolute-form. - Port identifier of the `Host` header -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). `http.flavor` 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. @@ -182,18 +178,16 @@ This metric is optional. |---|---|---|---|---| | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `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.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.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. | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | **[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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. -**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -**[3]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -203,14 +197,14 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[3]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.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) if it's sent in absolute-form. - Port identifier of the `Host` header -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). `http.flavor` 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. @@ -239,16 +233,14 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.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. | -| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [1] | `example.com` | Required | +| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -**[2]:** Determined by using the first of the following that applies +**[1]:** 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) if it's sent in absolute-form @@ -256,9 +248,9 @@ This metric is required. SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[2]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[3]:** If not default (`80` for `http` scheme, `443` for `https`). `http.flavor` 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. @@ -285,16 +277,14 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.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. | -| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [1] | `example.com` | Required | +| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -**[2]:** Determined by using the first of the following that applies +**[1]:** 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) if it's sent in absolute-form @@ -302,9 +292,9 @@ This metric is optional. SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[2]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[3]:** If not default (`80` for `http` scheme, `443` for `https`). `http.flavor` 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. @@ -331,16 +321,14 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.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. | -| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [1] | `example.com` | Required | +| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -**[2]:** Determined by using the first of the following that applies +**[1]:** 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) if it's sent in absolute-form @@ -348,9 +336,9 @@ This metric is optional. SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[2]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[3]:** If not default (`80` for `http` scheme, `443` for `https`). `http.flavor` 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. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 8bfc9bbfb1d..2f8f850b3e0 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -66,23 +66,21 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.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.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended | | `http.user_agent` | 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 | | `http.request_content_length` | 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_content_length` | 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.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [2] | +| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [1] | | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [3] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [2] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [3] | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +**[1]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. -**[2]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. +**[2]:** If available and different from `net.peer.name` and if `net.sock.peer.addr` is set. -**[3]:** If available and different from `net.peer.name` and if `net.sock.peer.addr` is set. - -**[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. +**[3]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: