Move net.peer.name from http common to http client (open-telemetry#2446)

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
 

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.'

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]

specification/metrics/semantic_conventions/rpc.md

@@ -64,14 +64,16 @@ 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 |
 
 **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
 
 **[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)

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:
 

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:[email protected]/`. 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)
 <!-- endsemconv -->
 
@@ -146,13 +144,22 @@ If set, `http.url` must be the originally requested URL,
 before any HTTP-redirects that may happen when executing the request.
 
 <!-- semconv http.client -->
+| 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:
 
 * `http.url`
 * `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)
 <!-- endsemconv -->
 
 Note that in some cases `http.host` might be different

specification/trace/semantic_conventions/rpc.md

@@ -60,14 +60,16 @@ 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 |
 
 **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
 
 **[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)

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.