Define net.sock attributes and clarify logical net.peer|host.name att…

…ributes (#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"
         ]
     },

CHANGELOG.md

@@ -49,6 +49,10 @@ release.
 - Add `http.*.*.size` metric semantic conventions for tracking size of requests
   / responses for http servers / clients
   ([#2588](https://github.com/open-telemetry/opentelemetry-specification/pull/2588)).
+- BREAKING: rename `net.peer.ip` to `net.sock.peer.addr`, `net.host.ip` to `net.sock.host.addr`,
+  `net.peer.name` to `net.sock.peer.name` for socket-level instrumentation.
+  Define socket-level attributes and clarify logical peer and host attributes meaning.
+  ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594))
 
 ### Compatibility
 

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,22 +217,29 @@ groups:
         tag: connection-level
         requirement_level:
           conditionally_required: See alternative attributes below.
-      - ref: net.peer.ip
+        brief: >
+          Name of the database host.
+      - ref: net.peer.port
         tag: connection-level
         requirement_level:
-          conditionally_required: See alternative attributes below.
-      - ref: net.peer.port
+          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:
-          conditionally_required: If using a port other than the default port for this DBMS.
+          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
       - ref: net.transport
         tag: connection-level
         requirement_level:
           conditionally_required: If database type is in-process (`"inproc"`), recommended for other database types.
     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
-          [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6)
-        examples: '127.0.0.1'
-      - id: peer.port
+          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).
+        examples: ['127.0.0.1', '/tmp/mysql.sock' ]
+      - id: sock.peer.port
         type: int
-        brief: 'Remote port number.'
-        examples: [80, 8080, 443]
+        brief: Remote socket peer port.
+        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
-        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
+      - id: peer.port
         type: int
-        brief: 'Like `net.peer.port` but for the host port.'
-        examples: 35555
+        brief: 'Logical remote port number'
+        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
-        sampling_relevant: true
-      - ref: net.peer.port
-        sampling_relevant: true
+      - ref: net.sock.peer.addr
+      - ref: net.sock.peer.port
+      - ref: net.sock.peer.name
+      - 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
-            source just confirms the same value as `net.peer.ip`.
-            Rationale: For `net.peer.ip`, one typically does not know if it
+            from the one used for `net.sock.peer.addr`, is available even if that other
+            source just confirms the same value as `net.sock.peer.addr`.
+            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/common/attribute-requirement-level.md

@@ -48,7 +48,7 @@ All instrumentations MUST add the attribute when given condition is satisfied. S
 
 When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute.
 
-For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.peer.ip` is available,  instrumentation can do a DNS lookup, cache and populate `net.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces.
+For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available,  instrumentation can do a DNS lookup, cache and populate `net.sock.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces.
 
 ## Recommended