more nits

semantic_conventions/trace/general.yaml

@@ -143,27 +143,27 @@ groups:
     attributes:
       - id: address
         type: string
-        brief: 'Server hostname, can represent FQDN. If no available, matches socket or IP address'
+        brief: 'Logical server hostname, can represent FQDN. If no available, matches socket or IP address'
         examples: ['example.com']
       - id: port
         type: int
         brief: 'Server port number'
         examples: [80, 8080, 443]
       - id: nat.address
         type: string
-        brief: Proxy server FQDN. If not known, IP address should be used.
+        brief: Physical server address - hostname, IP, or unix domain socket name.
         requirement_level:
-          recommended: If communication is done via proxy.
-        examples: proxy.example.com
+          recommended: If different than `server.address`
+        examples: ['proxy.example.com', '10.5.3.2']
       - id: nat.ip
         type: string
-        brief: Proxy IP address.
+        brief: Physical server IP address.
         requirement_level:
-          recommended: Only if different than `server.nat.address`.
-        examples: ['127.0.0.1']
+          recommended: Only on client side and if different than `server.nat.address`.
+        examples: ['10.5.3.2']
       - id: nat.port
         type: int
-        brief: Proxy port.
+        brief: Physical server port.
         examples: 16456
 
   - id: client

semantic_conventions/trace/http.yaml

@@ -79,9 +79,10 @@ groups:
         note: >
           When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.address` MUST match
           URI port identifier, otherwise it MUST match `Host` header port identifier.
+      - ref: server.nat.address
+        note: Address of the connected peer such as proxy FQDN, proxy IP address, or, if connected directly, an IP address of the server
       - ref: server.nat.ip
       - ref: server.nat.port
-      - ref: server.nat.address
 
   - id: trace.http.server
     prefix: http
@@ -149,7 +150,7 @@ groups:
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header
-      - ref: server.nat.ip
+      - ref: server.nat.address
         requirement_level: opt_in
       - ref: server.nat.port
       - ref: client.address

specification/metrics/semantic_conventions/http-metrics.md

@@ -228,7 +228,7 @@ This metric is required.
 | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
 | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required |
-| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If communication is done via proxy. |
+| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address` |
 | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
 
 **[1]:** `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`.
@@ -264,7 +264,7 @@ This metric is optional.
 | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
 | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required |
-| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If communication is done via proxy. |
+| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address` |
 | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
 
 **[1]:** `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`.
@@ -300,7 +300,7 @@ This metric is optional.
 | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
 | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required |
-| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If communication is done via proxy. |
+| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address` |
 | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
 
 **[1]:** `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`.

specification/metrics/semantic_conventions/rpc-metrics.md

@@ -74,9 +74,9 @@ measurements.
 | [`network.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below |
 | [`network.type`](../../trace/semantic_conventions/span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: If and only if `server.nat.address` is set. |
 | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
-| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If communication is done via proxy. |
-| [`server.nat.ip`](../../trace/semantic_conventions/span-general.md) | string | Proxy IP address. | `127.0.0.1` | Recommended: If address is known to be an IP address. |
-| [`server.nat.port`](../../trace/semantic_conventions/span-general.md) | int | Proxy port. | `16456` | Recommended: [4] |
+| [`server.nat.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address` |
+| [`server.nat.ip`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address. | `10.5.3.2` | Recommended: If address is known to be an IP address. |
+| [`server.nat.port`](../../trace/semantic_conventions/span-general.md) | int | Physical server port. | `16456` | Recommended: [4] |
 | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Server port number | `80`; `8080`; `443` | Conditionally Required: See below |
 
 **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).

specification/trace/semantic_conventions/database.md

@@ -47,8 +47,8 @@ Some database systems may allow a connection to switch to a different `db.user`,
 | [`network.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [1] |
 | [`network.type`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [2] |
 | [`server.address`](span-general.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. |
-| [`server.nat.address`](span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If different than `server.address`. |
-| [`server.nat.port`](span-general.md) | int | Proxy port. | `16456` | Recommended |
+| [`server.nat.address`](span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address`. |
+| [`server.nat.port`](span-general.md) | int | Physical server port. | `16456` | Recommended |
 | [`server.port`](span-general.md) | int | Server port number | `80`; `8080`; `443` | Conditionally Required: [3] |
 
 **[1]:** If database type is in-process (`"inproc"`), recommended for other database types.

specification/trace/semantic_conventions/http.md

@@ -124,11 +124,11 @@ before any HTTP-redirects that may happen when executing the request.
 |---|---|---|---|---|
 | `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. |
 | [`server.address`](span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required |
-| [`server.nat.address`](span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If communication is done via proxy. |
-| [`server.nat.ip`](span-general.md) | string | Proxy IP address. | `127.0.0.1` | Recommended: Only if different than `server.nat.address`. |
-| [`server.nat.port`](span-general.md) | int | Proxy port. | `16456` | Recommended |
-| [`server.port`](span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
-| `url.full` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Required |
+| [`server.nat.address`](span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. [3] | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address` |
+| [`server.nat.ip`](span-general.md) | string | Physical server IP address. | `10.5.3.2` | Recommended: [4] |
+| [`server.nat.port`](span-general.md) | int | Physical server port. | `16456` | Recommended |
+| [`server.port`](span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] |
+| `url.full` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [7] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Required |
 
 **[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
 
@@ -141,11 +141,15 @@ before any HTTP-redirects that may happen when executing the request.
 If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then
 `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
 
-**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.address` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
+**[3]:** Address of the connected peer such as proxy FQDN, proxy IP address, or, if connected directly, an IP address of the server
 
-**[4]:** If not default (`80` for `http` scheme, `443` for `https`).
+**[4]:** Only on client side and if different than `server.nat.address`.
 
-**[5]:** `url.full` MUST NOT contain credentials passed via URL in form of `https://username:[email protected]/`. In such case the attribute's value should be `https://www.example.com/`.
+**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.address` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
+
+**[6]:** If not default (`80` for `http` scheme, `443` for `https`).
+
+**[7]:** `url.full` MUST NOT contain credentials passed via URL in form of `https://username:[email protected]/`. In such case the attribute's value should be `https://www.example.com/`.
 
 Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
 
@@ -236,8 +240,8 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
 | [`client.address`](span-general.md) | string | Immediate client address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended |
 | [`client.port`](span-general.md) | int | Immediate client port number | `35555` | Recommended |
 | [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
-| [`server.nat.ip`](span-general.md) | string | Proxy IP address. | `127.0.0.1` | Opt-In |
-| [`server.nat.port`](span-general.md) | int | Proxy port. | `16456` | Recommended |
+| [`server.nat.address`](span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Opt-In |
+| [`server.nat.port`](span-general.md) | int | Physical server port. | `16456` | Recommended |
 | [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
 | `url.path` | string | The request path component passed in a HTTP request line or equivalent. | `/users/12314` | Required |
 | `url.query` | string | The query component passed in a HTTP request line or equivalent. | `?q=ddds` | Required |

specification/trace/semantic_conventions/messaging.md

@@ -196,10 +196,10 @@ The following operations related to messages are defined for these semantic conv
 | [`network.protocol.name`](span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended |
 | [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [8] | `3.1.1` | Recommended |
 | [`network.type`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [9] |
-| [`server.address`](span-general.md) | string | Server hostname, can represent FQDN. If no available, matches socket or IP address [10] | `example.com` | Conditionally Required: If available. |
-| [`server.nat.address`](span-general.md) | string | Proxy server FQDN. If not known, IP address should be used. | `proxy.example.com` | Recommended: If different than `server.address`. |
-| [`server.nat.ip`](span-general.md) | string | Proxy IP address. | `127.0.0.1` | Recommended: If different than `server.nat.address`. |
-| [`server.nat.port`](span-general.md) | int | Proxy port. | `16456` | Recommended |
+| [`server.address`](span-general.md) | string | Logical server hostname, can represent FQDN. If no available, matches socket or IP address [10] | `example.com` | Conditionally Required: If available. |
+| [`server.nat.address`](span-general.md) | string | Physical server address - hostname, IP, or unix domain socket name. | `proxy.example.com`; `10.5.3.2` | Recommended: If different than `server.address`. |
+| [`server.nat.ip`](span-general.md) | string | Physical server IP address. | `10.5.3.2` | Recommended: If different than `server.nat.address`. |
+| [`server.nat.port`](span-general.md) | int | Physical server port. | `16456` | Recommended |
 
 **[1]:** If a custom value is used, it MUST be of low cardinality.