review: better description for sock

CHANGELOG.md

@@ -23,6 +23,9 @@ release.
   ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)).
 - Adopt attribute requirement levels in semantic conventions
   ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594))
+- BREAKING: rename `net.peer.ip` to `net.sock.peer.addr` and `net.host.ip` to `net.sock.host.addr`.
+  Define socket-level attributes and clarify logical peer and host attributes meaning.
+  ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594))
 
 ### Compatibility
 

schemas/1.11.0

@@ -2,12 +2,6 @@ file_format: 1.0.0
 schema_url: https://opentelemetry.io/schemas/1.11.0
 versions:
   1.11.0:
-    spans:
-      changes:
-        - rename_attributes:
-            attribute_map:
-              net.peer.ip: net.sock.peer.addr
-              net.host.ip: net.sock.host.addr
   1.10.0:
   1.9.0:
   1.8.0:

schemas/1.12.0

@@ -2,6 +2,12 @@ file_format: 1.0.0
 schema_url: https://opentelemetry.io/schemas/1.12.0
 versions:
   1.12.0:
+    spans:
+      changes:
+        - rename_attributes:
+            attribute_map:
+              net.peer.ip: net.sock.peer.addr
+              net.host.ip: net.sock.host.addr
   1.11.0:
   1.10.0:
   1.9.0:

semantic_conventions/trace/database.yaml

@@ -218,23 +218,24 @@ groups:
         requirement_level:
           conditionally_required: See alternative attributes below.
         brief: >
-          Database hostname.
+          Name of the database host.
       - ref: net.peer.port
         tag: connection-level
         requirement_level:
           conditionally_required: If using a port other than the default port for this DBMS.
       - ref: net.sock.peer.addr
         tag: connection-level
-        requirement_level:
-          conditionally_required: See alternative attributes below.
       - ref: net.sock.peer.port
-        tag: connection-level
         requirement_level:
-          conditionally_required: if using a port other than the default port for this DBMS.
+          recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set.
+        tag: connection-level
       - ref: net.sock.family
         tag: connection-level
         requirement_level:
-          conditionally_required: if applicable and if `net.sock.peer.addr` is set.
+          conditionally_required: If and only if `net.sock.peer.addr` is set.
+      - ref: net.sock.peer.name
+        requirement_level:
+          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
       - ref: net.transport
         tag: connection-level
         requirement_level:

semantic_conventions/trace/general.yaml

@@ -47,24 +47,17 @@ groups:
         examples: '127.0.0.1'
       - id: sock.peer.name
         type: string
-        brief: >
-          Remote socket peer name.
+        brief: Remote socket peer name.
         examples: proxy.example.com
       - id: sock.peer.addr
         type: string
         brief: >
           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)).
-        note: >
-          Can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html)
-          or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername)
-          with format specific to protocol address family.
         examples: ['127.0.0.1', '/tmp/mysql.sock' ]
       - id: sock.peer.port
         type: int
-        requirement_level: 
-          conditionally_required: if `net.sock.peer.addr` is set and `net.sock.family` has a notion of port
-        brief: 'Remote socket peer port (if defined for the address family).'
+        brief: Remote socket peer port (if defined for the address family).
         examples: 16456
       - id: sock.family
         type:
@@ -79,7 +72,7 @@ groups:
             - id: unix
               value: 'AF_UNIX'
               brief: "Unix domain socket path/"
-        requirement_level: 
+        requirement_level:
           conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set
         brief: >
           Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication.
@@ -104,16 +97,10 @@ groups:
         examples: 8080
       - id: sock.host.addr
         type: string
-        brief: 'Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host.'
-        note: >
-          Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html)
-          or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname)
-          with format specific to protocol address family.
+        brief: Local socket address. Useful in case of a multi-IP host.'
         examples: '192.168.0.1'
       - id: sock.host.port
         type: int
-        requirement_level:
-          conditionally_required: if `net.sock.host.addr` is set and `net.sock.family` has a notion of port
         brief: 'Local socket peer port (if defined for the address family).'
         examples: 35555
       - id: host.connection.type

semantic_conventions/trace/http.yaml

@@ -116,9 +116,15 @@ groups:
         examples: 3
       - ref: net.sock.peer.addr
       - ref: net.sock.peer.port
+        requirement_level:
+          recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set.
+      - ref: net.sock.peer.name
+        requirement_level:
+          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
       - ref: net.sock.family
         requirement_level:
-          conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set
+          conditionally_required: If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set.
+
     constraints:
       - include: network
 

semantic_conventions/trace/messaging.yaml

@@ -74,12 +74,19 @@ groups:
           conditionally_required: If available.
       - ref: net.sock.peer.addr
         tag: connection-level
-        requirement_level:
-          conditionally_required: If available.
       - ref: net.sock.peer.port
+        requirement_level:
+          recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set.
         tag: connection-level
       - ref: net.sock.family
         tag: connection-level
+        requirement_level:
+          conditionally_required: If and only if `net.sock.peer.addr` is set.
+      - ref: net.sock.peer.name
+        tag: connection-level
+        requirement_level:
+          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
+
     constraints:
       - include: network
 

semantic_conventions/trace/rpc.yaml

@@ -47,7 +47,14 @@ groups:
         examples: "exampleMethod"
       - ref: net.sock.peer.addr
       - ref: net.sock.peer.port
+        requirement_level:
+          recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set.
       - ref: net.sock.family
+        requirement_level:
+          conditionally_required: If and only if `net.sock.peer.addr` is set.
+      - ref: net.sock.peer.name
+        requirement_level:
+          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
       - ref: net.peer.name
         requirement_level: required
         brief: >
@@ -59,13 +66,12 @@ groups:
       - ref: net.peer.port
         requirement_level:
           conditionally_required: See below
-        brief: >
-          RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html)
       - ref: net.transport
         requirement_level:
           conditionally_required: See below
     constraints:
       - any_of:
+          - net.sock.peer.addr
           - net.peer.name
       - include: network
 
@@ -78,7 +84,11 @@ groups:
       - ref: net.host.name
       - ref: net.sock.host.addr
       - ref: net.sock.host.port
+        requirement_level:
+          recommended: If different than `net.host.port` and if `net.sock.host.addr` is set.
       - ref: net.sock.family
+        requirement_level:
+          conditionally_required: If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set.
 
   - id: rpc.grpc
     prefix: rpc.grpc

specification/metrics/semantic_conventions/rpc.md

@@ -64,11 +64,12 @@ 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` | 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` | Recommended |
 | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
-| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) | `80`; `8080`; `443` | Conditionally Required: See below |
-| [`net.sock.family`](../../trace/semantic_conventions/span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | Recommended |
+| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: See below |
+| [`net.sock.family`](../../trace/semantic_conventions/span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | Conditionally Required: If and only if `net.sock.peer.addr` is set. |
 | [`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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended |
-| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended |
+ [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | See below |
+| [`net.sock.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] |
+| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] |
 | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: 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).
@@ -77,10 +78,13 @@ or not they should be on the server, client or both.
 
 **[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.peer.name` to the IP address provided in the host component.
 
-**[4]:** Can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername) with format specific to protocol address family.
+**[4]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set.
+
+**[5]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
+* [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md)
 * [`net.peer.name`](../../trace/semantic_conventions/span-general.md)
 
 `rpc.system` 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.

specification/trace/semantic_conventions/database.md

@@ -42,23 +42,21 @@ Some database systems may allow a connection to switch to a different `db.user`,
 | `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
 | `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;` | Recommended |
 | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
-| [`net.peer.name`](span-general.md) | string | Database hostname. [1] | `example.com` | Conditionally Required: See alternative attributes below. |
+| [`net.peer.name`](span-general.md) | string | Name of the database host. [1] | `example.com` | Conditionally Required: See alternative attributes below. |
 | [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | 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. | `AF_INET`; `AF_BLUETOOTH` | Conditionally Required: if applicable and if `net.sock.peer.addr` is set. |
+| [`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. | `AF_INET`; `AF_BLUETOOTH` | Conditionally Required: If and only if `net.sock.peer.addr` is set. |
 | [`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)). [3] | `127.0.0.1`; `/tmp/mysql.sock` | Conditionally Required: See alternative attributes below. |
-| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditionally Required: [4] |
-| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [5] |
+ [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | See below |
+| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [3] |
+| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [4] |
 
 **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.
 
 **[2]:** If using a port other than the default port for this DBMS.
 
-**[3]:** Can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername) with format specific to protocol address family.
+**[3]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set.
 
-**[4]:** if using a port other than the default port for this DBMS.
-
-**[5]:** If database type is in-process (`"inproc"`), recommended for other database types.
+**[4]:** If database type is in-process (`"inproc"`), recommended for other database types.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
@@ -223,7 +221,7 @@ Separated for clarity.
 | `db.connection_string`  | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` |
 | `db.user`               | `"billing_user"` |
 | `net.peer.name`         | `"shopdb.example.com"` |
-| `net.sock.peer.addr`           | `"192.0.2.12"` |
+| `net.sock.peer.addr`    | `"192.0.2.12"` |
 | `net.peer.port`         | `3306` |
 | `net.transport`         | `"IP.TCP"` |
 | `db.name`               | `"ShopDb"` |
@@ -258,7 +256,7 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an
 | `db.connection_string`  | not set |
 | `db.user`               | `"the_user"` |
 | `net.peer.name`         | `"mongodb0.example.com"` |
-| `net.sock.peer.addr`           | `"192.0.2.14"` |
+| `net.sock.peer.addr`    | `"192.0.2.14"` |
 | `net.peer.port`         | `27017` |
 | `net.transport`         | `"IP.TCP"` |
 | `db.name`               | `"shopDb"` |