add source and destination and fix some nits

schemas/1.21.0

@@ -12,13 +12,16 @@ versions:
         # https://github.com/open-telemetry/opentelemetry-specification/pull/3402
         - rename_attributes:
             attribute_map:
+              # net.peer.* attributes were only populated on client side
+              # so they always translate to server.*
               net.peer.name: server.address
               net.peer.port: server.port
+              # net.host.* attributes were only populated on server side
               net.host.name: server.address
               net.host.port: server.port
-              net.sock.peer.addr: server.socket.address            
+              # was only populated on client side
               net.sock.peer.name: server.socket.domain
-              net.sock.peer.port: server.socket.port
+              # net.sock.peer.(addr|port) mapping is not possible
               net.sock.host.addr: server.socket.address
               net.sock.host.port: server.socket.port
   1.20.0:

semantic_conventions/trace/client.yaml

@@ -2,7 +2,7 @@ groups:
   - id: client
     prefix: client
     type: attribute_group
-    brief: These attributes may be used for client - initiator of a network connection for events regarding sessions, connections, or bidirectional flow records.
+    brief: These attributes may be used to describe the client - initiator of a network connection for events regarding sessions, connections, or bidirectional flow records.
     attributes:
       - id: socket.address
         type: string

semantic_conventions/trace/destination.yaml

@@ -0,0 +1,20 @@
+groups:
+  - id: destination
+    prefix: destination
+    type: attribute_group
+    brief: These attributes may be used to describe the receiver of a network exchange/packet. 
+      These fields are populated from a network event, packet, or other event containing details of a network transaction.
+    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/trace/server.yaml

@@ -2,7 +2,7 @@ groups:
   - id: server
     prefix: server
     type: attribute_group
-    brief: These attributes may be used for server - responder in a network connection for events regarding sessions, connections, or bidirectional flow records.
+    brief: These attributes may be used to describe server - responder in a network connection for events regarding sessions, connections, or bidirectional flow records.
     attributes:
       - id: address
         type: string

semantic_conventions/trace/source.yaml

@@ -0,0 +1,20 @@
+groups:
+  - id: source
+    prefix: source
+    type: attribute_group
+    brief: These attributes may be used to describe the sender of a network exchange/packet. 
+      These fields are populated from a network event, packet, or other event containing details of a network transaction.
+    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, fo example IP address or UNIX socket name.'
+        examples: ['10.5.3.2']
+      - id: port
+        type: int
+        brief: 'Source port number'
+        examples: [3389, 2888]

specification/trace/semantic_conventions/span-general.md

@@ -10,10 +10,12 @@ Particular operations may refer to or require some of these attributes.
 
 <!-- toc -->
 
-- [General network connection attributes](#general-network-connection-attributes)
+- [Server and client attributes](#server-and-client-attributes)
   * [Server attributes](#server-attributes)
   * [Client attributes](#client-attributes)
+- [Network attributes](#network-attributes)
   * [Common network attributes](#common-network-attributes)
+  * [Source and destination attributes](#source-and-destination-attributes)* 
   * [Network connection and carrier attributes](#network-connection-and-carrier-attributes)
   * [`server.*` and `client*` attributes](#server-and-client-attributes)
     + [`server.*` attributes](#server-attributes)
@@ -28,16 +30,14 @@ Particular operations may refer to or require some of these attributes.
 
 <!-- tocstop -->
 
-## General network connection attributes
+## Server and client attributes
 
-These attributes may be used for any network related operation.
-The `server.*` attributes describe properties of the server side of the network connection
-(usually the receiver of the initial SYN packet(s) of the TCP connection. For other protocols,
-the server is generally the responder in the network transaction),
-while the `client.*` properties describe the initiator of the connection or request.
+These attributes may be used to describe client and server in request-response communication.
+The `server.*` attributes describe properties of the server responding to a network request,
+while the `client.*` attributes describe the initiator of the request.
 
 In an ideal situation, not accounting for proxies, multiple IP addresses or host names,
-the `client.*` and `server.*` properties are the same on the client and server.
+the `server.*` attributes are the same on the client and server.
 
 ### Server attributes
 
@@ -74,7 +74,7 @@ if they do not cause breaking changes to HTTP semantic conventions.
 | `client.socket.port` | int | Immediate client port number | `35555` | Recommended |
 <!-- endsemconv -->
 
-### Common network attributes
+## Common network attributes
 
 > **Warning**
 > Attributes in this section are in use by the HTTP semantic conventions.
@@ -114,6 +114,38 @@ if they do not cause breaking changes to HTTP semantic conventions.
 | `unix` | Unix domain socket path |
 <!-- endsemconv -->
 
+### Source and destination attributes
+
+`source` and `destination` attributes describe network peers exchanging packets and usually populated together. They could also be populated along with `client.*` and `server.*` attributes.
+
+_Note: `source` and `destination` are applicable on packet level and should not be used to describe bi-directional network calls since each peer plays both `source` and `destination` roles._
+
+#### Source
+
+<!-- semconv source -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended |
+| `source.address` | string | Source address, fo example IP address or UNIX socket name. | `10.5.3.2` | Recommended |
+| `source.port` | int | Source port number | `3389`; `2888` | Recommended |
+
+**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format.
+<!-- endsemconv -->
+
+#### Destination
+
+Destination fields capture details about the receiver of a network exchange/packet.
+
+<!-- semconv destination -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended |
+| `destination.address` | string | Peer address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended |
+| `destination.port` | int | Peer port number | `3389`; `2888` | Recommended |
+
+**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format.
+<!-- endsemconv -->
+
 ### Network connection and carrier attributes
 
 <!-- semconv network-connection-and-carrier -->