net.sock.peer.name

semantic_conventions/trace/general.yaml

@@ -6,7 +6,7 @@ groups:
     attributes:
       - id: transport
         type:
-          allow_custom_values: false
+          allow_custom_values: true
           members:
             - id: ip_tcp
               value: "ip_tcp"
@@ -27,6 +27,11 @@ groups:
               brief: 'Something else (non IP-based).'
         brief: >
           Transport protocol used. See note below.
+      - id: sock.peer.name
+        type: string
+        brief: >
+          Remote socket peer name.
+        examples: proxy.example.com
       - id: sock.peer.addr
         type: string
         brief: >

specification/trace/semantic_conventions/span-general.md

@@ -15,7 +15,7 @@ Particular operations may refer to or require some of these attributes.
   * [`net.*.name` attributes](#netname-attributes)
     + [`net.peer.name`](#netpeername)
     + [`net.host.name`](#nethostname)
-    + [Connecting over proxy](#connecting-over-proxy)
+    + [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)
@@ -38,6 +38,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
 | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | No |
+| `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | No |
 | `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)). [1] | `127.0.0.1`; `/tmp/mysql.sock` | No |
 | `net.sock.peer.port` | int | Remote socket peer port (if defined for the address family). | `16456` | Conditional [2] |
@@ -67,7 +68,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
 
 **[6]:** if `net.sock.host.addr` is set and `net.sock.family` has a notion of port
 
-`net.transport` MUST be one of the following:
+`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 |
 |---|---|
@@ -131,10 +132,12 @@ For `Unix` and `pipe`, since the connection goes over the file system instead of
 `net.peer.name` and `net.host.name` represent logical host names. Semantic conventions that refer to these attributes SHOULD
 specify what these attributes mean in their context.
 
-For IP-based communication, the name should be a DNS host name.
+Semantic conventions and instrumentations that populate both logical (`net.peer.name`, `net.host.name`) and socket-level (`net.sock.*.name`) attributes SHOULD only set socket-level attributes when they don't match logical ones. For example, when direct connection to the remote destination is established and when `net.peer.name` is populated, `net.sock.peer.name` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information.
 
 #### `net.peer.name`
 
+For IP-based communication, the name should be a DNS host name.
+
 `net.peer.name` should be the name of logical remote destination, e.g., `"example.com"` if connecting to an URL `https://example.com/foo`.
 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`).
 
@@ -152,11 +155,16 @@ For Unix domain socket, `net.sock.peer.addr` attribute represents destination na
 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.
 
-#### Connecting over proxy
+#### 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 intermediary address and port respectively. `net.sock.peer.name` SHOULD be set to intermediary DNS name if readily available.
+
+Instrumentations SHOULD NOT do DNS lookups to obtain `net.sock.peer.addr` or `net.sock.peer.name`. If intermediary information available to instrumentation can represent DNS name or address,
+it SHOULD NOT attempt parsing it and SHOULD set `net.sock.peer.name`.
 
-When connecting to the remote destination through a 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 proxy address and proxy port respectively.
+For example, [WebProxy in .NET](https://docs.microsoft.com/dotnet/api/system.net.webproxy.address) does not differentiate IP address and DNS name and HTTP instrumentations that don't have access to socket-level communication can only populate `net.sock.peer.name`. Instrumentations that have access to socket-level information, may be able to populate valid `net.sock.peer.addr` instead of or in addition to DNS name.
 
-Server instrumentations that use `net.host.name` and `net.host.port` SHOULD set them to logical local host; `net.sock.peer.addr` and `net.sock.peer.port` SHOULD be set to the proxy address.
+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