diff --git a/CHANGELOG.md b/CHANGELOG.md index 03487affb1f..eae4e4a5ff6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -122,6 +122,10 @@ release. ([#2436](https://github.com/open-telemetry/opentelemetry-specification/pull/2436)) - Add `rpc.system` value for Apache Dubbo. ([#2453](https://github.com/open-telemetry/opentelemetry-specification/pull/2453)) +- Note added that `net.peer.name` SHOULD NOT be set if capturing it would require an + extra reverse DNS lookup. And moved `net.peer.name` from common http attributes to + just client http attributes. + ([#2446](https://github.com/open-telemetry/opentelemetry-specification/pull/2446)) ### Compatibility diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index eb52b323bd9..b8274e3fdc4 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -47,6 +47,8 @@ groups: type: string brief: 'Remote hostname or similar, see note below.' examples: 'example.com' + note: > + `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. - id: host.ip type: string brief: 'Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host.' diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 85b9febb9f4..898eadc69c9 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -111,8 +111,6 @@ groups: required: conditional: If and only if a request was retried. examples: 3 - - ref: net.peer.name - sampling_relevant: true - ref: net.peer.ip sampling_relevant: true - ref: net.peer.port @@ -125,6 +123,9 @@ groups: extends: http span_kind: client brief: 'Semantic Convention for HTTP Client' + attributes: + - ref: net.peer.name + sampling_relevant: true constraints: - any_of: - [http.url] diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 02a45f84a75..f23ca38b7cf 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -64,7 +64,7 @@ or not they should be on the server, client or both. | [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | No, but recommended | | [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | No, but recommended | | [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | -| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | See below | +| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | See below | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote port number. | `80`; `8080`; `443` | See below | | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | See below | @@ -72,6 +72,8 @@ or not they should be on the server, client or both. **[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). +**[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. + **Additional attribute requirements:** At least one of the following sets of attributes is required: * [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 0f3817916bb..b1ae4e925f6 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -43,13 +43,15 @@ Some database systems may allow a connection to switch to a different `db.user`, | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | No | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | No | | [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below. | -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | See below. | -| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditional [1] | -| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [2] | +| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | See below. | +| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditional [2] | +| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [3] | -**[1]:** Required if using a port other than the default port for this DBMS. +**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[2]:** Recommended in general, required for in-process databases (`"inproc"`). +**[2]:** Required if using a port other than the default port for this DBMS. + +**[3]:** Recommended in general, required for in-process databases (`"inproc"`). **Additional attribute requirements:** At least one of the following sets of attributes is required: diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 16806a1a45e..099b8fc3833 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -75,7 +75,6 @@ Don't set the span status description if the reason can be inferred from `http.s | `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | If and only if a request was retried. | | [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No | -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | No | | [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | No | **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. @@ -102,7 +101,6 @@ Following attributes MUST be provided **at span creation time** (when provided a * `http.host` * `http.scheme` * [`net.peer.ip`](span-general.md) -* [`net.peer.name`](span-general.md) * [`net.peer.port`](span-general.md) @@ -146,6 +144,11 @@ If set, `http.url` must be the originally requested URL, before any HTTP-redirects that may happen when executing the request. +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | See below | + +**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. **Additional attribute requirements:** At least one of the following sets of attributes is required: @@ -153,6 +156,10 @@ before any HTTP-redirects that may happen when executing the request. * `http.scheme`, `http.host`, `http.target` * `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target` * `http.scheme`, [`net.peer.ip`](span-general.md), [`net.peer.port`](span-general.md), `http.target` + +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* [`net.peer.name`](span-general.md) Note that in some cases `http.host` might be different diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index b1b322aa9e3..b59eb3205cc 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -60,7 +60,7 @@ Examples of span names: | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | No, but recommended | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | No, but recommended | | [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | See below | +| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | See below | | [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | See below | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | See below | @@ -68,6 +68,8 @@ Examples of span names: **[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). +**[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. + **Additional attribute requirements:** At least one of the following sets of attributes is required: * [`net.peer.ip`](span-general.md) diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index df25818b207..03f99a23ca7 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -37,7 +37,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | No | | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No | | `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | No | -| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | No | +| `net.peer.name` | string | Remote hostname or similar, see note below. [1] | `example.com` | No | | `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | No | | `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | No | | `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | No | @@ -48,6 +48,8 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | No | | `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | No | +**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. + `net.transport` MUST be one of the following: | Value | Description | @@ -106,7 +108,8 @@ For `Unix` and `pipe`, since the connection goes over the file system instead of For IP-based communication, the name should be a DNS host name. For `net.peer.name`, this should be the name that was used to look up the IP address that was connected to (i.e., matching `net.peer.ip` if that one is set; e.g., `"example.com"` if connecting to an URL `https://example.com/foo`). -If only the IP address but no host name is available, reverse-lookup of the IP may optionally be used to obtain it. +If only the IP address but no host name is available, reverse DNS lookup SHOULD NOT be used to obtain `net.peer.name`, +and `net.peer.name` SHOULD NOT be set. `net.host.name` should be the host name of the local host, preferably the one that the peer used to connect for the current operation. If that is not known, a public hostname should be preferred over a private one. However, in that case it may be redundant with information already contained in resources and may be left out.