Clarify some cases for http.host and http.client_ip. (#1890)

* Clarify some cases for http.host and http.client_ip.

* Fill in PR#.

CHANGELOG.md

@@ -33,6 +33,8 @@ release.
   - Add YAML definitions for grpc events.
 - Add `messaging.consumer_id` to differentiate between message consumers.
   ([#1810](https://github.com/open-telemetry/opentelemetry-specification/pull/1810))
+- Clarifications for `http.client_ip` and `http.host`.
+  ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890))
 
 ### Compatibility
 

semantic_conventions/trace/http.yaml

@@ -28,7 +28,13 @@ groups:
         type: string
         brief: >
             The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4).
-            When the header is empty or not present, this attribute should be the same.
+            An empty Host header should also be reported, see note.
+        note: >
+          When the header is present but empty the attribute SHOULD be set to
+          the empty string. Note that this is a valid situation that is expected
+          in certain cases, according the aforementioned
+          [section of RFC 7230](https://tools.ietf.org/html/rfc7230#section-5.4).
+          When the header is not set the attribute MUST NOT be set.
         examples: ['www.example.org']
       - id: scheme
         type: string
@@ -134,8 +140,18 @@ groups:
         brief: >
             The IP address of the original client behind all proxies, if
             known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)).
-        note: >
-            This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
+        note: |
+            This is not necessarily the same as `net.peer.ip`, which would
+            identify the network-level peer, which may be a proxy.
+
+            This attribute should be set when a source of information different
+            from the one used for `net.peer.ip`, is available even if that other
+            source just confirms the same value as `net.peer.ip`.
+            Rationale: For `net.peer.ip`, one typically does not know if it
+            comes from a proxy, reverse proxy, or the actual client. Setting
+            `http.client_ip` when it's the same as `net.peer.ip` means that
+            one is at least somewhat confident that the address is not that of
+            the closest proxy.
         examples: '83.164.160.102'
     constraints:
       - any_of:

specification/trace/semantic_conventions/http.md

@@ -58,10 +58,10 @@ Don't set the span status description if the reason can be inferred from `http.s
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes |
 | `http.url` | 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. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | No |
-| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | No |
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [2] | `www.example.org` | No |
 | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | No |
 | `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If and only if one was received/sent. |
-| `http.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | No |
+| `http.flavor` | string | Kind of HTTP protocol used. [3] | `1.0` | No |
 | `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No |
 | `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
 | `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
@@ -70,7 +70,9 @@ Don't set the span status description if the reason can be inferred from `http.s
 
 **[1]:** `http.url` 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/`.
 
-**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.
+**[2]:** When the header is present but empty the attribute SHOULD be set to the empty string. Note that this is a valid situation that is expected in certain cases, according the aforementioned [section of RFC 7230](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is not set the attribute MUST NOT be set.
+
+**[3]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.
 
 `http.flavor` MUST be one of the following or, if none of the listed values apply, a custom value:
 
@@ -179,7 +181,17 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
 
 **[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.
 
-**[2]:** This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
+**[2]:** This is not necessarily the same as `net.peer.ip`, which would
+identify the network-level peer, which may be a proxy.
+
+This attribute should be set when a source of information different
+from the one used for `net.peer.ip`, is available even if that other
+source just confirms the same value as `net.peer.ip`.
+Rationale: For `net.peer.ip`, one typically does not know if it
+comes from a proxy, reverse proxy, or the actual client. Setting
+`http.client_ip` when it's the same as `net.peer.ip` means that
+one is at least somewhat confident that the address is not that of
+the closest proxy.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required: