From 7ad3ac37747b8dd1dade14dcbf7e1528039ea58e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 2 Mar 2023 14:01:52 -0800 Subject: [PATCH] Make net.sock.host.port conditionally required (#3246) --- CHANGELOG.md | 2 ++ semantic_conventions/trace/general.yaml | 2 +- specification/trace/semantic_conventions/http.md | 4 ++-- specification/trace/semantic_conventions/rpc.md | 4 ++-- specification/trace/semantic_conventions/span-general.md | 4 ++-- 5 files changed, 9 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ede43e10af2..ace1f31c4c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,6 +46,8 @@ release. ([#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)) +- Mark `net.sock.host.port` as conditionally required. + ([#3246](https://github.com/open-telemetry/opentelemetry-specification/pull/3246)) ### Compatibility diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index 54403442946..a8a4dbe77c8 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -106,7 +106,7 @@ groups: type: int brief: 'Local socket port number.' requirement_level: - recommended: If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. + conditionally_required: If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. In other cases, it is still recommended to set this. examples: 35555 - id: host.connection.type type: diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 6d7a82671d9..a3a22b98c73 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -249,7 +249,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Opt-In | -| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] | +| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Conditionally Required: [6] | **[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. @@ -285,7 +285,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. +**[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. In other cases, it is still recommended to set this. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 28c080294a7..f5d6e823457 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -127,11 +127,11 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | [`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. | `inet6`; `bluetooth` | Conditionally Required: [1] | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended | -| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [2] | +| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Conditionally Required: [2] | **[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 defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. +**[2]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. In other cases, it is still recommended to set this. ### Events diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index b0091f667b9..95fa45ff46b 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -52,7 +52,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended | | `net.sock.host.addr` | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended | -| `net.sock.host.port` | int | Local socket port number. | `35555` | Recommended: [6] | +| `net.sock.host.port` | int | Local socket port number. | `35555` | Conditionally Required: [6] | | `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended | | `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | | `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | @@ -70,7 +70,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. +**[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. In other cases, it is still recommended to set this. `net.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.