BREAKING: Replace net.peer.*/net.host.* with client.*/`server.*…

…` (and `source.*`/`destination.*`) (#3402)

CHANGELOG.md

@@ -58,6 +58,17 @@ release.
 - Add transition plan for upcoming breaking changes to the unstable HTTP semantic
   conventions.
   ([#3443](https://github.com/open-telemetry/opentelemetry-specification/pull/3443))
+- Rename `net.peer.*`, `net.host.*`, and `net.sock.*` attributes to align with ECS
+  ([#3402](https://github.com/open-telemetry/opentelemetry-specification/pull/3402))
+    BREAKING: rename `net.peer.name` to `server.address` on client side and to `client.address` on server side,
+     `net.peer.port` to `server.port` on client side and to `client.port` on server side,
+     `net.host.name` and `net.host.port` to `server.name` and `server.port` (since `net.host.*` attributes only applied to server instrumentation)
+     `net.sock.peer.addr` to `server.socket.address` on client side and to `client.socket.address` on server side,
+     `net.sock.peer.port` to `server.socket.port` on client side and to `client.socket.port` on server side,
+     `net.sock.peer.name` to `server.socket.domain` (since `net.sock.peer.name` only applied to client instrumentation),
+     `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`
 
 ### Compatibility
 

schemas/1.21.0

@@ -9,6 +9,22 @@ versions:
             attribute_map:
               messaging.kafka.client_id: messaging.client_id
               messaging.rocketmq.client_id: messaging.client_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3402
+        - rename_attributes:
+            attribute_map:
+              # net.peer.(name|port) attributes were usually populated on client side
+              # so they should be usually translated to server.(address|port)
+              # net.host.* attributes were only populated on server side
+              net.host.name: server.address
+              net.host.port: server.port
+              # was only populated on client side
+              net.sock.peer.name: server.socket.domain
+              # net.sock.peer.(addr|port) mapping is not possible
+              # since they applied to both client and server side
+              # were only populated on server side
+              net.sock.host.addr: server.socket.address
+              net.sock.host.port: server.socket.port
+              http.client_ip: client.address
   1.20.0:
     spans:
       changes:

semantic_conventions/client.yaml

@@ -0,0 +1,38 @@
+groups:
+  - id: client
+    prefix: client
+    type: attribute_group
+    brief: >
+      These attributes may be used to describe the client in a connection-based network interaction
+      where there is one side that initiates the connection (the client is the side that initiates the connection).
+      This covers all TCP network interactions since TCP is connection-based and one side initiates the
+      connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the
+      protocol / API does not expose a clear notion of client and server).
+      This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.
+    attributes:
+      - id: address
+        type: string
+        brief: Client address - unix domain socket name, IPv4 or IPv6 address.
+        note: >
+          When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent
+          client address behind any intermediaries (e.g. proxies) if it's available.
+        examples: ['/tmp/my.sock', '10.1.2.80']
+      - id: port
+        type: int
+        brief: 'Client port number'
+        examples: [65123]
+        note: >
+          When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent
+          client port behind any intermediaries (e.g. proxies) if it's available.
+      - id: socket.address
+        type: string
+        brief: Immediate client peer address - unix domain socket name, IPv4 or IPv6 address.
+        examples: ['/tmp/my.sock', '127.0.0.1']
+        requirement_level:
+          recommended: If different than `client.address`.
+      - id: socket.port
+        type: int
+        brief: 'Immediate client peer port number'
+        examples: [35555]
+        requirement_level:
+          recommended: If different than `client.port`.

semantic_conventions/deprecated/network.yaml

@@ -0,0 +1,53 @@
+groups:
+  - id: network-deprecated
+    prefix: net
+    type: attribute_group
+    brief: >
+        These attributes may be used for any network related operation.
+    attributes:
+      - id: sock.peer.name
+        type: string
+        stability: deprecated
+        brief: Deprecated, use `server.socket.domain` on client spans.
+        examples: ['/var/my.sock']
+      - id: sock.peer.addr
+        type: string
+        stability: deprecated
+        brief: >
+          Deprecated, use `server.socket.address` on client spans and `client.socket.address` on server spans.
+        examples: ['192.168.0.1']
+      - id: sock.peer.port
+        type: int
+        stability: deprecated
+        examples: [65531]
+        brief: Deprecated, use `server.socket.port` on client spans and `client.socket.port` on server spans.
+      - id: peer.name
+        type: string
+        stability: deprecated
+        brief: Deprecated, use `server.address` on client spans and `client.address` on server spans.
+        examples: ['example.com']
+      - id: peer.port
+        type: int
+        stability: deprecated
+        brief: Deprecated, use `server.port` on client spans and `client.port` on server spans.
+        examples: [8080]
+      - id: host.name
+        type: string
+        stability: deprecated
+        brief: Deprecated, use `server.address`.
+        examples: ['example.com']
+      - id: host.port
+        type: int
+        stability: deprecated
+        brief: Deprecated, use `server.port`.
+        examples: [8080]
+      - id: sock.host.addr
+        type: string
+        stability: deprecated
+        brief: Deprecated, use `server.socket.address`.
+        examples: ['/var/my.sock']
+      - id: sock.host.port
+        type: int
+        stability: deprecated
+        brief: Deprecated, use `server.socket.port`.
+        examples: [8080]

semantic_conventions/destination.yaml

@@ -0,0 +1,24 @@
+groups:
+  - id: destination
+    prefix: destination
+    type: attribute_group
+    brief: These attributes may be used to describe the receiver of a network exchange/packet. These should be used
+      when there is no client/server relationship between the two sides, or when that relationship is unknown.
+      This covers low-level network interactions (e.g. packet tracing) where you don't know if
+      there was a connection or which side initiated it.
+      This also covers unidirectional UDP flows and peer-to-peer communication where the
+      "user-facing" surface of the protocol / API does not expose a clear notion of client and server.
+    attributes:
+      - id: domain
+        type: string
+        brief: The domain name of the destination system.
+        examples: ['foo.example.com']
+        note: This value may be a host name, a fully qualified domain name, or another host naming format.
+      - id: address
+        type: string
+        brief: 'Peer address, for example IP address or UNIX socket name.'
+        examples: ['10.5.3.2']
+      - id: port
+        type: int
+        brief: 'Peer port number'
+        examples: [3389, 2888]

semantic_conventions/http-common.yaml

@@ -27,7 +27,7 @@ groups:
     type: attribute_group
     brief: 'HTTP Client spans attributes'
     attributes:
-      - ref: net.peer.name
+      - ref: server.address
         requirement_level: required
         brief: >
           Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.
@@ -39,13 +39,13 @@ groups:
           - Host identifier of the `Host` header
 
           SHOULD NOT be set if capturing it would require an extra DNS lookup.
-      - ref: net.peer.port
+      - ref: server.port
         requirement_level:
           conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
         brief: >
           Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) 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
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match
           URI port identifier, otherwise it MUST match `Host` header port identifier.
 
   - id: attributes.http.server
@@ -69,7 +69,7 @@ groups:
           MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
 
           SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
-      - ref: net.host.name
+      - ref: server.address
         requirement_level: required
         brief: >
           Name of the local HTTP server that received the request.
@@ -84,7 +84,7 @@ groups:
 
           SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
 
-      - ref: net.host.port
+      - ref: server.port
         requirement_level:
           conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
         brief: >

semantic_conventions/metrics/http.yaml

@@ -22,7 +22,7 @@ groups:
     attributes:
       - ref: http.method
       - ref: http.scheme
-      - ref: net.host.name
+      - ref: server.address
         requirement_level: required
         brief: >
           Name of the local HTTP server that received the request.
@@ -37,7 +37,7 @@ groups:
 
           SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
 
-      - ref: net.host.port
+      - ref: server.port
         requirement_level:
           conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
         brief: >
@@ -91,7 +91,7 @@ groups:
       - ref: http.status_code
       - ref: net.protocol.name
       - ref: net.protocol.version
-      - ref: net.sock.peer.addr
+      - ref: server.socket.address
 
   - id: metric.http.client.request.size
     type: metric
@@ -106,7 +106,7 @@ groups:
       - ref: http.status_code
       - ref: net.protocol.name
       - ref: net.protocol.version
-      - ref: net.sock.peer.addr
+      - ref: server.socket.address
 
   - id: metric.http.client.response.size
     type: metric
@@ -121,4 +121,4 @@ groups:
       - ref: http.status_code
       - ref: net.protocol.name
       - ref: net.protocol.version
-      - ref: net.sock.peer.addr
+      - ref: server.socket.address

semantic_conventions/server.yaml

@@ -0,0 +1,37 @@
+groups:
+  - id: server
+    prefix: server
+    type: attribute_group
+    brief: >
+      These attributes may be used to describe the server in a connection-based network interaction
+      where there is one side that initiates the connection (the client is the side that initiates the connection).
+      This covers all TCP network interactions since TCP is connection-based and one side initiates the
+      connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the
+      protocol / API does not expose a clear notion of client and server).
+      This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.
+    attributes:
+      - id: address
+        type: string
+        brief: 'Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known.'
+        examples: ['example.com']
+      - id: port
+        type: int
+        brief: 'Logical server port number'
+        examples: [80, 8080, 443]
+      - id: socket.domain
+        type: string
+        brief: The domain name of an immediate peer.
+        examples: ['proxy.example.com']
+        note: Typically observed from the client side, and represents a proxy or other intermediary domain name.
+      - id: socket.address
+        type: string
+        brief: Physical server IP address or Unix socket address.
+        examples: ['10.5.3.2']
+        requirement_level:
+          recommended: If different than `server.address`.
+      - id: socket.port
+        type: int
+        brief: Physical server port.
+        examples: [16456]
+        requirement_level:
+          recommended: If different than `server.port`.

semantic_conventions/source.yaml

@@ -0,0 +1,24 @@
+groups:
+  - id: source
+    prefix: source
+    type: attribute_group
+    brief: These attributes may be used to describe the sender of a network exchange/packet. These should be used
+      when there is no client/server relationship between the two sides, or when that relationship is unknown.
+      This covers low-level network interactions (e.g. packet tracing) where you don't know if
+      there was a connection or which side initiated it.
+      This also covers unidirectional UDP flows and peer-to-peer communication where the
+      "user-facing" surface of the protocol / API does not expose a clear notion of client and server.
+    attributes:
+      - id: domain
+        type: string
+        brief: The domain name of the source system.
+        examples: ['foo.example.com']
+        note: This value may be a host name, a fully qualified domain name, or another host naming format.
+      - id: address
+        type: string
+        brief: 'Source address, for example IP address or Unix socket name.'
+        examples: ['10.5.3.2']
+      - id: port
+        type: int
+        brief: 'Source port number'
+        examples: [3389, 2888]

semantic_conventions/trace/database.yaml

@@ -228,33 +228,33 @@ groups:
           If the SQL statement has an ambiguous operation, or performs more
           than one operation, this value may be omitted.
         examples: ['findAndModify', 'HMSET', 'SELECT']
-      - ref: net.peer.name
+      - ref: server.address
         tag: connection-level
         requirement_level:
           conditionally_required: See alternative attributes below.
         brief: >
           Name of the database host.
-      - ref: net.peer.port
+      - ref: server.port
         tag: connection-level
         requirement_level:
-          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
+          conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set.
+      - ref: server.socket.address
         tag: connection-level
-      - ref: net.sock.peer.port
+      - ref: server.socket.port
         tag: connection-level
       - ref: net.sock.family
         tag: connection-level
-      - ref: net.sock.peer.name
+      - ref: server.socket.domain
         requirement_level:
-          recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set.
+          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:
-          - 'net.peer.name'
-          - 'net.sock.peer.addr'
+          - 'server.address'
+          - 'server.socket.address'
 
   - id: db.mssql
     prefix: db.mssql
@@ -267,7 +267,7 @@ groups:
         tag: connection-level-tech-specific
         type: string
         note: >
-          If setting a `db.mssql.instance_name`, `net.peer.port` is no longer
+          If setting a `db.mssql.instance_name`, `server.port` is no longer
           required (but still recommended if non-standard).
         brief: >
           The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15)