Define net.sock attributes and clarify logical net.peer|host.name attributes (#2614)

.vscode/settings.json

@@ -10,7 +10,7 @@
         "MD040": false,
     },
     "yaml.schemas": {
-        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.12.0/semantic-conventions/semconv.schema.json": [
+        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.12.1/semantic-conventions/semconv.schema.json": [
             "semantic_conventions/**/*.yaml"
         ]
     },

Makefile

@@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
 
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
 # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
-SEMCONVGEN_VERSION=0.12.0
+SEMCONVGEN_VERSION=0.12.1
 
 # TODO: add `yamllint` step to `all` after making sure it works on Mac.
 .PHONY: all

internal/tools/schema_check.sh

@@ -6,7 +6,7 @@
 
 set -e
 
-BUILD_TOOL_SCHEMAS_VERSION=0.12.0
+BUILD_TOOL_SCHEMAS_VERSION=0.12.1
 
 # List of vesions that do not require or have a schema.
 declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.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/README.md

@@ -17,12 +17,12 @@ i.e.:
 Semantic conventions for the spec MUST adhere to the
 [attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions.
 
-Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions/syntax.md)
+Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.12.1/semantic-conventions/syntax.md)
 for how to write the YAML files for semantic conventions and what the YAML properties mean.
 
 A schema file for VS code is configured in the `/.vscode/settings.json` of this
 repository, enabling auto-completion and additional checks. Refer to
-[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions/README.md) for what extension you need.
+[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.12.1/semantic-conventions/README.md) for what extension you need.
 
 ## Generating markdown
 
@@ -33,7 +33,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run
 make table-generation
 ```
 
-For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions)
+For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.12.1/semantic-conventions)
 in the OpenTelemetry build tools repository.
 Using this build tool, it is also possible to generate code for use in OpenTelemetry
 language projects.

semantic_conventions/trace/database.yaml

@@ -217,14 +217,21 @@ groups:
         tag: connection-level
         requirement_level:
           conditionally_required: See alternative attributes below.
-      - ref: net.peer.ip
+        brief: >
-        tag: connection-level
+          Name of the database host.
-        requirement_level:
-          conditionally_required: See alternative attributes below.
       - ref: net.peer.port
         tag: connection-level
         requirement_level:
-          conditionally_required: If using a port other than the default port for this DBMS.
+          conditionally_required: If using a port other than the default port for this DBMS and if `net.peer.name` is set.
+      - ref: net.sock.peer.addr
+        tag: connection-level
+      - ref: net.sock.peer.port
+        tag: connection-level
+      - ref: net.sock.family
+        tag: connection-level
+      - 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:
@@ -232,7 +239,7 @@ groups:
     constraints:
       - any_of:
           - 'net.peer.name'
-          - 'net.peer.ip'
+          - 'net.sock.peer.addr'
 
   - id: db.mssql
     prefix: db.mssql

semantic_conventions/trace/general.yaml

@@ -6,18 +6,12 @@ groups:
     attributes:
       - id: transport
         type:
-          allow_custom_values: false
+          allow_custom_values: true
           members:
             - id: ip_tcp
               value: "ip_tcp"
             - id: ip_udp
               value: "ip_udp"
-            - id: ip
-              value: "ip"
-              brief: 'Another IP-based protocol'
-            - id: unix
-              value: "unix"
-              brief: 'Unix Domain socket. See below.'
             - id: pipe
               value: "pipe"
               brief: 'Named or anonymous pipe. See note below.'
@@ -45,34 +39,74 @@ groups:
           `net.app.protocol.version` refers to the version of the protocol used and might be
           different from the protocol client's version. If the HTTP client used has a version
           of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
-      - id: peer.ip
+      - id: sock.peer.name
+        type: string
+        brief: Remote socket peer name.
+        requirement_level:
+          recommended: If available and different than `net.peer.name` and if `net.sock.peer.addr` is set.
+        examples: proxy.example.com
+      - id: sock.peer.addr
         type: string
         brief: >
-          Remote address of the peer (dotted decimal for IPv4 or
+          Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication,
-          [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6)
+          [etc](https://man7.org/linux/man-pages/man7/address_families.7.html).
-        examples: '127.0.0.1'
+        examples: ['127.0.0.1', '/tmp/mysql.sock' ]
-      - id: peer.port
+      - id: sock.peer.port
         type: int
-        brief: 'Remote port number.'
+        brief: Remote socket peer port.
-        examples: [80, 8080, 443]
+        requirement_level:
+          recommended: If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set.
+        examples: 16456
+      - id: sock.family
+        type:
+          allow_custom_values: true
+          members:
+            - id: inet
+              value: 'inet'
+              brief: "IPv4 address"
+            - id: inet6
+              value: 'inet6'
+              brief: "IPv6 address"
+            - id: unix
+              value: 'unix'
+              brief: "Unix domain socket path"
+        requirement_level:
+          conditionally_required: >
+            If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set.
+            Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr`
+            without `net.sock.family` coming from instrumentations that follow previous versions
+            of this document.
+        brief: >
+          Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication.
+        examples: ['inet6', 'bluetooth']
       - id: peer.name
         type: string
-        brief: 'Remote hostname or similar, see note below.'
+        brief: 'Logical remote hostname, 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
+      - id: peer.port
-        type: string
-        brief: 'Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host.'
-        examples: '192.168.0.1'
-      - id: host.port
         type: int
-        brief: 'Like `net.peer.port` but for the host port.'
+        brief: 'Logical remote port number'
-        examples: 35555
+        examples: [80, 8080, 443]
       - id: host.name
         type: string
-        brief: 'Local hostname or similar, see note below.'
+        brief: 'Logical local hostname or similar, see note below.'
         examples: 'localhost'
+      - id: host.port
+        type: int
+        brief: 'Logical local port number, preferably the one that the peer used to connect'
+        examples: 8080
+      - id: sock.host.addr
+        type: string
+        brief: Local socket address. Useful in case of a multi-IP host.'
+        examples: '192.168.0.1'
+      - id: sock.host.port
+        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.
+        examples: 35555
       - id: host.connection.type
         type:
           allow_custom_values: true

semantic_conventions/trace/http.yaml

@@ -114,10 +114,11 @@ groups:
         requirement_level:
           recommended: If and only if a request was retried.
         examples: 3
-      - ref: net.peer.ip
+      - ref: net.sock.peer.addr
-        sampling_relevant: true
+      - ref: net.sock.peer.port
-      - ref: net.peer.port
+      - ref: net.sock.peer.name
-        sampling_relevant: true
+      - ref: net.sock.family
+
     constraints:
       - include: network
 
@@ -129,13 +130,29 @@ groups:
     attributes:
       - ref: net.peer.name
         sampling_relevant: true
+        brief: >
+          Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
+        note: >
+          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 provided host component.
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match
+          URI host component, otherwise `Host` header host component SHOULD be used.
+      - ref: net.peer.port
+        sampling_relevant: true
+        requirement_level:
+          conditionally_required: if not default for request scheme.
+        brief: >
+          Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
+        note: >
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match
+          URI port component, otherwise it MUST match `Host` header port component.
+
     constraints:
       - any_of:
           - [http.url]
           - [http.scheme, http.host, http.target]
           - [http.scheme, net.peer.name, net.peer.port, http.target]
-          - [http.scheme, net.peer.ip, net.peer.port, http.target]
+          - [http.scheme, net.sock.peer.addr, net.sock.peer.port, http.target]
-
   - id: http.server
     prefix: http
     extends: http
@@ -163,18 +180,36 @@ groups:
             The IP address of the original client behind all proxies, if
             known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)).
         note: |
-            This is not necessarily the same as `net.peer.ip`, which would
+            This is not necessarily the same as `net.sock.peer.addr`, which would
             identify the network-level peer, which may be a proxy.
 
             This attribute should be set when a source of information different
-            from the one used for `net.peer.ip`, is available even if that other
+            from the one used for `net.sock.peer.addr`, is available even if that other
-            source just confirms the same value as `net.peer.ip`.
+            source just confirms the same value as `net.sock.peer.addr`.
-            Rationale: For `net.peer.ip`, one typically does not know if it
+            Rationale: For `net.sock.peer.addr`, one typically does not know if it
             comes from a proxy, reverse proxy, or the actual client. Setting
-            `http.client_ip` when it's the same as `net.peer.ip` means that
+            `http.client_ip` when it's the same as `net.sock.peer.addr` means that
             one is at least somewhat confident that the address is not that of
             the closest proxy.
         examples: '83.164.160.102'
+      - ref: net.host.name
+        sampling_relevant: true
+        brief: >
+          Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
+        note: >
+          When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set
+          `net.host.name` to the IP address provided in the host component.
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match
+          URI host component, otherwise `Host` header host component SHOULD be used.
+      - ref: net.host.port
+        sampling_relevant: true
+        brief: >
+          Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
+        note: >
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match
+          URI port component, otherwise `Host` header port component SHOULD be used.
+      - ref: net.sock.host.addr
+      - ref: net.sock.host.port
     constraints:
       - any_of:
           - [http.scheme, http.host, http.target]

semantic_conventions/trace/messaging.yaml

@@ -72,10 +72,17 @@ groups:
           This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
         requirement_level:
           conditionally_required: If available.
-      - ref: net.peer.ip
+      - ref: net.sock.peer.addr
+        tag: connection-level
+      - ref: net.sock.peer.port
+        tag: connection-level
+      - ref: net.sock.family
+        tag: connection-level
+      - ref: net.sock.peer.name
         tag: connection-level
         requirement_level:
-          conditionally_required: If available.
+          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
+
     constraints:
       - include: network
 

semantic_conventions/trace/rpc.yaml

@@ -45,8 +45,24 @@ groups:
           (e.g., method actually executing the call on the server side,
           RPC client stub method on the client side).
         examples: "exampleMethod"
-      - ref: net.peer.ip
+      - 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: >
+          RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html).
+        note: >
+          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.
       - ref: net.peer.port
         requirement_level:
           conditionally_required: See below
@@ -55,7 +71,7 @@ groups:
           conditionally_required: See below
     constraints:
       - any_of:
-          - net.peer.ip
+          - net.sock.peer.addr
           - net.peer.name
       - include: network
 
@@ -66,7 +82,9 @@ groups:
     brief: 'Semantic Convention for RPC server spans'
     attributes:
       - ref: net.host.name
-      - ref: net.host.ip
+      - ref: net.sock.host.addr
+      - ref: net.sock.host.port
+      - ref: net.sock.family
 
   - id: rpc.grpc
     prefix: rpc.grpc

specification/metrics/semantic_conventions/http-metrics.md

@@ -52,7 +52,7 @@ and whether they should be on server, client, or both types of HTTP metric event
 | `http.flavor`      | `client` & `server` | Recommended                                                  | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`.                                                                                                                                          |
 | `net.peer.name`    | `client`            | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
 | `net.peer.port`    | `client`            | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
-| `net.peer.ip`      | `client`            | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
+| `net.sock.peer.addr`      | `client`            | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
 | `http.server_name` | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). |
 | `net.host.name`    | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
 | `net.host.port`    | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
@@ -101,7 +101,7 @@ path.
 * `http.url`
 * `http.scheme`, `http.host`, `http.target`
 * `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target`
-* `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target`
+* `http.scheme`, `net.sock.peer.addr`, `net.sock.peer.port`, `http.target`
 
 **[2]** For server metric attributes, `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. <https://github.com/open-telemetry/opentelemetry-python/pull/148>).
 It is thus preferred to supply the raw data that _is_ available.

specification/metrics/semantic_conventions/rpc.md

@@ -69,20 +69,27 @@ measurements.
 | [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
 | [`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.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 | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
-| [`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 | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: See below |
-| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | 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. | `inet6`; `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). | `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. | `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).
 
 **[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.
+**[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]:** 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.peer.ip`](../../trace/semantic_conventions/span-general.md)
+* [`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.
@@ -96,7 +103,7 @@ measurements.
 <!-- endsemconv -->
 
 To avoid high cardinality, implementations should prefer the most stable of `net.peer.name` or
-`net.peer.ip`, depending on expected deployment profile.  For many cloud applications, this is likely
+`net.sock.peer.addr`, depending on expected deployment profile.  For many cloud applications, this is likely
 `net.peer.name` as names can be recycled even across re-instantiation of a server with a different `ip`.
 
 For client-side metrics `net.peer.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).

specification/trace/semantic_conventions/database.md

@@ -42,21 +42,27 @@ 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.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` | 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.name`](span-general.md) | string | Remote hostname or similar, see note below. [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.peer.port`](span-general.md) | int | 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. | `inet6`; `bluetooth` | Conditionally Required: [3] |
-| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [3] |
+| [`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` | See below |
+| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] |
+| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [5] |
 
 **[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.
+**[2]:** If using a port other than the default port for this DBMS and if `net.peer.name` is set.
 
-**[3]:** If database type is in-process (`"inproc"`), recommended for other database types.
+**[3]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document.
+
+**[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set.
+
+**[5]:** 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:
 
 * [`net.peer.name`](span-general.md)
-* [`net.peer.ip`](span-general.md)
+* [`net.sock.peer.addr`](span-general.md)
 
 `db.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.
 
@@ -216,7 +222,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.peer.ip`           | `"192.0.2.12"` |
+| `net.sock.peer.addr`    | `"192.0.2.12"` |
 | `net.peer.port`         | `3306` |
 | `net.transport`         | `"IP.TCP"` |
 | `db.name`               | `"ShopDb"` |
@@ -226,7 +232,7 @@ Separated for clarity.
 
 ### Redis
 
-In this example, Redis is connected using a unix domain socket and therefore the connection string and `net.peer.ip` are left out.
+In this example, Redis is connected using a unix domain socket and therefore the connection string and `net.sock.peer.addr` are left out.
 Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead.
 
 | Key | Value |
@@ -251,7 +257,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.peer.ip`           | `"192.0.2.14"` |
+| `net.sock.peer.addr`    | `"192.0.2.14"` |
 | `net.peer.port`         | `27017` |
 | `net.transport`         | `"IP.TCP"` |
 | `db.name`               | `"shopDb"` |

specification/trace/semantic_conventions/http.md

@@ -74,8 +74,10 @@ Don't set the span status description if the reason can be inferred from `http.s
 | `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://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
 | `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` | Recommended |
 | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: 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` | 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: [4] |
-| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Recommended |
+| [`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: [5] |
+| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] |
 
 **[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/`.
 
@@ -83,6 +85,12 @@ Don't set the span status description if the reason can be inferred from `http.s
 
 **[3]:** 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.
 
+**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document.
+
+**[5]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set.
+
+**[6]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set.
+
 `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.
 
 | Value  | Description |
@@ -101,11 +109,9 @@ Following attributes MUST be provided **at span creation time** (when provided a
 * `http.target`
 * `http.host`
 * `http.scheme`
-* [`net.peer.ip`](span-general.md)
-* [`net.peer.port`](span-general.md)
 <!-- endsemconv -->
 
-It is recommended to also use the general [network attributes][], especially `net.peer.ip`. 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.
+It is recommended to also use the general [socket-level attributes][] - `net.sock.peer.addr` when available,  `net.sock.peer.name` and `net.sock.peer.port` when don't match `net.peer.name` and `net.peer.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected).
 
 ### HTTP request and response headers
 
@@ -122,7 +128,7 @@ Users MAY explicitly configure instrumentations to capture them even though it i
 
 **[2]:** The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
 
-[network attributes]: span-general.md#general-network-connection-attributes
+[socket-level attributes]: span-general.md#netsock-attributes
 
 ### HTTP request retries and redirects
 
@@ -147,25 +153,31 @@ before any HTTP-redirects that may happen when executing the request.
 <!-- semconv http.client -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | See below |
+| [`net.peer.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [1] | `example.com` | See below |
+| [`net.peer.port`](span-general.md) | int | Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [2] | `80`; `8080`; `443` | Conditionally Required: if not default for request scheme. |
 
-**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.
+**[1]:** 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 provided host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used.
+
+**[2]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port component, otherwise it MUST match `Host` header port component.
 
 **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`
+* `http.scheme`, [`net.sock.peer.addr`](span-general.md), [`net.sock.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)
+* [`net.peer.port`](span-general.md)
 <!-- endsemconv -->
 
+It is recommended to also use the general [socket-level attributes][] - `net.sock.host.addr` when available, `net.sock.host.port` when it doesn't match `net.host.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected).
+
 Note that in some cases `http.host` might be different
 from the `net.peer.name`
-used to look up the `net.peer.ip` that is actually connected to.
+used to look up the `net.sock.peer.addr` that is actually connected to.
 In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`.
 
 ## HTTP server
@@ -234,27 +246,42 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
 | `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below |
 | `http.route` | string | The matched route (path template). | `/users/:userID?` | Recommended |
 | `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended |
+| [`net.host.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [3] | `localhost` | See below |
+| [`net.host.port`](span-general.md) | int | Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [4] | `8080` | See below |
+| [`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: [5] |
 
 **[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.
 
-**[2]:** This is not necessarily the same as `net.peer.ip`, which would
+**[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would
 identify the network-level peer, which may be a proxy.
 
 This attribute should be set when a source of information different
-from the one used for `net.peer.ip`, is available even if that other
+from the one used for `net.sock.peer.addr`, is available even if that other
-source just confirms the same value as `net.peer.ip`.
+source just confirms the same value as `net.sock.peer.addr`.
-Rationale: For `net.peer.ip`, one typically does not know if it
+Rationale: For `net.sock.peer.addr`, one typically does not know if it
 comes from a proxy, reverse proxy, or the actual client. Setting
-`http.client_ip` when it's the same as `net.peer.ip` means that
+`http.client_ip` when it's the same as `net.sock.peer.addr` means that
 one is at least somewhat confident that the address is not that of
 the closest proxy.
 
+**[3]:** When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.host.name` to the IP address provided in the host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used.
+
+**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match URI port component, otherwise `Host` header port component SHOULD be used.
+
+**[5]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set.
+
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
 * `http.scheme`, `http.host`, `http.target`
 * `http.scheme`, `http.server_name`, [`net.host.port`](span-general.md), `http.target`
 * `http.scheme`, [`net.host.name`](span-general.md), [`net.host.port`](span-general.md), `http.target`
 * `http.url`
+
+Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
+
+* [`net.host.name`](span-general.md)
+* [`net.host.port`](span-general.md)
 <!-- endsemconv -->
 
 Of course, more than the required attributes can be supplied, but this is recommended only if they cannot be inferred from the sent ones.
@@ -268,32 +295,32 @@ As an example, if a browser request for `https://example.com:8080/webshop/articl
 
 Span name: `HTTP GET`
 
-|   Attribute name   |                                       Value             |
+|   Attribute name     |                                       Value             |
-| :----------------- | :-------------------------------------------------------|
+| :------------------- | :-------------------------------------------------------|
-| `http.method`      | `"GET"`                                                 |
+| `http.method`        | `"GET"`                                                 |
-| `http.flavor`      | `"1.1"`                                                 |
+| `http.flavor`        | `"1.1"`                                                 |
-| `http.url`         | `"https://example.com:8080/webshop/articles/4?s=1"`     |
+| `http.url`           | `"https://example.com:8080/webshop/articles/4?s=1"`     |
-| `net.peer.ip`      | `"192.0.2.5"`                                           |
+| `net.sock.peer.addr` | `"192.0.2.5"`                                           |
-| `http.status_code` | `200`                                                   |
+| `http.status_code`   | `200`                                                   |
 
 The corresponding server Span may look like this:
 
 Span name: `/webshop/articles/:article_id`.
 
-|   Attribute name   |                      Value                      |
+|   Attribute name     |                      Value                      |
-| :----------------- | :---------------------------------------------- |
+| :------------------- | :---------------------------------------------- |
-| `http.method`      | `"GET"`                                         |
+| `http.method`        | `"GET"`                                         |
-| `http.flavor`      | `"1.1"`                                         |
+| `http.flavor`        | `"1.1"`                                         |
-| `http.target`      | `"/webshop/articles/4?s=1"`                     |
+| `http.target`        | `"/webshop/articles/4?s=1"`                     |
-| `http.host`        | `"example.com:8080"`                            |
+| `http.host`          | `"example.com:8080"`                            |
-| `http.server_name` | `"example.com"`                                 |
+| `http.server_name`   | `"example.com"`                                 |
-| `net.host.port`    | `8080`                                          |
+| `net.host.port`      | `8080`                                          |
-| `http.scheme`      | `"https"`                                       |
+| `http.scheme`        | `"https"`                                       |
-| `http.route`       | `"/webshop/articles/:article_id"`               |
+| `http.route`         | `"/webshop/articles/:article_id"`               |
-| `http.status_code` | `200`                                           |
+| `http.status_code`   | `200`                                           |
-| `http.client_ip`   | `"192.0.2.4"`                                   |
+| `http.client_ip`     | `"192.0.2.4"`                                   |
-| `net.peer.ip`      | `"192.0.2.5"` (the client goes through a proxy) |
+| `net.sock.peer.addr` | `"192.0.2.5"` (the client goes through a proxy) |
-| `http.user_agent`  | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"`                               |
+| `http.user_agent`    | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"`                               |
 
 Note that following the recommendations above, `http.url` is not set in the above example.
 If set, it would be

specification/trace/semantic_conventions/messaging.md

@@ -139,8 +139,11 @@ The following operations related to messages are defined for these semantic conv
 | `messaging.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended |
 | `messaging.message_payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended |
 | `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | 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` | Conditionally Required: If available. |
+| [`net.peer.name`](span-general.md) | string | Logical remote hostname, see note below. [3] | `example.com` | Conditionally Required: If available. |
-| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | Conditionally Required: If available. |
+| [`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: [4] |
+| [`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: [5] |
+| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] |
 
 **[1]:** If the message destination is either a `queue` or `topic`.
 
@@ -148,6 +151,12 @@ The following operations related to messages are defined for these semantic conv
 
 **[3]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
 
+**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document.
+
+**[5]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set.
+
+**[6]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set.
+
 `messaging.destination_kind` MUST be one of the following:
 
 | Value  | Description |

specification/trace/semantic_conventions/rpc.md

@@ -60,20 +60,27 @@ Examples of span names:
 | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
 | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | 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` | 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 | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
-| [`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 | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: See below |
-| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: See below |
+| [`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: 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). | `127.0.0.1`; `/tmp/mysql.sock` | See below |
+| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] |
+| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] |
 | [`net.transport`](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).
 
 **[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.
+**[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]:** 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.peer.ip`](span-general.md)
+* [`net.sock.peer.addr`](span-general.md)
 * [`net.peer.name`](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.
@@ -111,8 +118,14 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
 <!-- semconv rpc.server -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| [`net.host.ip`](span-general.md) | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended |
+| [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | Recommended |
-| [`net.host.name`](span-general.md) | string | 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] |
+
+**[1]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from 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.
 <!-- endsemconv -->
 
 ### Events

specification/trace/semantic_conventions/span-general.md

@@ -12,7 +12,13 @@ Particular operations may refer to or require some of these attributes.
 
 - [General network connection attributes](#general-network-connection-attributes)
   * [Network transport attributes](#network-transport-attributes)
-  * [`net.*.name` attributes](#netname-attributes)
+  * [`net.peer.name` and `net.host.name` attributes](#netpeername-and-nethostname-attributes)
+    + [`net.peer.name`](#netpeername)
+    + [`net.host.name`](#nethostname)
+  * [`net.sock.*` attributes](#netsock-attributes)
+    + [Peer](#peer)
+    + [Host](#host)
+    + [Connecting through intermediary](#connecting-through-intermediary)
 - [General remote service attributes](#general-remote-service-attributes)
 - [General identity attributes](#general-identity-attributes)
 - [General thread attributes](#general-thread-attributes)
@@ -37,12 +43,16 @@ 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` | Recommended |
 | `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
-| `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` | Recommended |
+| `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended: [2] |
-| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | Recommended |
+| `net.sock.peer.addr` | 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.peer.name` | string | Remote hostname or similar, see note below. [2] | `example.com` | Recommended |
+| `net.sock.peer.port` | int | Remote socket peer port. | `16456` | Recommended: [3] |
-| `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` | Recommended |
+| `net.sock.family` | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [4] |
-| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | Recommended |
+| `net.peer.name` | string | Logical remote hostname, see note below. [5] | `example.com` | Recommended |
-| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | Recommended |
+| `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | Recommended |
+| `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.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 |
@@ -52,22 +62,36 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
 
 **[1]:** `net.app.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
-**[2]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.
+**[2]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set.
 
-`net.transport` MUST be one of the following:
+**[3]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set.
+
+**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document.
+
+**[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.
+
+`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.
 
 | Value  | Description |
 |---|---|
 | `ip_tcp` | ip_tcp |
 | `ip_udp` | ip_udp |
-| `ip` | Another IP-based protocol |
-| `unix` | Unix Domain socket. See below. |
 | `pipe` | Named or anonymous pipe. See note below. |
 | `inproc` | In-process communication. [1] |
 | `other` | Something else (non IP-based). |
 
 **[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case.
 
+`net.sock.family` 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.
+
+| Value  | Description |
+|---|---|
+| `inet` | IPv4 address |
+| `inet6` | IPv6 address |
+| `unix` | Unix domain socket path |
+
 `net.host.connection.type` 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.
 
 | Value  | Description |
@@ -107,21 +131,86 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
 
 For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `net.peer.name` is the only attribute that usually makes sense (see description of `net.peer.name` below).
 
-### `net.*.name` attributes
+### `net.peer.name` and `net.host.name` attributes
 
-For IP-based communication, the name should be a DNS host name.
+`net.peer.name` and `net.host.name` represent logical host names. Semantic conventions that refer to these attributes SHOULD
-For `net.peer.name`, this should be the name that was used to look up the IP address that was connected to
+specify what these attributes mean in their context.
-(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 DNS lookup SHOULD NOT be used to obtain `net.peer.name`,
+Semantic conventions and instrumentations that populate both logical (`net.peer.name`, `net.host.name`) and socket-level (`net.sock.*.name`) attributes SHOULD set socket-level attributes only when they don't match logical ones. For example, when direct connection to the remote destination is established and `net.peer.name` is populated, `net.sock.peer.name` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information.
-and `net.peer.name` SHOULD NOT be set.
+
-`net.host.name` should be the host name of the local host,
+#### `net.peer.name`
-preferably the one that the peer used to connect for the current operation.
+
+For IP-based communication, the name should be a DNS host name of the remote service.
+
+`net.peer.name` should be the name of logical remote destination, e.g., `"example.com"` if connecting to an URL `https://example.com/foo`. Usually, application pass it as configuration to client libraries in form of URL, connection string, host name, etc.
+
+Sometimes host name is only available to instrumentation as a string which may contain DNS name or IP address. `net.peer.name` SHOULD be set to the available known hostname (e.g., `"127.0.0.1"` if connecting to an URL `https://127.0.0.1.com/foo`).
+
+If only IP address is available via `net.sock.peer.addr`, `net.peer.name` SHOULD NOT be set. Reverse DNS lookup SHOULD NOT be used to obtain DNS name.
+
+If `net.transport` is `"pipe"`, the absolute path to the file representing it should be used as `net.peer.name` (`net.host.name` doesn't make sense in that context).
+If there is no such file (e.g., anonymous pipe),
+the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation.
+
+For Unix domain socket, `net.sock.peer.addr` attribute represents destination name and `net.peer.name` SHOULD NOT be set.
+
+`net.peer.name` and `net.peer.port` apply to client instrumentations only. Server instrumentations SHOULD NOT set these attributes.
+
+#### `net.host.name`
+
+`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.
 It will usually not make sense to use reverse-lookup to obtain `net.host.name`, as that would result in static information that is better stored as resource information.
 
-If `net.transport` is `"unix"` or `"pipe"`, the absolute path to the file representing it should be used as `net.peer.name` (`net.host.name` doesn't make sense in that context).
+`net.host.name` and `net.host.port` apply to server instrumentations only. Client instrumentations SHOULD NOT set these attributes.
-If there is no such file (e.g., anonymous pipe),
+
-the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation.
+### `net.sock.*` attributes
+
+_Note: this section applies to socket connections visible to instrumentations. Instrumentations have limited knowledge about intermediaries communications goes through such as [transparent proxies](https://www.rfc-editor.org/rfc/rfc3040.html#section-2.5) or VPN servers. Higher-level instrumentations such as HTTP don't always have access to the socket-level information and may not be able to populate socket-level attributes._
+
+Socket-level attributes identify peer and host that are directly connected to each other. Since instrumentations may have limited knowledge on network information, instrumentations SHOULD populate such attributes to the best of their knowledge when populate them at all.
+
+`net.sock.family` identifies address family specified when connecting to the socket. For example, it matches `sa_family` field of `sockaddr` structure on [Linux](https://man7.org/linux/man-pages/man0/sys_socket.h.0p.html) and [Windows](https://docs.microsoft.com/windows/win32/api/winsock/ns-winsock-sockaddr).
+
+_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._
+
+#### Peer
+
+`net.sock.peer.addr`, `net.sock.peer.port` identify remote peer - the address used to connect to the socket. For example, when connecting using `connect(2)`
+on [Linux](https://man7.org/linux/man-pages/man2/connect.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect)
+with `AF_INET` address family, represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure.
+
+Address and port can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html),
+[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername).
+
+`net.sock.peer.port` SHOULD only be populated for families that have notion of port.
+
+`net.sock.peer.name` SHOULD be set to the DNS name used to resolve `net.sock.peer.addr` if it's readily available. Instrumentations
+SHOULD NOT do DNS lookups to obtain `net.sock.peer.addr` or `net.sock.peer.name`. If peer information available to instrumentation
+can represent DNS name or IP address, instrumentation SHOULD NOT attempt to parse it and SHOULD only set `net.sock.peer.name`.
+
+For example, [URL Host component](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2) can contain IP address or DNS name and
+instrumentations that don't have access to socket-level communication can only populate `net.sock.peer.name`.
+Instrumentations that have access to socket connection, may be able to populate valid `net.sock.peer.addr` instead of or
+in addition to DNS name.
+
+#### Host
+
+`net.sock.host.addr`, `net.sock.host.port`  identify local socket address - the address used to bind to the socket. For example, when using `bind(2)`
+on [Linux](https://man7.org/linux/man-pages/man2/bind.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind)
+with `AF_INET` address family, represent `sin_addr` and `sin_port` fields of `sockaddr_in` structure.
+
+`net.sock.host.port` SHOULD only be populated for families that have notion of port.
+
+Address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html),
+[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname).
+
+#### Connecting through intermediary
+
+When connecting to the remote destination through an intermediary (e.g. proxy), client instrumentations SHOULD set `net.peer.name` and `net.peer.port` to logical remote destination address and `net.sock.peer.addr` and `net.sock.peer.port` to the socket peer connection is established with - the intermediary.
+
+Server instrumentations that use `net.host.name` and `net.host.port` SHOULD set them to logical local host; If `net.sock.peer.addr` and `net.sock.peer.port` are used, they SHOULD be set to the address of intermediary connection is established with.
+Server semantic conventions SHOULD define additional attribute(s) representing originating peer address for reverse-proxy scenarios when such information is available.
 
 ## General remote service attributes