BREAKING: Rename remaining network attributes from net.* to `networ…

…k.*` and align definitions with ECS (#3426)

CHANGELOG.md

@@ -69,6 +69,15 @@ release.
      `net.sock.host.addr` to `server.socket.address` (since `net.sock.host.*` only applied to server instrumentation),
      `net.sock.host.port` to `server.socket.port` (similarly since `net.sock.host.*` only applied to server instrumentation),
      `http.client_ip` to `client.address`
+- BREAKING: Introduce `network.transport` defined as
+  [OSI Transport Layer](https://osi-model.com/transport-layer/) or
+  [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication).
+  Introduce `network.type` defined as [OSI Network Layer](https://osi-model.com/network-layer/)
+  or non-OSI equivalent. Remove `net.transport` and `net.sock.family`.
+  Rename `net.protocol.*` to `network.protocol.*`,
+  `net.host.connection.*` to `network.connection.*`, and
+  `net.host.carrier.*` to `network.carrier.*`.
+  ([#3426](https://github.com/open-telemetry/opentelemetry-specification/pull/3426))
 
 ### Compatibility
 

schemas/1.21.0

@@ -25,6 +25,17 @@ versions:
               net.sock.host.addr: server.socket.address
               net.sock.host.port: server.socket.port
               http.client_ip: client.address
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3426
+        - rename_attributes:
+            attribute_map:
+              net.protocol.name: network.protocol.name
+              net.protocol.version: network.protocol.version
+              net.host.connection.type: network.connection.type
+              net.host.connection.subtype: network.connection.subtype
+              net.host.carrier.name: network.carrier.name
+              net.host.carrier.mcc: network.carrier.mcc
+              net.host.carrier.mnc: network.carrier.mnc
+              net.host.carrier.icc: network.carrier.icc
   1.20.0:
     spans:
       changes:

semantic_conventions/deprecated/network.yaml

@@ -51,3 +51,51 @@ groups:
         stability: deprecated
         brief: Deprecated, use `server.socket.port`.
         examples: [8080]
+      - id: transport
+        type:
+          allow_custom_values: true
+          members:
+            - id: ip_tcp
+              value: "ip_tcp"
+            - id: ip_udp
+              value: "ip_udp"
+            - id: pipe
+              value: "pipe"
+              brief: 'Named or anonymous pipe.'
+            - id: inproc
+              value: "inproc"
+              brief: 'In-process communication.'
+              note: >
+                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.
+            - id: other
+              value: "other"
+              brief: 'Something else (non IP-based).'
+        stability: deprecated
+        brief: Deprecated, use `network.transport`.
+      - id: protocol.name
+        type: string
+        stability: deprecated
+        brief: Deprecated, use `network.protocol.name`.
+        examples: ['amqp', 'http', 'mqtt']
+      - id: protocol.version
+        type: string
+        stability: deprecated
+        brief: Deprecated, use `network.protocol.version`.
+        examples: '3.1.1'
+      - 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"
+        stability: deprecated
+        brief: Deprecated, use `network.transport` and `network.type`.

semantic_conventions/http-common.yaml

@@ -15,11 +15,11 @@ groups:
           conditionally_required: If and only if one was received/sent.
         brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
         examples: [200]
-      - ref: net.protocol.name
+      - ref: network.protocol.name
         examples: ['http', 'spdy']
         requirement_level:
           recommended: if not default (`http`).
-      - ref: net.protocol.version
+      - ref: network.protocol.version
         examples: ['1.0', '1.1', '2.0']
 
   - id: attributes.http.client

semantic_conventions/metrics/http.yaml

@@ -10,8 +10,8 @@ groups:
       # todo (lmolkova) build tools don't populate grandparent attributes
       - ref: http.method
       - ref: http.status_code
-      - ref: net.protocol.name
-      - ref: net.protocol.version
+      - ref: network.protocol.name
+      - ref: network.protocol.version
 
   - id: metric.http.server.active_requests
     type: metric
@@ -62,8 +62,8 @@ groups:
       # todo (lmolkova) build tools don't populate grandparent attributes
       - ref: http.method
       - ref: http.status_code
-      - ref: net.protocol.name
-      - ref: net.protocol.version
+      - ref: network.protocol.name
+      - ref: network.protocol.version
 
   - id: metric.http.server.response.size
     type: metric
@@ -76,8 +76,8 @@ groups:
     attributes:
       - ref: http.method
       - ref: http.status_code
-      - ref: net.protocol.name
-      - ref: net.protocol.version
+      - ref: network.protocol.name
+      - ref: network.protocol.version
 
   - id: metric.http.client.duration
     type: metric
@@ -89,8 +89,8 @@ groups:
     attributes:
       - ref: http.method
       - ref: http.status_code
-      - ref: net.protocol.name
-      - ref: net.protocol.version
+      - ref: network.protocol.name
+      - ref: network.protocol.version
       - ref: server.socket.address
 
   - id: metric.http.client.request.size
@@ -104,8 +104,8 @@ groups:
     attributes:
       - ref: http.method
       - ref: http.status_code
-      - ref: net.protocol.name
-      - ref: net.protocol.version
+      - ref: network.protocol.name
+      - ref: network.protocol.version
       - ref: server.socket.address
 
   - id: metric.http.client.response.size
@@ -119,6 +119,6 @@ groups:
     attributes:
       - ref: http.method
       - ref: http.status_code
-      - ref: net.protocol.name
-      - ref: net.protocol.version
+      - ref: network.protocol.name
+      - ref: network.protocol.version
       - ref: server.socket.address

semantic_conventions/trace/database.yaml

@@ -242,15 +242,13 @@ groups:
         tag: connection-level
       - ref: server.socket.port
         tag: connection-level
-      - ref: net.sock.family
+      - ref: network.transport
+        tag: connection-level
+      - ref: network.type
         tag: connection-level
       - ref: server.socket.domain
         requirement_level:
           recommended: If different than `server.address` and if `server.socket.address` 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:
           - 'server.address'

semantic_conventions/trace/general.yaml

@@ -1,6 +1,6 @@
 groups:
   - id: network-core
-    prefix: net
+    prefix: network
     type: attribute_group
     brief: >
         These attributes may be used for any network related operation.
@@ -9,67 +9,59 @@ groups:
         type:
           allow_custom_values: true
           members:
-            - id: ip_tcp
-              value: "ip_tcp"
-            - id: ip_udp
-              value: "ip_udp"
+            - id: tcp
+              value: 'tcp'
+              brief: "TCP"
+            - id: udp
+              value: 'udp'
+              brief: "UDP"
             - id: pipe
               value: "pipe"
               brief: 'Named or anonymous pipe. See note below.'
-            - id: inproc
-              value: "inproc"
-              brief: 'In-process communication.'
-              note: >
-                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.
-            - id: other
-              value: "other"
-              brief: 'Something else (non IP-based).'
+            - id: unix
+              value: 'unix'
+              brief: "Unix domain socket"
         brief: >
-          Transport protocol used. See note below.
+          [OSI Transport Layer](https://osi-model.com/transport-layer/) or
+          [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication).
+          The value SHOULD be normalized to lowercase.
+        examples: ['tcp', 'udp']
+      - id: type
+        type:
+          allow_custom_values: true
+          members:
+            - id: ipv4
+              value: 'ipv4'
+              brief: "IPv4"
+            - id: ipv6
+              value: 'ipv6'
+              brief: "IPv6"
+        brief: >
+          [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent.
+          The value SHOULD be normalized to lowercase.
+        examples: ['ipv4', 'ipv6']
       - id: protocol.name
         type: string
-        brief: 'Application layer protocol used. The value SHOULD be normalized to lowercase.'
+        brief: >
+          [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent.
+          The value SHOULD be normalized to lowercase.
         examples: ['amqp', 'http', 'mqtt']
       - id: protocol.version
         type: string
         brief: 'Version of the application layer protocol used. See note below.'
         examples: '3.1.1'
         note: >
-          `net.protocol.version` refers to the version of the protocol used and might be
+          `network.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: 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 `server.socket.address` or `client.socket.address` are set.
-            Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `server.socket.address` and `client.socket.address`
-            if `net.sock.family` is not set. This is to support 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: network-connection-and-carrier
-    prefix: net
+    prefix: network
     type: attribute_group
     brief: >
       These attributes may be used for any network related operation.
     attributes:
-      - id: host.connection.type
+      - id: connection.type
         type:
           allow_custom_values: true
           members:
@@ -83,9 +75,9 @@ groups:
               value: "unavailable"
             - id: unknown
               value: "unknown"
-        brief: 'The internet connection type currently being used by the host.'
+        brief: 'The internet connection type.'
         examples: 'wifi'
-      - id: host.connection.subtype
+      - id: connection.subtype
         type:
           allow_custom_values: true
           members:
@@ -154,19 +146,19 @@ groups:
               value: "lte_ca"
         brief: '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.'
         examples: 'LTE'
-      - id: host.carrier.name
+      - id: carrier.name
         type: string
         brief: "The name of the mobile carrier."
         examples: "sprint"
-      - id: host.carrier.mcc
+      - id: carrier.mcc
         type: string
         brief: "The mobile carrier country code."
         examples: "310"
-      - id: host.carrier.mnc
+      - id: carrier.mnc
         type: string
         brief: "The mobile carrier network code."
         examples: "001"
-      - id: host.carrier.icc
+      - id: carrier.icc
         type: string
         brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network."
         examples: "DE"

semantic_conventions/trace/http.yaml

@@ -24,8 +24,10 @@ groups:
         examples: 3495
       - ref: http.method
         sampling_relevant: true
-      - ref: net.sock.family
-        examples: ['inet', 'inet6']
+      - ref: network.transport
+        requirement_level:
+          conditionally_required: If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`).
+      - ref: network.type
       - ref: user_agent.original
 
   - id: trace.http.client

semantic_conventions/trace/messaging.yaml

@@ -150,15 +150,17 @@ groups:
         tag: connection-level
       - ref: server.socket.port
         tag: connection-level
-      - ref: net.sock.family
+      - ref: network.transport
+        tag: connection-level
+      - ref: network.type
         tag: connection-level
       - ref: server.socket.domain
         tag: connection-level
         requirement_level:
           recommended: If different than `server.address` and if `server.socket.address` is set.
-      - ref: net.protocol.name
+      - ref: network.protocol.name
         examples: ['amqp', 'mqtt']
-      - ref: net.protocol.version
+      - ref: network.protocol.version
 
   - id: messaging.producer
     prefix: messaging

semantic_conventions/trace/rpc.yaml

@@ -53,9 +53,8 @@ groups:
       - ref: server.socket.port
         requirement_level:
           recommended: If different than `server.port` and if `server.socket.address` is set.
-      - ref: net.sock.family
-        requirement_level:
-          conditionally_required: If and only if `server.socket.address` is set.
+      - ref: network.transport
+      - ref: network.type
       - ref: server.address
         requirement_level: required
         brief: >
@@ -67,9 +66,6 @@ groups:
       - ref: server.port
         requirement_level:
           conditionally_required: See below
-      - ref: net.transport
-        requirement_level:
-          conditionally_required: See below
     constraints:
       - any_of:
           - server.socket.address
@@ -95,6 +91,8 @@ groups:
       - ref: client.port
       - ref: client.socket.address
       - ref: client.socket.port
+      - ref: network.transport
+      - ref: network.type
 
   - id: rpc.grpc
     prefix: rpc.grpc